Compare commits

..
1526 Commits
Author SHA1 Message Date
sam 8cb76092b6 chore(release): v1.61.2
deploy / gate (push) Successful in 5m3s
Quality / check (push) Canceled after 12m5s
deploy / agent-image (push) Successful in 3m23s
deploy / dist-zip (push) Successful in 1m51s
deploy / archied-image (push) Successful in 3m6s
2026-11-08 06:30:16 +11:00
sam 49d7619ba3 fix(daemon): claim a requeued backlog without a poll wait per task
deploy / gate (push) Successful in 4m56s
Quality / check (push) Canceled after 6m11s
deploy / archied-image (push) Successful in 3m1s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
2026-11-08 06:24:54 +11:00
sam ae53e83ff3 chore(release): v1.61.1
Quality / check (push) Successful in 6m19s
deploy / archied-image (push) Successful in 3m0s
deploy / dist-zip (push) Successful in 2m41s
deploy / gate (push) Successful in 4m46s
deploy / agent-image (push) Successful in 3m16s
2026-11-08 06:04:33 +11:00
sam ef84e18f46 fix(ui): a new canvas workflow names the agent it runs as (#1622)
deploy / gate (push) Successful in 4m52s
Quality / check (push) Successful in 6m53s
deploy / agent-image (push) Successful in 11s
deploy / archied-image (push) Successful in 3m21s
deploy / dist-zip (push) Skipped
2026-11-08 05:49:40 +11:00
sam cf1be16763 fix(controlplane): repair a stored workflow collection that no longer validates (#1622) 2026-11-08 05:49:40 +11:00
sam cc8428643a fix(gatewayrpc): sniff the head of URL-only attachments (#1672)
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m41s
deploy / agent-image (push) Successful in 12s
Quality / check (push) Successful in 7m2s
deploy / archied-image (push) Successful in 3m37s
2026-11-08 05:40:27 +11:00
sam 70251ff3ce chore(release): v1.61.0
deploy / gate (push) Successful in 4m44s
Quality / check (push) Successful in 7m16s
deploy / archied-image (push) Successful in 3m0s
deploy / agent-image (push) Successful in 3m35s
deploy / dist-zip (push) Successful in 2m39s
2026-11-08 04:59:28 +11:00
sam 76dc34a17c fix(distribution): trust the rotated catalogue signing key (#1790)
Quality / check (push) Canceled after 5m9s
deploy / archied-image (push) Successful in 2m58s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m32s
deploy / agent-image (push) Successful in 12s
2026-11-08 04:54:32 +11:00
sam a6a0c7c11e fix(archied): say why the canary can't compare migrations
deploy / gate (push) Successful in 4m41s
deploy / archied-image (push) Successful in 2m57s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 6m27s
2026-11-08 03:05:29 +11:00
sam f759387eb7 chore: ignore the fleet run directory 2026-11-08 02:48:29 +11:00
sam 21b3591da1 fix(e2e+ui): e2e checks for the audit's failure classes, and the gaps they caught (#1767)
deploy / gate (push) Successful in 4m48s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 3m31s
Quality / check (push) Successful in 6m11s
loading-errors now forces each list API (/api/tasks, /api/captures,
/api/event-types, /api/tokens, /api/access/policies) to fail and asserts
the page shows its error surface, never its empty-state copy.
accessibility gains two static-route sweeps: every input/textarea/select/
button must have an accessible name, and every keyboard focus stop's
indicator (ring var, outline, shadow or focus border) must clear 3:1
against the background behind it. phone-overflow sweeps every static
route at 390x844 for horizontal scroll. The sweeps caught real gaps,
fixed here: the DurationInput amount input had no accessible name and
its unit select no focus indicator, and TabsContent and CodeBlockContent
were focusable with outline-none and no ring. The stale 'Sections' list
selector now matches the nav landmark.
2026-11-07 17:08:10 +11:00
sam e9937ded6b fix(ui): a failed answer keeps the question card and its filled-in answer (#1728)
Quality / check (push) Successful in 9m2s
deploy / gate (push) Successful in 4m49s
deploy / archied-image (push) Successful in 3m25s
deploy / dist-zip (push) Skipped
deploy / agent-image (push) Successful in 11s
answerAsk now clears the pending question only after api.chatAnswer
accepts it, and resolves whether it did. On failure the new askError ref
carries the message, shown on the card as a ReadError whose Retry resends
the last answer; ChatAskCard keeps the typed reply until acceptance and
routes every choice button through the same path, and the questionnaire
submits through the card so its answers are retryable too. askError resets
on turn start, on a new ask, and on conversation switch.
2026-11-07 01:23:10 +11:00
sam bd1acdd0cc fix(ui): switching conversation detaches the running turn (#1729)
Quality / check (push) Canceled after 23s
deploy / archied-image (push) Successful in 3m24s
deploy / gate (push) Successful in 4m47s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
selectSession now bumps a session epoch and aborts the in-flight stream
before switching, and the transcript read is applied only if the session is
still current. sendMessage captures the epoch at turn start: a detached turn
stops reading, cancels the reader, and writes no messages, streamingTurn or
session id; only the turn still owning the abort controller clears isSending,
so it cannot unlock the composer for a turn running in the new conversation.
2026-11-07 01:20:49 +11:00
sam a2c6341544 fix(ui): policy form opens blank on New, id read-only when editing, dirty draft asks first (#1730)
Quality / check (push) Canceled after 4m48s
deploy / archied-image (push) Successful in 3m26s
deploy / agent-image (push) Successful in 11s
deploy / gate (push) Successful in 4m52s
deploy / dist-zip (push) Skipped
New policy now resets the draft instead of reusing the open policy's, so
Save cannot overwrite the policy that happens to be open. The id input is
readonly while editing a persisted policy, so a rename can no longer write
a second policy. New/Edit/Cancel route through openForm, which asks for
confirmation before discarding a dirty draft.
2026-11-07 01:16:48 +11:00
sam cb3372ac76 fix(ui): terminal palette is theme tokens, switches live (#1739)
deploy / archied-image (push) Successful in 3m22s
Quality / check (push) Canceled after 3m23s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m51s
--terminal-bg/fg/cursor/selection are defined per theme in style.css
(dark keeps the deep well, light gets a paper inset) and exposed as
bg-terminal. Both xterm surfaces (SetupTerminal, SandboxView) read them
via lib/terminalTheme and re-apply on every data-theme flip, so the
theme switch is live; the raw #0b0f14/#e6edf3/#264f78 hex is gone.
2026-11-07 01:13:41 +11:00
sam 48e605a545 fix(ui): dead tokens replaced or deleted — text-ok, --radius-lg, real surface (#1740)
deploy / agent-image (push) Successful in 11s
Quality / check (push) Successful in 6m33s
deploy / gate (push) Successful in 4m49s
deploy / archied-image (push) Successful in 3m22s
deploy / dist-zip (push) Skipped
text-success was not a token (now text-ok) in ChatToolCall and BindEvent;
var(--radius) is undefined (now var(--radius-lg)) in input-group and Sonner;
Sonner's hsl(var(--popover) / 0.9) wrapped a hex (now a plain hex); the
undefined cn-font-heading class is deleted from the nine title components.
2026-11-07 01:06:42 +11:00
sam 9a4e59f0e0 fix(ui): tab, toggle, input and idle-text contrast meet their targets (#1741)
Quality / check (push) Canceled after 3m37s
deploy / gate (push) Successful in 4m48s
deploy / archied-image (push) Successful in 3m24s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Inactive tab labels use text-fg-muted instead of foreground/60 (was
4.1:1). The selected toggle/toggle-group segment gains a sage-deep ring
(5.3:1 light, 3.9:1 dark) instead of the near-invisible muted fill.
--input rises to 3.6:1 (light) and 3.5:1 (dark) on the card; dark --idle
rises to 5.1:1 on --accent. Values computed against the style.css tokens.
2026-11-07 01:03:19 +11:00
sam 820beda72f fix(ui): empty states wait for the first read to settle (#1742)
Quality / check (push) Successful in 6m42s
deploy / gate (push) Successful in 4m49s
deploy / archied-image (push) Successful in 3m27s
deploy / dist-zip (push) Skipped
deploy / agent-image (push) Successful in 11s
Skills, curators, QuickTask's workflow list, the alerts bell and the
extensions catalogue now show a loading state until the first read
settles, then the data, the error, or the empty state. Draft-backed lists
(agent profiles, playbooks, credential bindings) show their empty state
only once the draft exists, not beside the load error.
2026-11-07 00:54:25 +11:00
sam c6f70de82d fix(ui): settings pages show a skeleton or the error until their draft loads (#1743)
Quality / check (push) Successful in 7m32s
deploy / archied-image (push) Successful in 3m27s
deploy / agent-image (push) Successful in 11s
deploy / gate (push) Successful in 4m59s
deploy / dist-zip (push) Skipped
New settings/KindGate renders the store's per-kind loading/error state
where the form would be: a skeleton while loading, ReadError with Retry
on a failed read. Wired into Tools, SystemModels, SystemRepos,
SchedulingPolicy, ContainerRuntime, OrgAlerts, Instructions, Plugins,
SystemTasks, UpdateSettings, IdentityGrants, OrgModels, Channels and
Authentication pages, which no longer render blank until the draft
exists.
2026-11-07 00:42:28 +11:00
sam f37f6e2453 fix(ui): one error presentation with Retry across the dashboard (#1744)
Quality / check (push) Successful in 6m56s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m58s
deploy / agent-image (push) Successful in 11s
deploy / archied-image (push) Successful in 3m28s
New components/ui ReadError (destructive Alert + message + optional Retry)
is now the single read-error presentation, used by Versions, Services,
Canary, OrgAccess, Denials, Tokens, Audit, Extensions, Harness and the
Status page (one page-level error instead of one per card). PanelError is
the same alert for task panels, and TasksState's error kind, the attempts
panel and the task-log pane all offer Retry. Org policy save errors sit
beside the Save button instead of at the page top.
2026-11-07 00:33:49 +11:00
sam f7a999e317 fix(ui): failed task pages keep rows with an inline error; refreshes don't flash (#1745)
deploy / archied-image (push) Successful in 3m28s
deploy / agent-image (push) Successful in 11s
Quality / check (push) Successful in 6m31s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m49s
A failed Load more or live refresh sets moreError beside the Load more
button instead of replacing the table; only a first-load failure takes
the table down. The no-match empty state says search covers loaded rows
when more pages exist. refreshAll keeps attempts/events (keep=true) and a
failed task-list read keeps the last known list, so panels no longer
flash to loading on every live update.
2026-11-07 00:25:36 +11:00
sam 45494d5b43 fix(ui): logs page error no longer flickers, live entries pruned, unavailable clears (#1746)
Quality / check (push) Canceled after 2m59s
deploy / gate (push) Successful in 4m51s
deploy / dist-zip (push) Skipped
deploy / agent-image (push) Successful in 11s
deploy / archied-image (push) Successful in 3m28s
readError is cleared only by a successful read instead of at the start of
every 5 s refresh, so an outage shows a steady error beside the stale
lines. liveEntries is pruned past 1500 (the list shows 1000) so the map
cannot grow unbounded. streamState leaves "unavailable" as soon as live
entries flow again.
2026-11-07 00:22:40 +11:00
sam 9ca9545847 fix(ui): alert state is shared; a failed dismiss keeps the alert and says why (#1747)
deploy / archied-image (push) Successful in 3m30s
deploy / agent-image (push) Successful in 12s
Quality / check (push) Canceled after 3m8s
deploy / gate (push) Successful in 4m51s
deploy / dist-zip (push) Skipped
use-alerts.ts now holds the alerts/failed refs at module scope (wired once),
so the bell and the dashboard card see the same list. dismiss removes the
alert only after the server confirms; on failure it stays and the reason
shows in the bell. dismissAll reports any rejection and reloads.
2026-11-07 00:19:31 +11:00
sam fa14e7da80 fix(ui): chat failures are shown where they happen and leave the real state (#1748)
deploy / gate (push) Successful in 4m47s
deploy / agent-image (push) Successful in 11s
Quality / check (push) Canceled after 1m18s
deploy / archied-image (push) Successful in 3m27s
deploy / dist-zip (push) Skipped
Mic permission failure shows an inline alert; setModel only switches on
server confirmation and reverts + reports in the transcript on failure;
a failed session refresh after a turn no longer becomes a retryable turn
error; a voice clip during a turn queues instead of dropping; blocked
localStorage falls back to a per-load channel id; a failed install offers
Retry/Not now again; rename/branch use a labelled Dialog instead of
window.prompt; a failed cancel is reported; a stopped turn no longer
blocks transcript reloads.
2026-11-07 00:17:44 +11:00
sam 12eea5eee3 fix(ui): destructive actions confirm via AlertDialog, naming the item (#1749)
deploy / gate (push) Successful in 4m49s
deploy / agent-image (push) Successful in 12s
deploy / archied-image (push) Successful in 3m29s
deploy / dist-zip (push) Skipped
Quality / check (push) Canceled after 7m10s
Delete policy, remove member, revoke token, remove passkey and delete
source now open the shared AlertDialog confirmation that names the item,
matching the binding/mapping/event-type deletes that already confirmed.
2026-11-07 00:11:16 +11:00
sam ef623f6c68 fix(ui): rows keep table semantics; first-cell link/button is the focus target (#1750)
deploy / gate (push) Successful in 4m59s
deploy / archied-image (push) Successful in 3m29s
Quality / check (push) Successful in 6m40s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
DataTable, ActivityRow, LiveActivityCard's group row and CaptureRow no
longer put role=link/button, tabindex or aria-label on the <tr>. The row
keeps its mouse click handler; the first cell carries a real RouterLink
(DataTable rowLink) or button with the accessible name, so keyboard and
screen-reader users get a focus target and rows keep row/cell semantics.
The live-activity group row's disclosure button and open button are now
siblings, not nested.
2026-11-07 00:00:41 +11:00
sam ee2d19d011 fix(ui): real heading structure and a nav landmark for the sidebar (#1751)
deploy / gate (push) Successful in 4m52s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Quality / check (push) Canceled after 4m2s
deploy / archied-image (push) Successful in 3m30s
CardTitle and EmptyTitle take an as prop (default h2) and render through
component :is, so card and empty-state titles are headings; Section passes
as="h2" under the page's h1. The sidebar menu list now sits in
<nav aria-label="Sections">.
2026-11-06 23:56:34 +11:00
sam 53c6b3e413 fix(ui): disabled reasons and truncated values reachable without hover (#1752)
Quality / check (push) Canceled after 4m7s
deploy / archied-image (push) Successful in 3m32s
deploy / gate (push) Successful in 4m49s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
Disabled New run and task-row buttons now carry their reason in a Tooltip
on a focusable wrapper (disabled buttons cannot take focus), and New run
says when the task list has not loaded. Truncated values (binding filter
and failure reason, activity rows, live alerts, event-type rule summaries,
source URLs, mapping field paths) are focusable spans whose full text is in
a Tooltip. The org switcher has distinct loading ('…' tile, 'Loading…')
and failed ('!' tile, 'Organisations unavailable') states.
2026-11-06 23:52:25 +11:00
sam d58125c0bc fix(ui): combobox pattern for the slash palette, named palette input, bound labels (#1753)
Quality / check (push) Canceled after 4m45s
deploy / gate (push) Successful in 4m48s
deploy / archied-image (push) Successful in 3m28s
deploy / dist-zip (push) Skipped
deploy / agent-image (push) Successful in 12s
The composer textarea is now role=combobox with aria-expanded,
aria-controls and aria-activedescendant wired to the slash palette's
listbox ids. CommandInput has an accessible name. FieldLabels without a
control beside them are bound: for/id on selects, inputs, switches and
duration inputs across channels, curators and schedules pages, and
role=group + aria-labelledby/aria-label on the TagsInput, secret-ref and
rule row groups.
2026-11-06 23:47:41 +11:00
sam 029198ff61 fix(ui): generation-guard the remaining async loads and polls (#1754)
Quality / check (push) Canceled after 7m38s
deploy / gate (push) Successful in 4m51s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 3m26s
deploy / agent-image (push) Successful in 12s
Schedules, command palette, skills, repos, services, secret engines,
captures, event types, curators, sources, channels, mappings (list and
preview), dispatch links and workflow history now capture a generation
at request start and drop their writes unless still latest — the guard
logs/state.ts already used. A failed schedules poll keeps the last good
rows beside the inline error instead of replacing the table, and a
failed skills/secret-engines poll no longer clears the list.
2026-11-06 23:40:03 +11:00
sam 0b08fc5242 fix(ui): harness setup terminal reports the real failure and can be reopened (#1755)
Quality / check (push) Canceled after 5m18s
deploy / archied-image (push) Successful in 3m29s
deploy / gate (push) Successful in 4m48s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
A websocket that never opened stays "failed" — onclose no longer
overwrites it with "closed", so the terminal says "Could not open the
setup terminal." instead of "The terminal session ended.". The terminal
emits ended when its session closes, and HarnessPage resets terminalOpen
on it (plus a Close terminal button), so reopening starts a fresh session
instead of requiring a page reload. The harness load failure now has a
Retry button.
2026-11-06 23:34:38 +11:00
sam 93609c7ab3 fix(ui): eleven small dashboard state bugs from the audit (#1756)
deploy / gate (push) Successful in 4m50s
deploy / agent-image (push) Successful in 11s
Quality / check (push) Canceled after 3m13s
deploy / archied-image (push) Successful in 3m28s
deploy / dist-zip (push) Skipped
Install disables when no installable snapshot; retention hours is empty
until loaded instead of showing 0; the audit Action field carries all
comma-separated actions; saving a view over an existing name asks first;
"Password changed" is a notice, not a destructive alert; "Sign in
again" appears only on an expired session (classifyActionError) on
account, authentication and create-account; sign-out failure sets the
store error instead of an unhandled rejection; the workflow identity
select shows the seeded agent without writing it into the YAML;
unparseable durations show an inline error instead of snapping back;
CardAccordion keys items by id; curator add() explains a no-op.
2026-11-06 23:31:47 +11:00
sam 461d3dc1f7 fix(ui): phone-width overflows in the audit's flagged rows, with an e2e check (#1757)
deploy / archied-image (push) Successful in 3m23s
deploy / agent-image (push) Successful in 11s
Quality / check (push) Successful in 6m36s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m54s
Grants rows and toggle groups wrap with a smaller phone label; the token
form wraps and its input flexes; the sources name column caps at full
width and its action buttons wrap; the rule-editor condition row wraps
with a full-width phone select; the payload tree indents less and breaks
long JSON leaves; the topbar instance badge truncates; org agent rows
keep Assign inline and move Rename/Suspend/Retire into a MoreMenu. New
e2e check phone-overflow.cjs visits these views at 390x844 with seeded
data and asserts no horizontal scroll.
2026-11-06 23:23:16 +11:00
sam 94f79177a2 fix(ui): adopt the type scale across components/ui and pages (#1758)
deploy / archied-image (push) Successful in 3m20s
deploy / gate (push) Successful in 4m53s
Quality / check (push) Successful in 6m42s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
components/ui and the pages now use only the style.css scale:
text-[0.8rem]→text-label, text-[0.625rem]→text-micro, text-base/text-sm→
text-label (rows and controls), text-xs→text-caption (captions and
secondary text), text-lg/text-xl/text-2xl→text-title (panel and page
titles). Rendered markdown (ChatMarkdown/ChatInline/markdown.ts) keeps
Tailwind steps as the issue allows. 196 files, class-token swaps only.
2026-11-06 23:07:46 +11:00
sam 9169e9db09 fix(ui): hand-rolled cards, headings, captions and empties use components/ui (#1759)
deploy / archied-image (push) Successful in 3m24s
deploy / gate (push) Successful in 4m50s
Quality / check (push) Canceled after 4m48s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Captions move from text-xs to the text-caption type-scale token across
the workflow/bind/schedule editors and curator card. The task page title
uses PageHeader's h1 classes. Hand-rolled boxes become Card (token
reveal, recovery code, pending extension update) or CodeView (install
progress); the startup-settings key/value table becomes MetadataList;
the harness empty row becomes TableEmpty; 'No tokens/dispatches/inputs/
removed' states become Empty; the step-editor problem line becomes a
destructive Alert. The risky-row danger tint in ToolsPage and
SystemReposPage now uses SettingRow tone="danger" instead of a
hand-written before: overlay (DANGER_ROW deleted).
2026-11-06 23:03:10 +11:00
sam 0d0cd09124 fix(ui): known lists use Select/TagsInput fed by the server catalogue (#1760)
deploy / gate (push) Successful in 4m36s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 3m17s
Quality / check (push) Successful in 8m37s
Token lifetimes use Select instead of NativeSelect. Credential bindings
pick service from the store's credentialServices and organisation from
the org list (empty = default, via a sentinel). Curator and agent-profile
tools are TagsInput instead of comma text; curator model is a Select of
the configured providers' models from /api/config's catalog. Org and
system model pages pick provider class from the catalog's classes, and
SystemModelsPage's local CLASSES list is deleted. Chat model choice is a
Select of the server-served model list instead of a button row.

Left as free text because no server source exists: policy object kind,
curator memory engine, update channel labels, connection type default,
container default, step titles (x-step-types carries no titles).
2026-11-06 22:51:21 +11:00
sam 0dc5bf9a9b fix(ui): times honour the Appearance zone, one duration formatter everywhere (#1761)
Quality / check (push) Successful in 6m44s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 3m44s
deploy / gate (push) Successful in 4m54s
lib/format.ts gains shortTime(value, zone) and becomes the home of the
single duration() formatter (moved from timeline-event.ts, which
re-exports it so the stage rail and duration.test.ts are unchanged).
LogTable's time column, audit's From/To chips and chat session titles now
format in the zone chosen under Appearance instead of the browser's.
StepNode, schedule runDuration, labels formatMs and ChatToolCall all
delegate to duration(), removing the "12ms" vs "12 ms" vs "under 1 s"
split.
2026-11-06 22:21:45 +11:00
sam ca107f6977 fix(ui): failed draft save is retried, then shown — never dropped silently (#1731)
persistDraft retried only while draftState.saving was true, but
settings.replace clears saving in its finally before resolving false, so
the retry branch could never run and a failed putDraft vanished. It now
retries on a bounded schedule (5 attempts, 500ms apart) regardless of the
saving flag, and on final failure sets localError so the editor's alert
says the draft was not saved while the edit stays in the editor. The
alert also reads the draft store's own error (workflows.draftState.error)
instead of only the definitions store's.
2026-11-06 22:09:56 +11:00
sam 4dad1415e6 fix(ui): workflow reads keep their error instead of showing empty (#1732)
Triggers: a failed bindings/schedules read surfaces as an error with
Retry in TriggerSettings instead of "Manual runs only." Run stages: a
failed attempts read sets stagesError, shown with Retry above the canvas
instead of a bare canvas. Bind form: failed reads show an error with
Retry rather than empty pickers, and save refuses to mappingUpdate an
existing mapping unless the bindings list actually loaded. History: a
failed revisions read shows the error with Retry in the revision list,
and "No recorded changes" appears only after a successful read.
2026-11-06 22:06:25 +11:00
sam 5bf0a696c6 fix(ui): failed reads show an error with Retry, not an empty view (#1733)
Chat: a failed conversation load sets sessionError, shown in the
transcript with Retry instead of the empty invitation (it no longer goes
to statusText in the settings popover). Command palette: failed task or
workflow reads render a "Couldn't load … — Retry" item in that group.
Denials: the table no longer shows "No denials recorded" under an
error. Mapping form: failed captures/event-types reads show an error row
with Retry instead of "No captured events yet." or a silently empty
select. Channels: a failed status read keeps the last badges and shows
an error with Retry. Sources: read failures are separate from write
failures, shown with Retry, and a loaded-but-empty list gets an empty
state.
2026-11-06 22:01:03 +11:00
sam 7a8d948fcb fix(ui): drop stale async responses with a generation guard (#1734)
TasksPage load/loadMore, use-task-run keyedLoad, TaskLogs loadOlder and
EventsPage loadCounts now each capture a generation at request start and
drop their writes unless they are still the latest request, the same
guard logs/state.ts already uses. dropCaches also stales every in-flight
keyed read, so a 30s timeout's null can no longer overwrite a newer
successful response, and the task-log pager no longer writes a page
fetched under the old attempt or filter.
2026-11-06 21:52:55 +11:00
sam d90f7d48d0 fix(ui): step card header is a keyboard-operable button, Edit in its menu (#1735)
The step header in StepNode.vue was a div with @click and no role, so a
step could not be opened from the keyboard, and Edit existed only in the
right-click canvas menu. The header now renders as a real <button> (with
aria-expanded) whenever the step can toggle, so Tab/Enter/Space open it;
while renaming it stays a div so the rename input is not nested inside a
button. The actions menu trigger moved to an absolute overlay at the
card's top-right (same spot as before, with a matching spacer in the
header row) and gained an Edit item that toggles the step, matching the
canvas context menu.
2026-11-06 21:48:55 +11:00
sam c5a43f21aa fix(ui): accessible names on fields that had only placeholders (#1736)
Step editor fields (lead, compact rows, long/YAML textareas and the
compact boolean switch), the org policy editor (policy id, level,
workspace id, object kind/id, Cedar textarea), the binding constant
value input, the log search and the channel tags inputs now each carry
an aria-label. On TagsInput the aria-label moved from the root div,
where screen readers never reach it, onto the actual TagsInputInput.
2026-11-06 21:43:23 +11:00
sam d3fbb0842f fix(ui): focus rings at full strength for 3:1 contrast (#1737)
The shared components used focus-visible:ring-ring/50 (and the base
outline-ring/50), which measured 2.1:1 on light and 2.4:1 on dark --
under the 3:1 WCAG 2.4.11/1.4.11 requires. All ring-ring and outline-ring
tokens in ui/src now render at full strength (5.3:1 light, 5.7:1 dark),
matching the :focus-visible outline floor in style.css.
2026-11-06 21:39:37 +11:00
sam dafd426316 fix(ui): startup failure is a centred panel that retries on its own (#1738)
When /api/auth/status fails, App.vue now shows a centred card with the
logo, a plain 'Can't reach Archie' statement and the detail in a
destructive Alert (role=alert), and retries the read every 5s until it
succeeds instead of offering only a manual Retry link. errorMessage in
api.ts only reads text/plain bodies, so a proxy's HTML error page no
longer passes through as the detail; other content types fall back to
the status line.
2026-11-06 21:36:17 +11:00
sam bec374aa92 ci(quality): stop installing ripgrep and setting sysctl from the gate (#1710)
The check job now runs on the archie-quality self-hosted runner under an
unprivileged user, so the sudo apt-get install and sudo sysctl steps fail,
exactly as the deploy gate did before 3b372b4a. Both are host provisioning:
ripgrep is installed on the runner host and the userns restriction belongs in
sysctl.d. The namespace check stays, without sudo.
2026-11-06 21:30:33 +11:00
sam 85b21578d8 ci(release): name the missing DEPLOY_TOKEN before checkout, and list what a mirror needs
Quality / check (push) Successful in 3m46s
deploy / gate (push) Successful in 4m29s
deploy / archied-image (push) Successful in 2m53s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
Refs #1788
2026-11-05 00:33:18 +11:00
sam 03c25e7214 docs(workflow): say repo.commit never runs the checkout's git hooks
deploy / gate (push) Successful in 4m45s
deploy / archied-image (push) Successful in 3m0s
deploy / agent-image (push) Successful in 12s
Quality / check (push) Successful in 3m44s
deploy / dist-zip (push) Skipped
Refs #1792
2026-11-05 00:26:20 +11:00
sam c30624a59e feat(workflow): a handoff starts a separate linked run of the next workflow (#1791)
Quality / check (push) Successful in 4m12s
deploy / gate (push) Successful in 4m42s
deploy / agent-image (push) Successful in 11s
deploy / archied-image (push) Successful in 3m13s
deploy / dist-zip (push) Skipped
2026-11-03 20:56:03 +11:00
sam 3cf025fb4a fix(worktree): mirror fetch follows moved tags and rewritten branches
Quality / check (push) Successful in 6m46s
deploy / gate (push) Successful in 4m35s
deploy / agent-image (push) Successful in 12s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 2m55s
2026-11-03 10:00:04 +11:00
sam 81b784876b fix(ui): live task updates refresh in place instead of flashing the loading state
Quality / check (push) Successful in 3m52s
deploy / archied-image (push) Successful in 3m14s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m33s
2026-11-03 09:51:43 +11:00
sam 6c42f64bfa chore(release): v1.60.0
deploy / archied-image (push) Successful in 2m52s
Quality / check (push) Canceled after 18s
deploy / gate (push) Successful in 4m39s
deploy / agent-image (push) Successful in 3m21s
deploy / dist-zip (push) Successful in 1m47s
2026-11-03 09:51:30 +11:00
sam d74216c6b7 docs(changelog): curator issue tools (#1770)
Quality / check (push) Successful in 4m3s
deploy / archied-image (push) Successful in 2m49s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m42s
2026-11-03 09:43:45 +11:00
sam 0b7ce448ab fix(e2e): checks follow the sidebar navigation; trim stray button and caption whitespace (#1789)
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m36s
deploy / archied-image (push) Successful in 3m16s
Quality / check (push) Successful in 3m52s
2026-11-03 09:35:19 +11:00
sam 2fb8c09a00 refactor(webui): extract the workflows module (#1778)
deploy / gate (push) Successful in 4m37s
deploy / archied-image (push) Successful in 2m51s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 4m23s
2026-11-03 08:39:40 +11:00
sam 0442f1849f refactor(webui): extract the audit module and its export guards (#1778)
deploy / gate (push) Successful in 4m33s
deploy / archied-image (push) Successful in 2m52s
deploy / agent-image (push) Successful in 11s
Quality / check (push) Canceled after 1m17s
deploy / dist-zip (push) Skipped
2026-11-03 08:38:22 +11:00
sam cf049797b0 refactor(webui): extract the schedules and alerts modules (#1778)
deploy / agent-image (push) Successful in 12s
deploy / gate (push) Successful in 4m33s
deploy / dist-zip (push) Skipped
Quality / check (push) Canceled after 1m5s
deploy / archied-image (push) Successful in 2m48s
2026-11-03 08:37:15 +11:00
sam 18e6fe6af6 refactor(webui): extract the chat module and its ask/file state (#1778)
deploy / gate (push) Successful in 4m35s
Quality / check (push) Canceled after 1m5s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 2m48s
2026-11-03 08:36:09 +11:00
sam e8a84d3e41 refactor(webui): extract the control-plane and logs modules (#1778)
deploy / gate (push) Successful in 4m31s
deploy / dist-zip (push) Skipped
Quality / check (push) Canceled after 1m17s
deploy / archied-image (push) Successful in 2m49s
deploy / agent-image (push) Successful in 11s
2026-11-03 08:34:51 +11:00
sam c5f4541cbf refactor(webui): extract the access policies and denials module (#1778)
Quality / check (push) Canceled after 1m5s
deploy / gate (push) Successful in 4m35s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 2m49s
deploy / agent-image (push) Successful in 12s
2026-11-03 08:33:46 +11:00
sam 369e5038ca refactor(webui): extract the identities and tokens module (#1778)
deploy / archied-image (push) Successful in 2m52s
deploy / agent-image (push) Successful in 10s
deploy / dist-zip (push) Skipped
Quality / check (push) Canceled after 1m9s
deploy / gate (push) Successful in 4m34s
2026-11-03 08:32:44 +11:00
sam 66862a1bab refactor(webui): extract the orgs resource module (#1778)
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 4m2s
deploy / gate (push) Successful in 4m39s
deploy / archied-image (push) Successful in 2m51s
deploy / agent-image (push) Successful in 11s
2026-11-03 08:28:36 +11:00
sam 25dcdb2d19 refactor(webui): extract the extensions resource module (#1778)
Quality / check (push) Successful in 5m1s
deploy / archied-image (push) Successful in 2m46s
deploy / agent-image (push) Successful in 10s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m35s
2026-11-03 08:22:02 +11:00
sam 1830a89898 refactor(webui): extract the harness resource module (#1778)
Quality / check (push) Successful in 3m56s
deploy / agent-image (push) Successful in 12s
deploy / gate (push) Successful in 4m34s
deploy / archied-image (push) Successful in 2m55s
deploy / dist-zip (push) Skipped
2026-11-03 08:17:12 +11:00
sam 6e718e165a feat(curator): issue_list and issue_create tools via the daemon (#1770)
deploy / agent-image (push) Successful in 12s
deploy / gate (push) Successful in 4m30s
deploy / archied-image (push) Successful in 2m50s
Quality / check (push) Successful in 4m6s
deploy / dist-zip (push) Skipped
2026-11-03 08:12:05 +11:00
sam 0a37b551f5 refactor(webui): extract the tasks resource module (#1778)
Quality / check (push) Successful in 3m47s
deploy / agent-image (push) Successful in 10s
deploy / gate (push) Successful in 4m32s
deploy / archied-image (push) Successful in 2m51s
deploy / dist-zip (push) Skipped
2026-11-03 08:06:56 +11:00
sam 864b87faa6 refactor(webui): extract event-types, mappings and sources modules (#1778)
deploy / gate (push) Successful in 4m29s
Quality / check (push) Successful in 3m52s
deploy / archied-image (push) Successful in 2m48s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Same pattern as the bindings pilot: eventTypesAPI (registers unconditionally,
list answers enabled:false without a store), mappingsAPI and sourcesAPI
(constructed only when their store is configured, 503 stub otherwise).
Shared helpers unsignedSources/recentRefusals/listedIn stay on Server; the
dispatch-ledger handler stays shared for captures/tasks. task check green.
2026-11-03 07:42:50 +11:00
sam d55d8580cf refactor(webui): extract the bindings resource module (#1778)
Pilot for one-module-per-resource: bindingsAPI owns the /api/bindings*
routes and their handlers, constructed only when the binding store is
configured; a 503 stub mounts the same routes otherwise, preserving the
old not-configured answers. Handlers move off *Server unchanged in
behavior; the shared dispatch-ledger handler stays on Server for the
captures/tasks routes. task check green.
2026-11-03 07:01:12 +11:00
sam 63229d1711 refactor(storecontract): assert every store interface at its implementation (#1781)
Complete the var _ storecontract.X = (*T)(nil) sweep so each of the 31
contract interfaces is compiler-checked against at least one adapter:
postgres.Store (19), postgres.EDA (11, consolidated into edastore.go),
staterpc.Client (29). Removes the scattered single-line assertions from
harness_secrets.go, edastore_eventtypes.go, sources.go, run_credentials.go.
task check green.
2026-11-03 06:24:09 +11:00
sam 56044476fc chore(release): v1.59.0
deploy / archied-image (push) Successful in 2m45s
deploy / dist-zip (push) Successful in 2m35s
deploy / gate (push) Successful in 4m21s
deploy / agent-image (push) Successful in 3m15s
Quality / check (push) Successful in 3m53s
2026-11-03 06:15:09 +11:00
sam 796bfd0045 docs(changelog): forge extensions gain CreateIssue
Quality / check (push) Successful in 7m12s
deploy / gate (push) Successful in 5m16s
deploy / archied-image (push) Successful in 3m2s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
2026-11-03 02:43:25 +11:00
sam abcb72a76a feat(curator): dry-run self-intake pass with run inspection tools (#1770)
Curators could only reach the workflow/integration tools; there was no way
to survey task runs. Adds run_list/run_events to the shared registry
(guarded as read on task kind), attaches the instance's acting principal
to curator model calls so guarded tools authorize, and records a pass's
final text as a pass.summary action so the report is inspectable. Ships a
dry-run self-intake definition in dev.toml/config.example.toml declaring
only those two tools, so it cannot file issues yet.
2026-11-03 02:35:06 +11:00
sam 443a7a501b refactor(storecontract): split the store contract into topical files (#1781)
Pure move: one 624-line storecontract.go becomes storecontract.go
(package doc + composed TaskStore), task.go, capture.go, binding.go,
mapping.go, source.go, status.go, resource.go, credentials.go and
errors.go. The package remains the single seam; no declaration changed
(verified line-identical against HEAD). task check green.
2026-11-03 02:27:57 +11:00
sam 88e86776e8 feat(forge): add CreateIssue to the forge contract (#1770)
deploy / archied-image (push) Successful in 2m54s
Quality / check (push) Successful in 4m10s
deploy / gate (push) Successful in 4m43s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Issue-level writes could comment and close but not open an issue, so no
curator or workflow stage can file its own work yet. Adds the rpc to
proto/forge/v1, regenerates the contracts, and threads it through the
domain interface, forgerpc client/server (comment permission, like
CloseIssue), forgeext, and the archipelago SDK + gitea/github plugins.
2026-11-03 02:04:56 +11:00
sam e10bb161fe docs(prds): mark the self-development ADR as decided, not built (#1769) 2026-11-03 01:52:06 +11:00
sam 3b525b7482 docs(prds): mark the self-development ADR as record, not mechanism (#1769) 2026-11-03 01:50:54 +11:00
sam c2cc10ebfa docs(prds): record the self-development loop decision (#1769) 2026-11-03 01:36:31 +11:00
sam 2f8076d7f8 fix(access): forbid clause scopes the canary grant against its developer role (#1727)
deploy / agent-image (push) Successful in 10s
deploy / gate (push) Successful in 4m45s
deploy / archied-image (push) Successful in 2m53s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m37s
Service accounts created through the identities API are assigned the
developer role in the request's org, whose shipped policy permits read and
write across the org -- the permit alone did not scope the canary. Install a
matching org-canary-grant-forbid policy (access.CanaryGrantForbidPolicy) that
negates exactly the permit's surface for the canary identity; a forbid wins
within the level, so the role can no longer widen access. Engine tests pin
the surface with the principal carrying the developer role, and the
rehearsal now proves it live: the scoped token gets 403 on /api/access/policies
and 200 on /api/chat/update, and the full canary loop runs on it.

task check passes; task canary:rehearse green (REHEARSE_EXIT=0).
2026-11-02 06:23:38 +11:00
sam c180a2debb feat(access): scoped canary grant replaces instance-admin CANARY_TOKEN (#1727)
deploy / gate (push) Successful in 4m48s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m49s
deploy / archied-image (push) Successful in 2m55s
deploy / agent-image (push) Successful in 11s
The canary now authenticates as a dedicated service-account identity in the
system org whose only grant is access.CalaryGrantPolicy: read the signal
endpoints (chat update, alerts, logs, tasks), read and write the
update-settings resource, and trigger an update install. CANARY_TOKEN no
longer carries instance admin; DEPLOY_TOKEN stays CI-only.

- authorize: POST /api/chat/update/install and /defer map to
  update on Object::"update" (dashboard) instead of run on any workflow,
  so the grant can cover installs without granting workflow runs
- accounts: active service-account identities may authenticate with bearer
  tokens (CanAct), not just users
- new POST /api/identities/{id}/tokens (behind manage_identities) mints a
  token for a named non-user identity; new AccountService RPC
  BindIdentityPersonalToken backs it remotely, refusing user-kind targets,
  with the caller recorded as audit actor
- engine tests pin the grant's exact allow/deny surface

RELEASING.md documents the one-time setup. task check passes on this tree.
2026-11-02 06:03:41 +11:00
sam 5356745968 fix(releaseupdate): address review findings on the #1725 canary change
deploy / archied-image (push) Successful in 3m11s
Quality / check (push) Successful in 3m39s
deploy / gate (push) Successful in 4m28s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
- one shared UpdateStateDir() resolver for daemon and dashboard, instead of
  two copies that could drift
- the recovery path for a committed/rolled-back journal writes
  installed.json too, so a crash after the outcome phase cannot lose the
  install record
- JudgeCanaryNow is the explicit signals-only entry point for promoting
  without the window, replacing the zero-install-time sentinel
- canary version comparisons use IssuedAt, matching Promote's replay rule,
  so semver/issued-at divergence cannot wedge check red; queuedBehind
  reuses the judgeable predicate instead of a looser check
- promote prints the channel/pin; promote.yml cancels superseded runs
- canary card: no duplicated elapsed rendering, channel row waits for the
  settings resource instead of showing a default, agent fallback '?'
- rehearsal script bounds its docker build/push/run calls

task check passes on this tree.
2026-11-02 02:45:26 +11:00
sam 5b5059615b feat(releaseupdate): judge the installed release, window from install (#1725)
deploy / archied-image (push) Successful in 3m14s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m31s
Quality / check (push) Successful in 4m2s
deploy / agent-image (push) Successful in 11s
The canary window now counts from when a release is installed on the host
(installed.json / installed_at in the update snapshot), not from the
statement's issued_at, and 'release canary check' judges the release the
canary actually runs via its exact-pin tag instead of the moving next tag.
A newer release on next queues behind the one being judged instead of
restarting the clock, so stable moves once per release.

New subcommands: canary status (read-only state, signals, verdict), canary
promote (promote now when hard checks pass), canary unpin (back to next),
and start -force. A held/pinned canary is verified installable every check
and a stranded pin fails the run red instead of looking green. Rollback
pre-flight checks stable's zip and agent image digests before pinning.
Relative signals are judged whenever both windows carry minimum data, so a
breach rolls back mid-window; promote still needs the full window unless
the operator promotes early (new promote.yml workflow_dispatch). The window
is configurable via -window / CANARY_WINDOW.

Also: dashboard canary status card (ui), and task canary:rehearse, a local
end-to-end rehearsal of publish -> canary start -> status -> check ->
promote against a throwaway registry and host.

task check passes; rehearsal run green (REHEARSE_EXIT=0).
2026-11-02 01:15:29 +11:00
sam bca1f3b412 chore(release): v1.58.1
deploy / agent-image (push) Successful in 3m18s
Quality / check (push) Successful in 3m43s
deploy / dist-zip (push) Successful in 2m37s
deploy / gate (push) Successful in 4m36s
deploy / archied-image (push) Successful in 2m52s
2026-11-02 00:27:14 +11:00
sam 3af96fd818 fix(daemon): watch the task intake loop too and name the stalled loop
deploy / gate (push) Successful in 4m30s
deploy / agent-image (push) Successful in 12s
Quality / check (push) Canceled after 26s
deploy / archied-image (push) Successful in 2m50s
deploy / dist-zip (push) Skipped
2026-11-02 00:26:50 +11:00
sam 1043982529 fix(daemon): stamp each run-loop cycle so the systemd watchdog keeps beating
deploy / archied-image (push) Successful in 2m54s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m37s
deploy / gate (push) Successful in 4m27s
2026-11-02 00:22:24 +11:00
sam 6abfe32540 chore(release): v1.58.0
Quality / check (push) Successful in 3m39s
deploy / archied-image (push) Successful in 2m49s
deploy / gate (push) Successful in 4m19s
deploy / agent-image (push) Successful in 3m9s
deploy / dist-zip (push) Successful in 4m52s
2026-11-01 23:55:55 +11:00
sam 1f9807a99c fix(ui/chat): give the collapsed composer its own card and reserve its height (#1719)
deploy / gate (push) Successful in 4m33s
deploy / archied-image (push) Successful in 3m16s
Quality / check (push) Successful in 3m39s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
2026-11-01 23:11:01 +11:00
sam b2edf1fa8b build(ui): reinstall Trace and Collapsible with the shadcn-vue CLI
Quality / check (push) Successful in 3m34s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 3m26s
deploy / gate (push) Successful in 4m32s
2026-11-01 23:05:18 +11:00
sam bb897e76b8 Merge pull request 'feat(agentexec): record each agent run's transcript and show it per step (#1718)' (#1724) from claude/intelligent-tereshkova-5422da into main
deploy / gate (push) Successful in 4m37s
deploy / archied-image (push) Successful in 3m13s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m41s
Reviewed-on: #1724
2026-11-01 11:43:32 +00:00
sam 07062352b4 Merge branch 'main' into claude/intelligent-tereshkova-5422da
Quality / check (pull_request) Successful in 3m35s
2026-11-01 11:43:20 +00:00
sam 856c15858b feat(ui): replace the top bar navigation with the sidebar-07 block (#1723)
Quality / check (push) Successful in 3m24s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 3m18s
deploy / gate (push) Successful in 4m32s
2026-11-01 22:09:54 +11:00
sam 69a46249cc feat(webui): draw each transcript entry with its Trace pattern (#1718)
Quality / check (pull_request) Successful in 3m38s
Record the model's reasoning parts. The step run view shows reasoning as a
Thought row, shell calls as a terminal, the gate as a test run, web_fetch as a
source, finish as the verdict, and each fan-out branch as a subagent.
2026-11-01 22:09:53 +11:00
sam 6f10ecc04f feat(agentexec): record each agent run's transcript and show it per step (#1718)
The loop runner hooks every model call and tool call and reports ordered,
redacted, clipped entries. Each is persisted as an agent_transcript task
event through InsertEvent, left out of the timeline read, and served per
attempt at /api/tasks/{id}/transcript. The step run view shows it with Trace.
2026-11-01 22:09:53 +11:00
sam d6ca6a72a5 build(ui): build the dashboard in CI and the Taskfile instead of committing ui/dist
deploy / gate (push) Successful in 4m28s
deploy / archied-image (push) Successful in 3m29s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
Quality / check (push) Canceled after 1m27s
2026-11-01 22:07:36 +11:00
sam 243832fee6 docs(ui): add components with the shadcn-vue CLI, not by hand
deploy / archied-image (push) Successful in 2m47s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m7s
deploy / gate (push) Successful in 3m51s
deploy / agent-image (push) Successful in 11s
2026-11-01 21:47:54 +11:00
sam e8c2c844a8 ci: skip setup-go caching on the self-hosted runner (#1716)
Quality / check (push) Successful in 3m1s
deploy / archied-image (push) Successful in 2m54s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 4m6s
2026-11-01 21:21:09 +11:00
sam 6220387ed6 fix(install): restart running services on reinstall (#1716)
Quality / check (push) Successful in 3m32s
deploy / dist-zip (push) Skipped
deploy / gate (push) Successful in 7m18s
deploy / archied-image (push) Successful in 3m4s
deploy / agent-image (push) Successful in 11s
2026-11-01 17:59:05 +11:00
sam efd3eb2854 fix(releaseupdate): wait for the canary to offer a release before installing (#1716)
deploy / agent-image (push) Successful in 11s
Quality / check (push) Successful in 3m14s
deploy / gate (push) Successful in 6m48s
deploy / archied-image (push) Successful in 3m3s
deploy / dist-zip (push) Skipped
2026-11-01 02:55:31 +11:00
sam c78063eba0 chore(release): v1.57.0
Quality / check (push) Successful in 3m20s
deploy / archied-image (push) Successful in 2m51s
deploy / dist-zip (push) Failing after 1m56s
deploy / gate (push) Successful in 6m29s
deploy / agent-image (push) Successful in 3m25s
2026-11-01 02:26:01 +11:00
sam 0e931485a0 docs(releaseupdate): use contractions in the release and canary text (#1716)
deploy / agent-image (push) Successful in 12s
Quality / check (push) Successful in 7m33s
deploy / gate (push) Successful in 6m27s
deploy / archied-image (push) Successful in 2m57s
deploy / dist-zip (push) Skipped
2026-10-31 22:18:57 +11:00
sam 1bf536d4ab docs(releaseupdate): rewrite the canary comments in plain English (#1716)
Quality / check (push) Canceled after 8m7s
deploy / archied-image (push) Successful in 2m57s
deploy / agent-image (push) Successful in 11s
deploy / gate (push) Successful in 6m20s
deploy / dist-zip (push) Skipped
2026-10-31 22:11:04 +11:00
sam 2181b5fd08 ci(deploy): move the images' :latest only when a release is promoted (#1716)
deploy / agent-image (push) Successful in 10s
deploy / gate (push) Successful in 6m29s
deploy / archied-image (push) Successful in 2m59s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m47s
2026-10-31 21:48:10 +11:00
sam a4a7c96da6 feat(releaseupdate): publish to next and promote to stable only after a canary evaluation (#1716)
deploy / gate (push) Failing after 16m14s
deploy / agent-image (push) Skipped
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 3m49s
deploy / archied-image (push) Skipped
2026-10-31 21:39:32 +11:00
sam a7f6e517ad ci(release): cut releases from [Unreleased] by workflow dispatch (#1716)
deploy / gate (push) Successful in 7m17s
Quality / check (push) Canceled after 9m13s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
deploy / archied-image (push) Successful in 2m56s
2026-10-31 21:30:33 +11:00
sam 812d9004a7 feat(webui): keep the Model setup step open until the provider credential resolves (#1045)
Quality / check (push) Successful in 4m40s
deploy / agent-image (push) Successful in 11s
deploy / gate (push) Successful in 6m15s
deploy / archied-image (push) Successful in 2m57s
deploy / dist-zip (push) Skipped
2026-10-31 20:04:06 +11:00
sam ebc6dd67e6 fix(setup): offer the bundled database as an explicit choice on a re-run (#1388)
With an existing database_url, setup prefilled the URL, so a blank answer
kept it and the bundled socket database was unreachable without typing its
URL. The re-run database step now presents a choice menu: keep the existing
URL (still the default), switch to the bundled database (socket URL plus a
generated PGPASSWORD written to the env file), or enter a different URL.
Fresh installs and -database-url are unchanged; a blank answer anywhere
still keeps the existing URL. Pinned at the setup API level with fake
prompter/sink: TestRunParamsDatabaseChoice.
2026-10-31 20:03:33 +11:00
sam 949457689c chore(release): v1.56.0
deploy / archied-image (push) Successful in 2m46s
Quality / check (push) Successful in 3m46s
deploy / agent-image (push) Successful in 3m16s
deploy / dist-zip (push) Successful in 3m16s
deploy / gate (push) Successful in 6m7s
2026-10-31 19:26:43 +11:00
sam 0cb035555f ci(deploy): link the published packages to the repository
Quality / check (push) Successful in 4m25s
deploy / gate (push) Successful in 6m4s
deploy / archied-image (push) Successful in 2m55s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
2026-10-31 19:19:49 +11:00
sam a5974d0ea0 ci(deploy): one v* release stream; drop the legacy per-component tags
deploy / archied-image (push) Successful in 2m58s
Quality / check (push) Successful in 3m44s
deploy / gate (push) Successful in 5m58s
deploy / agent-image (push) Successful in 11s
deploy / dist-zip (push) Skipped
2026-10-31 19:14:48 +11:00
sam 1ea15462c0 feat(messaging): run Telegram as an archipelago channel extension (#1399)
deploy / gate (push) Successful in 6m11s
deploy / archied-image (push) Successful in 2m56s
deploy / agent-image (push) Successful in 10s
deploy / dist-zip (push) Skipped
Quality / check (push) Successful in 4m56s
The bundled internal/channels/telegram package (17 files) is deleted; the
channel now ships as archipelago/channels/telegram, launched by archiemessaging
through the existing channel-extension machinery. An existing [chat.telegram]
config enables it with the same keys: the token stays a secret reference
(token_ref) the host resolves, allowed_user_ids and show_tool_calls map onto
extension settings. Per-org bots compose the same extension per org from the
org's credential binding. Reload support is now derived from a channels.Reloader
interface instead of a *telegram.Gateway assertion. The five host-only seams
(/update, release announcements, running versions, in-place show_tool_calls,
reload) are dropped from the channel and need a contract home or deletion.
2026-10-31 18:19:21 +11:00
sam 9d8f364af1 feat(releaseupdate): signed OCI distribution sources for releases and the catalogue (#1715)
Quality / check (push) Successful in 5m53s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / gate (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-31 18:18:43 +11:00
sam c87b0c31e1 chore(tools): sign cloud environment commits with an SSH key
deploy / archied-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
Quality / check (push) Successful in 5m1s
deploy / gate (push) Successful in 6m30s
deploy / agent-image (push) Canceled after 0s
2026-10-31 14:57:01 +11:00
sam c5802cf86d fix(releaseupdate): load the env file beside the config so update install gets the database password from a shell (#1431) 2026-10-31 14:40:41 +11:00
sam 4f2338810b chore(tools): install go 1.27.3 in the cloud setup script
go.mod moved to 1.27.3 for the crypto/x509 advisory govulncheck reports; the
setup script still installed 1.27.2.
2026-10-31 14:39:58 +11:00
sam f8da67348c feat(webui): org-scoped schedules for non-system orgs (#1639 #1051 #49) 2026-10-31 14:25:24 +11:00
sam 003771ca48 feat(access): denial retention knob, State Store sweep and dashboard denials page (#1842)
Add [access].denial_retention (default 90 days, matching the audit-retention
seed) wired through config defaults and validation; the State Store sweeps
denial records older than the configured age hourly via the new
access.DenialPruner / PruneDenials store query. The dashboard gains
GET /api/access/denials (read_audit-gated, so org admins/owners see their
org's records; the store scopes by the credential's org) and an
/org/denials page backed by a Pinia store.
2026-10-31 14:23:31 +11:00
sam f7926cde15 fix(deps): go 1.27.3 and x/net 0.62.0 to clear govulncheck
The deploy gate's govulncheck step failed on the first run that reached it, for
two real findings: crypto/x509 in the standard library, fixed in go1.27.3, and
golang.org/x/net v0.61.0, reached from webfetch.htmlToText calling html.Parse,
fixed in v0.62.0. govulncheck now reports none.
2026-10-31 01:05:27 +11:00
sam 3a05b3ecd0 fix(ui): show stream state at phone width and serve sections from the sheet below lg (#1261 #1386) 2026-10-31 00:47:38 +11:00
sam 6031a7a14b ci(deploy): run the gate from the Taskfile, not an inlined copy (#1580)
deploy.yml inlined its own sequence, which drifted weaker than `task check`:
no db:check, news:check or ui:check, so a release could ship stale sqlc
output, a stale ui/dist, or release notes that disagree with CHANGELOG.md,
and the dashboard suite ran outside the gate without its type check.

The release now runs `task check TEST_FLAGS=-count=1`: same definition, the
full uncached suite including the Docker-backed tests -short skips. quality.yml
already invoked the Taskfile, so both pipelines now share one gate.
2026-10-31 00:37:26 +11:00
sam ad9ec16844 test(egress): delete the test-only ResolverFunc adapter and its tests (#1671) 2026-10-31 00:36:37 +11:00
sam 3977eaad68 fix(workflow): make the repository optional for the triage workflow (#1578) 2026-10-31 00:36:10 +11:00
sam 3b6de96782 docs(deploy): name the registry each agent-image path publishes to
The pinning section said CI republished ghcr.io on every push to main. CI
publishes git.catlow.cloud, and only for a release tag; ghcr is where the
hand-run tools/publish.sh writes, which is the reference the default names.

A release zip pins a digest on a registry an anonymous pull cannot reach, and
[containers].registry_auth -- the setting that fixes it -- was documented
nowhere. Documented there, beside the pin.

Also corrected: every shipped profile does not pin the image, and the section
link omitted its number so it matched no heading.
2026-10-31 00:35:49 +11:00
sam decc86fd08 ci(quality): stop caching the pnpm store
setup-node's cache save fails on this runner -- the pnpm store path it computes
does not exist at post-step time, which marks the job failed after the gate has
already passed. Run 19 proved it: 0 lint issues, ui/dist matched, no task failure,
then 'Path Validation Error' and exit 1.
2026-10-30 01:44:56 +11:00
sam 5485dc4690 chore(workflow): finish dropping the unread step-type catalogue accessors (#1014)
Manager.StepTypes and Providers had no reader; the catalogue they were meant
to feed is not missing -- Registry/Settings serve it as x-step-types in the
workflow-definitions schema, read by the dashboard workflow editor and the
gateway's workflow_step_types tool. Remove the write-only providers field
the accessor deletion left behind, and pin that production reader in
controlplanerpc so a dropped schema extension fails the gate.
2026-10-30 01:31:36 +11:00
sam 57865b51f4 fix(forge): return SetStateLabel failures to the caller
A failed state-label change was dropped at three points: the forge.Forge
interface returned nothing, forgeext logged the extension's gRPC error
instead of returning it, and the forgerpc client and server discarded the
response error. SetStateLabel now returns an error on the interface and on
NoopForge, forgeext propagates the extension's error, and the forgerpc
server carries it in the response envelope while the client returns it,
matching the other forgerpc handlers.

The proto is unchanged: a gRPC error rides the status and
SetStateLabelResponse is already an empty message.

TestSetStateLabelFailureReachesTheCaller pins the full chain: an extension
whose SetStateLabel RPC fails, through forgeext and the forgerpc
client/server, to the caller receiving the error.

Refs #280
2026-10-30 00:58:07 +11:00
sam 0a1aa8b3c2 fix(prreview): classify comment lines against the diff before posting 2026-10-30 00:35:36 +11:00
sam 7c8114bc55 fix(curator): grant the definition engine its model runner
Registry.filter stripped the LLM capability whenever a manifest declared
no tools, skills, memory or conversation capabilities, but
DefinitionEngine.Pass always calls the model. An instruction-only custom
curator therefore registered healthy and then failed every pass with
'no model runner is bound'. The definition engine is inherently agentic,
so the filter now keeps the model runner for it while every other
capability service stays bound only when declared.

Adds tests reproducing the instruction-only pass through the
registry/engine path and pinning that the registrar view for an
instruction-only manifest exposes the model but no tools, skills,
memory or conversations.

Closes #1132
2026-10-30 00:22:50 +11:00
sam aa57377c7f fix(staterpc): make model usage writes durable through a State Store outage
A failed RecordUsage was logged and dropped, losing chat, title, sampling
and curator usage that cannot be rebuilt from events. The staterpc Client
now keeps a bounded local outbox: a failed write is queued and retried with
backoff (1s doubling to 1m, 10s per attempt) until the store accepts it, so
records land once the store recovers. The queue is capped at 1024 records;
an overflow is refused so the caller logs the drop. The sampling usage
write is bounded to 5s so a dead store cannot hold a model call.
2026-10-30 00:06:38 +11:00
sam 8aa65bc7b4 fix(workflow): close a budget-stopped stage with its findings as the outcome 2026-10-30 00:06:38 +11:00
sam a781fde566 fix(catalogue): sign an issue time and refuse a replayed older catalogue 2026-10-30 00:06:38 +11:00
sam 3b372b4a91 ci(deploy): stop installing ripgrep and setting sysctl from the gate
The deploy gate runs on a self-hosted runner under an unprivileged user, so the
sudo apt-get install and sudo sysctl steps fail. Both are host provisioning:
ripgrep is installed on the runner host and the userns restriction belongs in
sysctl.d. The namespace check stays, without sudo.
2026-10-29 23:57:23 +11:00
sam 066522cf5d ci(quality): run the gate on the archie-quality runner
The check job asked for the self-hosted label. The repository's only runner,
archie-quality, is online but carries just its own custom label, so run 17 has
been queued since it was pushed. Name the runner instead of a label nothing
offers.
2026-10-29 23:30:43 +11:00
sam ec9bf5feb2 docs: track work in Gitea issues instead of beads
Every one of the 1709 tracker issues was created in Gitea and checked field by
field against its source record: title, body, state, label set, assignee,
comments, dependency edges and epic label. All 1729 beads are closed, citing the
issue that carries each one, and .beads is removed.

Three differences are deliberate: Gitea truncates titles at 253 characters, so
three long titles keep their full text in the issue body; Gitea refuses a mutual
dependency, so five symmetric relates-to links exist in one direction; issue 497
carries its fix from e3b1103f.
2026-10-29 23:22:35 +11:00
sam dfb37fb4f2 Merge origin/main: README update 2026-10-29 23:00:09 +11:00
sam 86c2909a57 Update README.md 2026-10-29 22:54:26 +11:00
sam b5482857f8 fix(forge): accept invitations only to configured repositories
The GitHub forge extension accepted every pending repository
invitation, so any GitHub user could add archie's account to a
repository by sending an invitation. AcceptInvitations now carries the
connection's configured repositories and the extension leaves an
invitation to anything else pending.
2026-10-28 23:57:44 +11:00
sam 0c137d9319 refactor(fsutil): consolidate nine copies of the atomic write helper
Nine packages each had their own write-temp-then-rename helper with
slightly different behaviour (some synced, some did not; some created
the parent directory, some did not; modes and temp-file patterns
varied). They are replaced by one fsutil.WriteFileAtomic that always
syncs before rename, creates the parent directory, and takes the file
mode as a parameter.
2026-10-28 00:48:59 +11:00
sam 59827b19bd fix(controlplane): reject userinfo and query in notify_webhook
A webhook URL with embedded credentials or a query string can leak
secrets through logs, proxies and referrer headers. The task policy
validator now refuses both.
2026-10-28 00:36:33 +11:00
sam 34179f0f9f ci(deploy): publish images and releases to Gitea
The deploy workflow now targets git.catlow.cloud: images push to the
Gitea registry and the distribution zip publishes as a release on
sam/archie through the Gitea API, both authenticated with one
DEPLOY_TOKEN PAT (write:packages + write:repository scopes).
2026-10-27 23:20:54 +11:00
sam 9c193aeebb fix(staterpc): log internal identity errors through the service logger with request context 2026-10-27 20:54:41 +11:00
sam 1cd8955d23 docs(agents): errors surface through OpenTelemetry, not global slog 2026-10-27 20:51:52 +11:00
sam 004e38b8eb fix(staterpc): record internal identity errors on the request span instead of slog 2026-10-27 20:51:46 +11:00
sam c5991a560e fix(staterpc): give token revoke its own audit request ID and log internal identity errors 2026-10-27 20:50:18 +11:00
sam 04ce0f9056 feat(identity): name, lifetime and last-used on personal API tokens 2026-10-27 15:37:44 +11:00
sam e5cb0ac00b fix(ui): copy and dismiss a new API token 2026-10-27 15:31:13 +11:00
sam abe4c488cf fix(archied): recover an orphaned update journal while running, not only at boot 2026-10-27 15:24:04 +11:00
sam 973541f344 fix(gatewayrpc): refuse an inbound attachment whose bytes contradict its declared type 2026-10-27 15:23:48 +11:00
sam 3c4b7b5877 fix(workflow): keep a stopped stage's notes in the parked detail 2026-10-27 15:22:42 +11:00
sam 8fbfb3c99f fix(ui): show the last update's outcome on Settings > Status and present install as staged 2026-10-27 15:18:52 +11:00
sam 3b33d164c7 test(e2e): per-run report.html, fix stale workflow-logic and audit-runtime, add org selector, org pages, setup, recovery, readiness and schedule-trigger checks 2026-10-27 11:44:23 +11:00
sam 292597660f fix(webui): skip the open-card reframe while the workflow canvas is hidden 2026-10-27 11:44:23 +11:00
sam ba3a26af3c fix(postgres): carry org, park class and park blocker on task list rows so a parked task's recovery link shows 2026-10-27 11:44:23 +11:00
sam 4bb473c0b0 fix(webui): resolve a selected org's workspaces as the caller, wire selection into gateway and harness, and let a member start tasks in the org they selected 2026-10-27 11:06:18 +11:00
sam c3d49cbc6c feat(webui): park model credential failures with a recovery link, add Model setup step, readiness badges, and move audit to the organisation 2026-10-27 11:06:18 +11:00
sam e831edb005 feat(webui): act in a selected organisation the caller is a member of, enforced at the dashboard and the State Store 2026-10-27 11:06:18 +11:00
sam 3db2654188 feat(webui): derive the setup checklist from the caller's organisation and drop the optional chat channel step 2026-10-27 10:47:14 +11:00
sam afdb4b203f feat(daemon): park repository, credential and forge-extension failures with a recovery link on the task list 2026-10-27 10:47:14 +11:00
sam 6f57d38669 feat(webui): offer each organisation page only to callers its API write allows, and move appearance to the account menu 2026-10-27 10:47:14 +11:00
sam d60995af43 fix(orgs): layer only the fields an org document sets, retry alerts on a failed lookup, and key chat sessions by org 2026-10-27 10:38:00 +11:00
sam 472d9d8b10 feat(messaging): run a channel per organisation and deliver only through the owner's 2026-10-27 10:38:00 +11:00
sam 11b89354a6 feat(alerts): send each organisation's alerts to its own webhook 2026-10-27 10:38:00 +11:00
sam 8150df8d81 feat(scheduling): resolve the issue discovery rule per organisation 2026-10-27 10:38:00 +11:00
sam b8e080301c fix(postgres): let every org read a built-in mapping so a non-system org can arm a schedule trigger 2026-10-27 10:13:03 +11:00
sam 2d87e9f587 fix(applystatus): report only the instance's own copy so another org's read cannot overwrite it 2026-10-27 10:08:24 +11:00
sam 749baa3e5d fix(scheduling): fire a schedule's capture into its owning organisation 2026-10-27 10:03:29 +11:00
sam 90deba8472 fix(gateway): chat /cancel declines through the task-action service so the run stops 2026-10-27 10:00:54 +11:00
sam 9498fad064 fix(webui): report a workflow's running count and last status from its own runs 2026-10-27 02:52:38 +11:00
sam 6ca5c7f851 fix(release): ship archie-agent beside archied so Kit runs have one to mount 2026-10-27 02:49:31 +11:00
sam dfce3360b2 test(orgs): hold the agent-assignment contract the Agents tab reads 2026-10-27 02:45:35 +11:00
sam 58629ea03a fix(webui): keep the instance settings out of another org's reach 2026-10-27 02:44:33 +11:00
sam 5b3b88ed3d fix(taskfile): install dashboard deps before the parallel gate scans the tree 2026-10-27 02:41:38 +11:00
sam 62dbac9247 fix(archied): refuse an unknown subcommand instead of starting a second daemon 2026-10-27 02:40:41 +11:00
sam a8aad28239 fix(ui): give the topbar its own surface and a filled active tab 2026-10-27 02:13:27 +11:00
sam 9d633855f4 fix(ui): use the Archie mark in chat empty state and sign-in gate 2026-10-27 02:01:32 +11:00
sam 56ac50931e fix(ui): drop cycling names from the logo 2026-10-27 01:57:00 +11:00
sam 3e437d4275 chore: remove dashboard-v2, archived out of tree 2026-10-27 01:54:05 +11:00
sam c9951c085c feat(dashboard-v2): tasks page from table-filter template 2026-10-27 01:47:42 +11:00
sam 59c6f0e4c0 fix(dashboard-v2): fail loudly when 5174 is taken 2026-10-27 01:37:38 +11:00
sam 9460f51e07 Merge remote-tracking branch 'origin/main' 2026-10-27 01:29:45 +11:00
sam 3ac5b97706 fix(ui): larger all-sage mark in the topbar (#1859) 2026-10-27 01:12:19 +11:00
sam 1add0fca32 feat(dashboard-v2): Archie motion mark on login, mark favicon 2026-10-27 01:10:24 +11:00
sam 0d8c48cbf4 Merge remote-tracking branch 'origin/main' 2026-10-27 01:06:12 +11:00
sam e41b7606d6 feat(ui): new Archie mark, shared sage accent, theme follows the OS (#1858) 2026-10-27 01:04:15 +11:00
sam ad2ceaaec2 fix(dashboard-v2): remove duplicated api opener 2026-10-27 00:19:58 +11:00
sam c3b636bf72 feat(dashboard-v2): show instance, offer SSO when advertised 2026-10-27 00:19:20 +11:00
sam 98acd6aad0 chore(dashboard-v2): lock TanStack Query 5.104.5 2026-10-27 00:16:40 +11:00
sam 8f7743c73d fix(dashboard-v2): gate session on status user, add favicon 2026-10-27 00:15:49 +11:00
sam 60a19ab15e feat(dashboard-v2): TanStack Query plus session state 2026-10-26 23:53:48 +11:00
sam dc1e45ff82 feat(dashboard-v2): sign in on 401 via login template page 2026-10-26 23:52:12 +11:00
sam 5fefd1902f fix(dashboard-v2): require StyleX ^0.19 per core peer range 2026-10-26 23:44:18 +11:00
sam 45ed5b2faf feat(dashboard-v2): verify build, commit lockfile and generated theme 2026-10-26 23:44:01 +11:00
sam f0fac7899f chore(dashboard-v2): drop stub lockfile from offline install 2026-10-26 23:41:00 +11:00
sam c7e12b56d0 feat(dashboard-v2): scaffold Astryx app with system status slice 2026-10-26 23:40:47 +11:00
sam 087aa45349 test(e2e): split overloaded checks, standardize screenshots 2026-10-26 22:57:15 +11:00
sam 4cc22ac5e0 refactor(ui): audit leftovers use Alert, Item, CodeView and Tooltip
Inline error paragraphs become destructive Alerts, divided record lists
become Item rows, the redirect URI box uses CodeView, and icon-button
title hints use Tooltip. Native titles remain on truncated values and on
disabled controls.
2026-10-26 22:35:47 +11:00
sam 7f0ecaa192 build: move the dashboard and e2e packages from npm to pnpm 2026-10-26 22:15:26 +11:00
sam a203cbc03b refactor(ui): Empty, Spinner and Label replace hand-built equivalents 2026-10-26 22:11:39 +11:00
sam 17c07a31fe build(ui): update dependencies within range 2026-10-26 22:00:33 +11:00
sam 87100c4aba build(ui): add vue-sonner and the Sonner component 2026-10-26 21:58:02 +11:00
sam 5498c97e3d fix(ui): e2e checks match the current dashboard; trim stray label whitespace, keep Home/End in suggest input 2026-10-26 20:59:48 +11:00
sam 3ff6867e84 refactor(ui): raw buttons, details and hr use Button, Collapsible and Separator 2026-10-26 20:00:57 +11:00
sam 7c050eef14 refactor(ui): block error messages use Alert 2026-10-26 19:59:00 +11:00
sam d98abad8bb feat(archied): raise an alert when container max uptime is under the task limit 2026-10-26 19:48:09 +11:00
sam 9e92beb4cc fix(ui): agent profile tools commit on change so commas can be typed 2026-10-26 19:46:56 +11:00
sam ca597c3678 feat(ui): suggest input on Combobox replaces datalists, RadioGroup for task pickers
Also records the combobox and radio-group components added in 63476393.
2026-10-26 19:45:18 +11:00
sam 63476393d7 feat(ui): settings pages edit through TanStack Form with shadcn-vue Field
Each control-plane kind has one store-owned TanStack form, so edits survive
navigation and the save bar submits every dirty section. Shared editors emit
new values, map entries are written whole, unset resources stay null, and the
container runtime page warns when max uptime is under the task limit.
2026-10-26 19:17:03 +11:00
sam 9d930436c5 refactor(ui): delete unused SegmentBar 2026-10-26 18:52:55 +11:00
sam be0f6f5ab7 fix(gateway): name a plan wait's workflow from its run, not the next one
workflow.approve pre-writes the task's workflow column with the workflow
that runs once approved, so task_list named a workflow that had not
started while the task's own log named the one that produced the plan.
Chat now names the compiled workflow through the pinned definition for a
plan wait, matching the log.
2026-10-26 18:32:25 +11:00
sam 66daa071a5 fix(configuration): raise the default max uptime above the task limit 2026-10-26 18:32:25 +11:00
sam ca44b9e6bb fix(archied): bound task titles in chat notifications 2026-10-26 18:32:25 +11:00
sam da7efa3f4e fix(ui): keep the chat dock open across navigation
Clicking any navigation control counted as an outside click, so the dock
collapsed on every route change and the conversation disappeared. Hide and
Escape remain the only ways to collapse it.

The e2e accessibility check referenced the removed outside-click launcher and
the old Close chat label; both now use the dock's real controls.
2026-10-26 18:28:32 +11:00
sam 4de8882ef5 fix(gateway): require a remote check before claiming branch or PR state
The chat agent read only its local checkout, so an unfetched workspace made it report that no task branch or PR existed and that shipped UI code did not exist. Add a core rule: refresh from the remote or check the forge before describing branches, commits, pull requests or the default branch, and say the answer is local-only when it cannot.
2026-10-26 18:28:32 +11:00
sam c00a90c9ca fix(workflow): report a parked run's outcome as the task's status
A run that parked left tc.Outcome empty, so the taskrun response carried an
empty status and the daemon logged 'taskrun run recorded no outcome' for a run
that had recorded one, then retried the park it could not apply.

Record the outcome once the parked transition lands, so a budget stop and every
other park surface with the reason the run parked.
2026-10-26 18:28:32 +11:00
sam c4c50ea70d fix(gateway): cap task_spawn titles and carry instructions into the body 2026-10-26 18:24:47 +11:00
sam c578c8e954 fix(taskactions): let the operator chat act on every task, like the dashboard
A chat profile bound to the operator identity passed a strict scope to the
action gate, so it refused root-owned tasks whose identity is the daemon's
empty sentinel (task 22: belongs to "", not "d898c8c8-..."). The dashboard
acts with a nil scope and the chat read paths already treat the operator as
acting across identities, so the write gate was the only surface that disagreed.

Exempt the operator identity from the scope comparison and share that rule with
the chat adapters that had their own copy.
2026-10-26 18:24:47 +11:00
sam e85719f2d2 fix(controlplanerpc): attribute chat workflow drafts so saves succeed 2026-10-26 18:24:46 +11:00
sam 4dca007003 fix(container): report a crashed container's panic line and log its stderr 2026-10-26 18:24:46 +11:00
sam d7d1bd4556 fix(workflow): record the own-PR flag after the review stages that allocate it
StagePRReviewAndOpenPR set tc.prReview.ownPR before the decision stages ran,
but intake allocates tc.prReview, so every implement run dereferenced a nil
state at repo.open-pr and the agent container panicked with exit code 2
before opening the pull request.
2026-10-26 18:07:01 +11:00
sam dc26daeebe fix(daemon): issue poll and PR passes report failed items to the scheduler 2026-10-26 17:24:55 +11:00
sam f727d54d75 feat(ui): schedules table, runs page and Schedule trigger
Schedules list as a table with enable, run now, edit, duplicate, delete and
view runs; built-ins only enable, retime and run. The runs page links each
run's tasks through its capture's dispatches. The Start node gains a Schedule
trigger that picks or creates a schedule and binds the schedule source to the
workflow. Times show in a per-browser display zone set under Appearance; the
cron time zone and run retention are edited on the Schedules page.
2026-10-26 00:57:52 +11:00
sam 6f8371a7bf feat(workflow): message.send step delivers text through archied's messaging client 2026-10-26 00:56:07 +11:00
sam fff689312d feat(archied): run daemon maintenance as built-in schedules 2026-10-26 00:51:53 +11:00
sam b701f60a99 feat(scheduling): schedules and runs in the State Store with grid timing and run history
Schedules leave the schedules control-plane resource for State Store tables
behind a ScheduleService contract. A run is claimed per schedule slot, missed
slots fire once, the next run stays on the schedule's grid, cron is read in the
schedule-settings time zone, and failed runs are recorded and advance. Three
failures in a row raise a schedule.failing alert. A fired run records a
schedule-fired capture. Run history is pruned by age and count.

Removes the chat and spawn-task runners, the dangerous-payload guard and the
old schedules settings page.
2026-10-26 00:49:24 +11:00
sam 6ba6a595b8 feat(eda): capture schedule firings on a reserved source for bindings 2026-10-26 00:38:55 +11:00
sam 6cd9c4a7d8 feat(daemon): built-in maintenance jobs and idle mirror pruning
Cycle's maintenance passes become a BuiltinJobs list for the scheduler to
seed as locked schedules. Mirrors use a file lock shared by every Manager
and held across refresh and clone, so pruning cannot race a clone.
2026-10-26 00:37:25 +11:00
sam 816ce2e1f8 fix(extension): log go-plugin output through the service slog logger 2026-10-26 00:25:37 +11:00
sam 19570ad4bb fix(logging): route ui, messaging and playbook logs through the service log 2026-10-26 00:18:39 +11:00
sam 5212a4d913 build(deps): bump ai-sdk to v0.6.0, nats.go, oras-go, go-jose and indirect deps 2026-10-26 00:18:39 +11:00
sam 46f0643cf5 fix(webui): name API spans after their route 2026-10-25 23:42:44 +11:00
sam 656feab2a4 refactor(logging): log with the caller's context so records carry trace ids 2026-10-25 23:30:01 +11:00
sam 0611e00330 feat(llm): trace model and tool calls via ai-sdk v0.5.0 2026-10-25 23:19:40 +11:00
sam 128d5e0a82 feat(agent): export container spans over NATS through archied 2026-10-25 23:17:34 +11:00
sam c6187b7c23 feat(servicekit): OpenTelemetry tracer provider and RPC propagation 2026-10-25 23:11:03 +11:00
sam afd6669877 fix(memory): rotate a full section's oldest records to history 2026-10-25 23:10:15 +11:00
sam 7bf007bb58 test(e2e): wait for audit dialogs to close 2026-10-25 23:05:27 +11:00
sam 92a74e4b7d test(e2e): wait for audit dialogs to close 2026-10-25 23:04:56 +11:00
sam 0880e6a01c feat(natsrpc): propagate trace context across NATS and into task runs 2026-10-25 23:03:55 +11:00
sam 4a889991bd test(e2e): audit page browser check 2026-10-25 23:00:44 +11:00
sam 89bb4eb46b fix(audit): filter count aliases outside the projection and clean identity detail 2026-10-25 23:00:44 +11:00
sam f3c7555195 test(e2e): browser check for the audit page 2026-10-25 22:56:18 +11:00
sam 79f3895923 feat(logging): stamp trace and span ids on log records 2026-10-25 22:55:57 +11:00
sam 837cd91501 refactor(controlplane): move the store-backed server out of internal/app 2026-10-25 22:49:27 +11:00
sam 5112ce896b fix(channelext): bound the extension broker server with service limits 2026-10-25 22:46:47 +11:00
sam 7715d6b23b fix(audit): close the feed union and repair denied and retention controls 2026-10-25 22:42:00 +11:00
sam 373032e330 fix(audit): gate resource history, harden export, scope legacy keys and catalog 2026-10-25 22:39:34 +11:00
sam 6a69fb760a fix(audit): harden export, scope history and derive feed targets 2026-10-25 22:39:22 +11:00
sam 4cc7573b27 fix(ui): gate audit retention, resolve export time on click, merge live updates 2026-10-25 22:33:31 +11:00
sam 1d7fd6aab3 fix(ui): gate audit retention, resolve export at click, merge live updates 2026-10-25 22:32:59 +11:00
sam c04a18d387 feat(ui): audit page with server filters, live tail, export and revert 2026-10-25 22:14:53 +11:00
sam abf485b9ef fix(ui): address audit page review findings 2026-10-25 22:14:33 +11:00
sam 0245c4e455 fix(webui): link audit task targets to the task detail 2026-10-25 22:09:31 +11:00
sam fa00f74af5 fix(ui): enforce the retention minimum beside the hours field 2026-10-25 22:09:25 +11:00
sam 2f9ed7adca fix(webui): link audit task targets to task detail 2026-10-25 22:09:25 +11:00
sam 4f2e1c3687 fix(ui): send explicit export range and whole-hour retention 2026-10-25 22:09:25 +11:00
sam 2d2ca156d8 feat(ui): unified audit page with server filters and live tail 2026-10-25 22:09:25 +11:00
sam f8c3dbedf2 fix(webui): allow an all-time audit export 2026-10-25 22:05:40 +11:00
sam 17354de8fe fix(webui): treat the epoch export start as any time 2026-10-25 22:05:34 +11:00
sam 7066a6fd46 feat(webui): audit feed API, export and read_audit grant 2026-10-25 22:02:03 +11:00
sam 20595a70b4 feat(webui): audit feed API, export and read_audit grant 2026-10-25 22:01:02 +11:00
sam 568f7adf52 fix(storage): mount a task's object mirror read-only into its container 2026-10-25 21:58:25 +11:00
sam 74e34fb07a perf(worktree): clone tasks from a shared per-repository mirror 2026-10-25 21:55:20 +11:00
sam e6d765d233 feat(state): audit retention resource and observability sweep 2026-10-25 21:53:29 +11:00
sam 4250a31ff9 fix(state): retain product-read events and normalise audit retention 2026-10-25 21:53:19 +11:00
sam ad19271c6c fix(archied): drop a cached extension binary when its start fails 2026-10-25 21:47:31 +11:00
sam b774b68ed4 perf(archied): reuse running forge extension instances and materialized binaries 2026-10-25 21:46:51 +11:00
sam 8eaf7b00c3 fix(daemon): drain tasks in their own loop, not on the poll tick 2026-10-25 21:45:57 +11:00
sam 59eecd956d feat(state): apply audit retention to observability events 2026-10-25 21:42:38 +11:00
sam e2f9388071 feat(state): unified org-scoped audit feed and AuditService 2026-10-25 21:37:56 +11:00
sam 6c095e5ac6 fix(state): resolve identity audit org in one statement 2026-10-25 21:37:50 +11:00
sam 274acfe6f5 fix(state): attribute identity events to the subject's single org 2026-10-25 21:35:19 +11:00
sam f1eda629a8 feat(state): audit access reset, org, membership and EDA writes 2026-10-25 21:33:28 +11:00
sam 5602534ba9 fix(state): serialise source writes and keep binding workspaces audited 2026-10-25 21:33:08 +11:00
sam bc9b9952cd fix(state): classify audit coverage rows and keep unknown identity orgs private 2026-10-25 21:25:55 +11:00
sam 7f5a73d97d fix(state): close residual audit coverage gaps 2026-10-25 21:24:50 +11:00
sam 02a4ac0629 fix(state): harden the audit feed against audit findings 2026-10-25 21:23:52 +11:00
sam ab78f5c909 feat(state): org-scoped audit feed contract and read model 2026-10-25 21:23:52 +11:00
sam c9c552a1bd feat(state): audit access resets, org and EDA writes 2026-10-25 21:10:38 +11:00
sam c24b055cf3 feat(state): audit package and harness secret writes 2026-10-25 21:10:08 +11:00
sam 72052fe186 fix(postgres): skip unchanged authority in package audit 2026-10-25 21:10:02 +11:00
sam 0f14378363 fix(postgres): correct package and secret audit coverage 2026-10-25 21:03:00 +11:00
sam 551220eccc feat(postgres): audit package and harness secret writes 2026-10-25 21:00:27 +11:00
sam 287f8d71dd refactor(staterpc): one file per State Store service 2026-10-25 21:00:19 +11:00
sam 390e89aefb fix(state): correct audit backfill scoping and policy write races 2026-10-25 20:59:04 +11:00
sam 18e21661b2 feat(state): shared audit write helper for domain tables 2026-10-25 20:49:47 +11:00
sam 8af19c79f4 feat(state): org-scoped audit trail and complete policy write audit 2026-10-25 20:49:20 +11:00
sam b7cda2b2fe build: keep the agent image context to what compiles it
A trailing-slash pattern in .dockerignore matches only the context root, so
node_modules/ never excluded ui/node_modules -- 200MB shipped to the builder
for a Go compile. The issue tracker's Dolt directory was never listed at all.
Every line here either bloats the context or invalidates the COPY layer for
nothing: 467MB transferred per build, 320kB now.
2026-10-25 20:47:24 +11:00
sam c86b8659e5 build: stamp the agent image with the checkout's version
The container build was the one build path that could not learn a version: the
build context excludes .git, so it has to be passed in, and nothing passed one
-- Compose handed the Dockerfile no build args, so every locally built agent
answered "dev" while the daemon reported the tag. The Taskfile now derives the
version from git describe once, for both the host binaries and the image, and
task image:agent passes it through.

docker compose build agent also failed outright: the service named the image by
digest, and Compose refuses to tag a digest. The build-only service names it by
tag now; what a task container runs is still pinned in the daemon's own
[containers] image.
2026-10-25 20:24:27 +11:00
sam de3b41b70d fix(messaging): read a voice clip's container instead of believing its type
The dashboard upload names its own attachment type, so the check that ran on
it only compared two declarations the sender wrote. A browser can label any
bytes audio/ogg, and the transcriber keys on the attachment type alone, so the
bytes went to the operator's provider regardless.

When the bytes are present the container decides: Ogg, WebM/Matroska, mp4/m4a,
wav, flac and mp3 are the containers a clip is recorded in, and anything else
claimed to be speech is refused before it reaches a transcriber. Magic numbers
rather than http.DetectContentType, which reports application/octet-stream for
the WebM every browser but Safari records.
2026-10-25 20:17:30 +11:00
sam 5aa0aead4d chore(proto): drop the one-off service-deletion exception 2026-10-25 19:54:47 +11:00
sam 0dae907dad refactor(state)!: split StateStoreService into per-domain services
One gRPC service per domain in state.v1 (tasks, executions, accounts, identities, packages, captures, bindings, access, orgs, alerts and so on), each with its own server type in staterpc. RPC and message names and numbers are unchanged.
2026-10-25 19:54:27 +11:00
sam 59e3de62db feat(ui): marketplace grouped by surface, searchable, with install state
The marketplace was one long list of filled Install buttons with the raw
surface name beside each version. Packages now group under Forges, Channels,
Secret engines and the rest, as cards in a two-column grid with a search
box. Installed packages stay listed, marked installed or offering their
update.
2026-10-25 19:45:28 +11:00
sam 6c2ab54f65 fix(ui): offer an extension update only when the catalogue has one
An installed extension showed its own version and an Update button whether
or not the catalogue pinned anything newer, so a published update was
invisible. The row now offers 'Update to <version>' when the catalogue's
digest differs from the installed one and no update is already pending.
2026-10-25 18:55:20 +11:00
sam be47311883 docs: map the services and development commands in CLAUDE.md 2026-10-25 18:15:14 +11:00
sam 1e9659c7a2 fix(messaging): say what the inbound media check actually checks
The check compares two declarations; it never reads the bytes, so it cannot
tell whether a file is what its content type says. The comment and the test
row claiming otherwise have gone, and so has an allowance letting a video
carry an image type, which no producer emits.

A caller that named the attachment type itself -- a browser upload -- must now
also state a content type, since the previous empty-type escape made the check
optional there. The Telegram declared-size rule is deleted: the shared check
runs first with the same ceiling, so only the rule on the bytes actually
received can still fire.
2026-10-25 18:13:30 +11:00
sam ca73d02804 chore: bump beads version to 1.3.2 2026-10-25 18:11:33 +11:00
sam 5f827b6e19 fix(messaging): refuse an inbound attachment whose type contradicts its content
A declared MIME type decides what the Gateway does with a file: a voice note is
transcribed, an image goes to a model. Both acceptance points took that claim
from the caller unchecked -- the dashboard's voice upload and every Telegram
attachment -- so a file could be used as something it is not.

ValidateInbound refuses a type outside the shared vocabulary, content over the
size ceiling, and a MIME type that contradicts the attachment type, with an
error the caller sees: a dashboard upload is a 400, a Telegram file gets a
chat reply instead of a silent drop.
2026-10-25 18:05:34 +11:00
sam 7d9c40d79d fix(workflow): review a task's own pull request as a comment
GitHub refuses REQUEST_CHANGES from a pull request's author, so a blocking
finding on the PR a task opened lost every finding. The retry's identical
refusal is now reported once, and forge errors drop the gRPC framing.
2026-10-25 17:57:20 +11:00
sam 33da08bce5 feat(ui): task log opens newest first 2026-10-25 17:41:21 +11:00
sam f2b8681611 refactor(workflow): stop assuming a human decides
An approval, ask or park can be resolved by an operator, a rule, a
classifier or automatically, so the vocabulary stops naming a person:

- step type human.approve -> workflow.approve
- park class needs_human -> needs_decision (ParkNeedsDecision)
- event kinds human_* -> operator_*
- alert kind task.needs_human -> task.needs_decision
- status grouping "needs you" -> "needs attention"

0061 rewrites the stored values, including the approval step type in the
workflow-definitions resource and each task's pinned definition, with the
digest recomputed so resumed tasks still match.
2026-10-25 17:31:16 +11:00
sam fc609171ca docs: clarify reviewer in implement finish summary 2026-10-25 17:20:13 +11:00
sam 2399da1f8d docs(workflow): name no human approver in the plan document 2026-10-25 17:19:06 +11:00
sam d699b9afba feat(workflow): approve a PRD as one structured document
The prd step returns the PRD as structured fields and human.approve takes
them as its document. The plan text every surface reads and the approval
card's layout are both rendered from that one document, so what the human
approves is what the implement workflow is handed. Replaces the separately
generated OpenUI view, which could drift from the plan.
2026-10-25 16:53:17 +11:00
sam 7a03e003a1 docs(ui): drop the local deploy sequence from the shared rules 2026-10-25 16:53:17 +11:00
sam 340223de2e feat(modelloop): run a step's tool calls in parallel as each tool's classification allows 2026-10-25 16:45:34 +11:00
sam 54697c6e17 feat(curator): add and remove curators live; definition updates touch only changed curators 2026-10-25 16:45:34 +11:00
sam 18eed1fb96 fix(webui): refuse change captures whose file entries have the wrong key set 2026-10-25 16:45:34 +11:00
sam 55c201e7c1 fix(builtin): send_file resolves symlinks before the confinement check 2026-10-25 16:45:34 +11:00
sam 54a78175b4 feat(workflow): render a PRD's generated view on the plan approval card
agent.run gains views: the agent may return an OpenUI Lang view of its
answer through an optional view tool, read as steps.<id>.view. human.approve
stores it as the task's plan_view, and the approval card renders it with
the dashboard's own components, falling back to the plan text when there
is no view or it does not parse. The feasibility prd step uses it.
2026-10-25 16:33:04 +11:00
sam cae19ca42e fix(ui): name and link the identity a parked reason names 2026-10-25 16:24:03 +11:00
sam d4558c15d3 test(daemon): a task start parks transient when the policy chain is unavailable 2026-10-25 16:23:16 +11:00
sam 75c1dbf83c fix(access): check the policy version before each decision
archied, archie-ui and the tool gateway re-read the stored policies on a 30s
ticker, so a forbid written seconds earlier did not stop a run. One
instance-wide revision now moves inside the transaction of every policy write,
and a decision reads it first and rebuilds the engine only when it moved.

A version read that fails, or a policy list that fails after a bump, refuses
with ErrChainUnavailable instead of standing on the last chain, so three call
sites now treat unavailable as availability rather than denial: dispatch leaves
the capture for the next cycle, a task start parks transient, and the tool
gateway reports the tool as unavailable.
2026-10-25 16:21:01 +11:00
sam 536155752c test(egress): a recording session performs no central tool call 2026-10-25 16:02:46 +11:00
sam 958561d255 feat(egress): record a test run's deliveries instead of sending them
A test run used to suppress only forge and push writes, which named one
destination among many. Deliveries now have one seam: TaskContext.Deliveries
records each as "would ..." and performs none, and a recording egress
session does the same for a Kit run's HTTP writes and central tool calls,
answering them synthetically. Provider hosts stay live, since model traffic
is how a test run reads. Native containers have no proxy (archie-core-n8d3).
2026-10-25 16:01:06 +11:00
sam 7cd62232ef feat(webui): add WebMCP task actions 2026-10-25 15:47:59 +11:00
sam 32b73c3a28 fix(store): post open chat task states once after the posted-status migration 2026-10-25 02:46:43 +11:00
sam b0137d6181 fix(daemon): archied --once drains until callees of a waiting call finish 2026-10-25 02:46:16 +11:00
sam a776de8b8f fix(archied): post each reportable status a chat task reaches, recorded by status not by flag 2026-10-25 02:42:31 +11:00
sam b577b02eb6 feat(archied): tell the chat when its task opens a pull request 2026-10-25 02:39:34 +11:00
sam b006b1c943 fix(ui): long log messages wrap inside the table 2026-10-25 02:23:29 +11:00
sam 4241dbf817 fix(ui): log table shows component on the Logs page and a bordered sticky header 2026-10-25 02:21:57 +11:00
sam 0ccd1793e3 fix(ui): the log table header sticks to the log frame 2026-10-25 02:20:29 +11:00
sam 29aad11bed fix(ui): sticky log table header and bounded stage and service columns 2026-10-25 02:19:05 +11:00
sam 6e33004ef2 feat(ui): the Logs page uses the task log's table 2026-10-25 02:17:35 +11:00
sam afca2c164f fix(ui): singular field count in the task log 2026-10-25 01:24:21 +11:00
sam c7e2160582 fix(ui): metadata labels size to their content and wrap in table details 2026-10-25 01:22:59 +11:00
sam 849e24757d feat(ui): task logs as a table with expandable fields 2026-10-25 01:21:21 +11:00
sam e143362479 fix(ui): centre the plan in the approval card 2026-10-25 00:50:16 +11:00
sam 4146600579 fix(ui): put the approval card in the task page's main column 2026-10-25 00:46:18 +11:00
sam a04afe8d4e fix(ui): size the approval card to its text so the answers sit beside it 2026-10-25 00:38:02 +11:00
sam 550bb60691 fix(ui): hold the plan to a readable line length 2026-10-25 00:36:45 +11:00
sam df54db239d fix(ui): plain text for the plan's title on the approval card 2026-10-25 00:17:27 +11:00
sam de532ca299 fix(ui): approve a plan from a card that holds the plan and both answers 2026-10-25 00:16:10 +11:00
sam d7fc4e1fe9 feat(archied): post approval requests to the chat that started the task 2026-10-24 23:59:25 +11:00
sam e8a60c4abd refactor!: waiting_human becomes waiting_approval, with the approval kind on each task 2026-10-24 23:45:20 +11:00
sam 1f8a9964c1 fix(ui): show the plan and Approve/Reject on a task waiting for approval 2026-10-24 23:35:31 +11:00
sam aabe8f7a80 fix(archied): post dashboard chat task outcomes into the conversation through the gateway 2026-10-24 23:22:11 +11:00
sam fe9bdefc62 fix(workflow): keep the failing lines when clipping gate output 2026-10-24 23:18:23 +11:00
sam 205d0ec976 feat(archied): update agent-image sets the image new tasks run 2026-10-24 23:16:13 +11:00
sam e9ecc84064 docs(config): cut the setup template to the settings that start the services 2026-10-24 22:26:33 +11:00
sam 3b7193c207 refactor!: remove the diff-size cap and its gate.diff-size step 2026-10-24 22:19:23 +11:00
sam 84cb0eb3fd build(agent): golangci-lint 2.14.0, which reads Go 1.27.3 export data 2026-10-24 22:00:30 +11:00
sam d9fda2338f test(secretengine): skip the host launch test where the kernel refuses namespaces 2026-10-24 21:54:04 +11:00
sam 64acc0e97a fix(ui): mount a fresh canvas menu at each right-click 2026-10-24 21:50:23 +11:00
sam 8d2307d12d fix(ui): close the canvas menu for a tick before reopening it at the pointer 2026-10-24 21:48:29 +11:00
sam 8c128592bd fix(ui): show full repo names and reopen the canvas menu at a new right-click 2026-10-24 21:46:12 +11:00
sam 39430d78ae Revert "fix(messaging): mask secrets embedded in chat tool arguments"
This reverts commit 9c9aefd296.
2026-10-24 20:56:31 +11:00
sam 9c9aefd296 fix(messaging): mask secrets embedded in chat tool arguments 2026-10-24 20:53:27 +11:00
sam e63489829e fix(ui): show non-text tool arguments as key: value pairs 2026-10-24 20:51:59 +11:00
sam 87bc53c278 feat(chat): show each tool call where it happened in the reply 2026-10-24 20:48:43 +11:00
sam 5bdf68594d fix(messaging): show tool argument values in chat, redacting only sensitive keys 2026-10-24 20:46:29 +11:00
sam f6988916d8 feat(gateway): record how long each chat tool call took and show it per row 2026-10-24 20:44:40 +11:00
sam aaccbcf984 fix(ui): show a chat tool run as N tool calls with one status row per call 2026-10-24 20:31:51 +11:00
sam f9e3c4eaa4 fix(ui): summarise a chat tool run as one line instead of per-tool counts 2026-10-24 20:30:27 +11:00
sam 97195bf2ac chore(workflow): say in a review post failure whether it carried inline comments 2026-10-24 18:27:17 +11:00
sam c787db7e07 chore(workflow): log where a review's comments are placed before posting 2026-10-24 18:18:54 +11:00
sam 12b5022a4f fix(workflow): repost a review without inline comments when the forge refuses their placement 2026-10-24 18:07:14 +11:00
sam 8c98f20f0e build(deps): bump ai-sdk to v0.3.2 for DeepSeek forced tool choices 2026-10-24 17:48:24 +11:00
sam 9e334c3627 fix(ui): let command rows shrink to their column 2026-10-24 17:45:36 +11:00
sam 66f06a1878 fix(ui): stop wide setting controls from stretching the row past its card 2026-10-24 17:29:12 +11:00
sam 6d7f341de5 fix(workflow): post review findings outside the diff in the review body instead of inline 2026-10-24 17:27:35 +11:00
sam 7973feceb0 fix(tools): compare protos against an export of main so the gate runs as any user 2026-10-24 17:27:34 +11:00
sam 8ccac46fc9 fix(ui): size the command list to its setting row 2026-10-24 17:18:05 +11:00
sam b70e791fed fix(ui): keep command fields to the row width 2026-10-24 17:16:55 +11:00
sam 1a57aa7216 fix(ui): edit gate and tooling commands as shell-quoted lines instead of argument chips 2026-10-24 17:15:41 +11:00
sam 102355aba5 fix(daemon): park a pushing workflow before it runs when its identity may not push, with a link to the connection 2026-10-24 17:06:25 +11:00
sam 9a08048744 fix(archied): stop retrying task outcomes for a channel messaging does not have 2026-10-24 17:02:50 +11:00
sam 793569f6e1 refactor(ui): build the task list on DataTable with sortable columns and row links 2026-10-24 13:29:57 +11:00
sam ffafc3a989 fix(ui): add a warn alert variant and fit org and model forms on phones 2026-10-24 13:26:35 +11:00
sam 951acb8088 refactor(ui): build settings, org, task, workflow and dashboard pages from the shared components 2026-10-24 12:34:29 +11:00
sam afc0c0319b fix(ui): merge type-scale sizes with colours and put the column picker in the header 2026-10-24 12:21:48 +11:00
sam 522dfa5703 feat(ui): add the shared design-system components and type scale 2026-10-24 12:20:01 +11:00
sam 332e444397 fix(ui): lay out appearance preferences as setting rows 2026-10-24 12:15:52 +11:00
sam 959e1e0520 fix(ui): shorten the missing-snapshot notice 2026-10-24 11:47:16 +11:00
sam d8572e17e6 fix(ui): cut copy that restates what a value is 2026-10-24 11:46:38 +11:00
sam b2f720cc2b feat(ui): split agents from services, choose status columns, open reasons from the state badge 2026-10-24 11:45:57 +11:00
sam c7fc55a0ef fix(ui): group consecutive chat tool calls and simplify the chat controls 2026-10-24 11:45:57 +11:00
sam e84dd0f7e2 fix(ui): give service problems room and drop rows and bars with nothing to say 2026-10-24 11:41:48 +11:00
sam 1624353b2b fix(readiness): name only the filesystems over their limit 2026-10-24 11:41:48 +11:00
sam 5e7b51710c fix(ui): trim the task page and draw a run's pinned definition on the canvas 2026-10-24 11:39:55 +11:00
sam 97466ad27d refactor(daemon): name a taskrun failure's cause in one place 2026-10-24 11:32:16 +11:00
sam 90c5f5075a fix(daemon): leave a task running when only the daemon is stopping 2026-10-24 11:30:45 +11:00
sam 4e97975862 fix(archieui): reach the sandbox and setup terminal on the daemon's listener 2026-10-24 11:24:49 +11:00
sam 64e398112f fix(container): keep agent output out of the exit reason 2026-10-24 02:28:01 +11:00
sam 2a5b50346c fix(ui): keep page controls clear of the chat dock and hide synthetic issue numbers 2026-10-24 02:25:26 +11:00
sam 6ff09f92a5 fix(releaseupdate): a development build names no release to compare 2026-10-24 02:25:25 +11:00
sam 07c8bf310d fix(daemon): say how an agent container ended when it dies mid-task 2026-10-24 02:25:25 +11:00
sam dc6c4826bc fix(ui): fold the workflow title into the toolbar band on desktop 2026-10-24 02:17:53 +11:00
sam d915a24f4d fix(webui): compare a describe build's release, not its raw version, for drift 2026-10-24 02:17:53 +11:00
sam 267528efba fix(ui): use the shared settings card on account, authentication, instructions and channels pages 2026-10-24 00:03:21 +11:00
sam ad827e34bb test(kitrun): drop the WorkerEnv wiring test 2026-10-22 17:39:37 +11:00
sam 69b8c482c1 fix(config): read a model alias's provider the way the resolver does 2026-10-22 17:39:13 +11:00
sam aac77950f2 fix(configuration): keep named instances under the archie- namespace 2026-10-22 17:38:40 +11:00
sam 614ab1e6fa fix(workflow): require triage's workflow when a code change is needed 2026-10-22 17:37:33 +11:00
sam 2e6c493487 fix(config): give a non-system org only the aliases its policy resolves 2026-10-22 17:36:24 +11:00
sam 2ca7c9b2b9 fix(daemon): relay a loopback State Store with external NATS, and only for the task's container 2026-10-22 17:35:24 +11:00
sam b395eec893 fix(archiegateway): confine non-operator chat identities to their own tasks 2026-10-22 17:32:55 +11:00
sam 5675284b08 fix(controlplane): keep an org's own provider credential reference 2026-10-22 17:31:54 +11:00
sam cbe998b598 Merge pull request #1818 from samcharles93/fix/triage-non-code-path
fix(triage): let a task that needs no code change be classified
2026-10-22 13:52:18 +11:00
sam fc0dd41092 fix(triage): let a task that needs no code change be classified
The classify result required a workflow, and the capture tool rejects an empty
required string on the agent's single allowed call. A task needing no code
change has no workflow to name, so the classification failed instead of
closing the task -- the non-code path could never complete.

Require only what every classification has: whether a change is needed and the
reasons. Name the workflow required-when-true in its description, guard the
handoff on needs_code_change rather than relying on the finish step having
ended the run first, and comment the reasons before closing so the reporter
sees why nothing was built.
2026-10-22 13:50:47 +11:00
sam 2f8d375692 Merge pull request #1817 from samcharles93/fix/repo-tooling-stage
feat(workflow): install a repository's declared tooling before its gate
2026-10-21 23:11:52 +11:00
sam 8ed814cbf7 feat(workflow): install a repository's declared tooling before its gate 2026-10-21 23:11:16 +11:00
sam 852dd4f6c7 Merge pull request #1815 from samcharles93/fix/model-provider-credential-ref
fix(staterpc): carry each model provider's credential reference
2026-10-20 07:13:44 +11:00
sam 88514a444b fix(staterpc): carry each model provider's credential reference
The State Store wire described a provider's class, base URL and key variable
but never where its key lives, so every provider reached the daemon
credential-less. A task then built its runtime with no key: the egress session
had nothing to bind and the agent parked on 'APIKey is required'.

Carry api_key_engine and api_key_key alongside the provider. They are a
reference, not a secret; the key is still resolved daemon-side and never
travels to a container.
2026-10-20 07:10:58 +11:00
sam e33adbb12f Merge pull request #1814 from samcharles93/fix/egress-provider-secret-ref
fix(egress): bind a task's model providers from their api_key_ref
2026-10-20 06:57:31 +11:00
sam ae178f1be0 fix(egress): bind a task's model providers from their api_key_ref
A container task parked when a provider carried an api_key_env but no
credential binding named after it, even though the task's models never
reached that provider. Egress pre-bound every provider the instance
configures and ignored api_key_ref, so the credentials an operator stores in
provider-settings were never used.

A task's config now carries only the providers its model aliases resolve to,
each with the variable its credential is read from: the operator's
api_key_env, or a name derived from the provider when its credential is a
secret reference. modelEgress resolves that reference once for the session
and the proxy substitutes the session's key for the sentinel, so the
container still holds no key. A provider that only declares an env var keeps
resolving through its org credential binding.
2026-10-20 06:56:38 +11:00
sam d1b7a21b9b Merge pull request #1813 from samcharles93/fix/default-org-providers
fix(controlplane): resolve the default org's providers with its aliases
2026-10-20 03:44:53 +11:00
sam bf4fde5f7d fix(config): keep the resolved aliases when an org supplies none 2026-10-20 03:44:21 +11:00
sam 6194a51ed0 fix(controlplane): resolve the default org's providers with its aliases 2026-10-20 03:44:21 +11:00
sam 4847fb0b77 Merge pull request #1811 from samcharles93/fix/container-state-store-reachability
fix(daemon): give a task container a reachable State Store endpoint
2026-10-20 03:25:36 +11:00
sam fd241a59cc Merge pull request #1810 from samcharles93/fix/agent-empty-status-parks
fix(daemon): park a task whose agent reported no status
2026-10-20 03:24:38 +11:00
sam 0f0f048380 Merge pull request #1812 from samcharles93/fix/messaging-session-save
fix(gateway): save a messaging session instead of requiring web visibility
2026-10-20 03:24:00 +11:00
sam 974c93498a fix(gateway): save a messaging session instead of requiring web visibility 2026-10-20 03:12:40 +11:00
sam 92bc0f692f fix(daemon): give a task container a reachable State Store endpoint 2026-10-20 03:12:21 +11:00
sam 7b2af3348d fix(daemon): park a task whose agent reported no status
runViaAgent logged the agent's reply status and returned, so a task whose
agent could not persist its own outcome (empty status, State Store down)
stayed running with no park reason while the run read as complete.

A status the task cannot reach from running now parks it, quoting the
status and naming the condition.
2026-10-20 03:10:33 +11:00
sam 89cbbfc871 fix: chat streaming blocking the UI. extensions not showing accepted policies once accepted. (#1809)
* fix(ui): show an extension's accepted authority after it is accepted

* fix(ui): keep a chat reply's streamed text when the turn is stopped or fails

* feat(ui): queue chat messages sent while a turn runs
2026-10-19 18:53:13 +11:00
sam e955c45ba8 fix(egress): name the denied target when refusing a tunnel CONNECT (#1808) 2026-10-19 07:50:58 +00:00
sam 1ed8d4f543 fix(archiegateway): create the chat workspace before enabling its tools 2026-10-19 11:15:20 +11:00
sam 19e5dcd9d0 fix(gateway): chat acts as the control-plane operator and sees every task 2026-10-19 11:12:34 +11:00
sam caafdb266f feat(webui): scope cookies to the instance and show non-default instance names 2026-10-19 10:17:05 +11:00
sam 412d73e7e1 feat(install): install and update a named instance side by side 2026-10-19 10:16:49 +11:00
sam 76c0e4dd1b fix(container): scope agent containers, volumes and the egress relay to the instance 2026-10-19 10:15:47 +11:00
sam b8b223c87c feat(configuration): name the instance with ARCHIE_INSTANCE and scope default paths by it 2026-10-19 10:12:48 +11:00
sam 9d3ea208ef docs(news): regenerate release notes from the changelog 2026-10-19 10:05:23 +11:00
sam 5a55196572 docs: edit guides, PRDs and security notes, regenerate release news 2026-10-19 10:04:36 +11:00
sam 35e9d5d64e feat(ui): wrap the YAML editor at the pane or a set print width, with an appearance setting 2026-10-19 09:41:03 +11:00
sam b47f768076 feat(ui): scroll past the end of the YAML editor and history diff, with an appearance setting 2026-10-19 09:34:32 +11:00
sam 6630b0c9bf fix(ui): clear the chat on /new, show the copy action on hover, fold settings into the bar's menu 2026-10-19 09:01:44 +11:00
sam 1b2a8eec7c feat(chat): ask several questions in one interaction with ask_questions
A turn can pose a questionnaire (single and multiple choice, free text,
skippable) and read the answers back, rendered in the chat with the
shadcn-vue questionnaire. The gateway contract gains a questionnaire ask and a
can_question capability; answers travel as a JSON object keyed by question name
and are checked against the questions that were asked.
2026-10-19 03:30:47 +11:00
sam 31da6dc7c2 feat(ui): show a capture's changed files as a folder tree 2026-10-19 03:24:03 +11:00
sam d873cb5476 feat(ui): chat tool calls, approvals and suggestions on shadcn-vue's trace, item and button patterns 2026-10-19 03:19:07 +11:00
sam 5179bc81b7 fix(ui): anchor each question in the chat transcript and keep the live reply as the row its message takes 2026-10-19 03:13:12 +11:00
sam 26e3d2bff2 feat(ui): fade the chat's borders in when it opens and close it on an outside click 2026-10-19 03:09:57 +11:00
sam 61ee5fd3a7 feat(ui): dock the chat at the bottom of every page and keep a skeleton while a conversation loads 2026-10-19 03:01:12 +11:00
sam 0eecc95aac feat(ui): one chat panel on every page; the workflow editor syncs its draft around a turn
Replaces the separate Build with Archie bar and its per-workflow channel, so
every conversation belongs to the account and is listed on every device, and
the command palette is the same everywhere.
2026-10-19 02:56:23 +11:00
sam 3bb8f73c6a feat(ui): offer only conversation commands in the workflow editor's chat 2026-10-19 02:53:06 +11:00
sam 890361468d fix(ui): stop clipping the slash palette above the Build with Archie bar 2026-10-19 02:47:22 +11:00
sam 889856aa81 feat(ui): Build with Archie runs on the chat system, floats over the canvas and keeps its conversation
Each workflow has its own persisted conversation, rendered like the chat panel.
The canvas and YAML go read-only while Archie works instead of inert. The code
block highlighter loads Go and TOML and drops jsx, tsx and vue.
2026-10-19 02:43:54 +11:00
sam 63adbc71ef feat(ui): code blocks and chat messages from shadcn-vue's code-block, message and bubble 2026-10-19 02:22:42 +11:00
sam d876c150eb refactor(ui): one key/value list for a task's inputs, outputs and details, sized to its content 2026-10-19 02:10:46 +11:00
sam 3202386eaa feat(ui): list a task's inputs and outputs as separate sections of one card 2026-10-19 02:07:26 +11:00
sam eade816ee0 fix(webui): return an interrupted stage's cause and show it in a warning tone 2026-10-19 02:05:45 +11:00
sam f9861d3ea5 fix(ui): drop the duplicate start time from a task's stages 2026-10-19 01:59:47 +11:00
sam 580108dd7f fix(ui): frame the task page's attempts, stages, details and inputs, and fit the run tabs on a phone 2026-10-19 01:56:38 +11:00
sam 30105666e2 fix(ui): show a parked task's error once and wrap long log lines on a phone 2026-10-19 01:47:34 +11:00
sam 8d0d707d3e fix(postgres): repin parked and queued tasks that still name the root identity 2026-10-19 01:45:48 +11:00
sam c94a943854 fix(ui): improve keyboard access and add headed checks 2026-10-19 01:45:20 +11:00
sam 12685e264d fix(ui): show the agent's name, not its id, in a workflow's Runs as 2026-10-19 01:42:47 +11:00
sam 1e56219bbe fix(ui): label the default credential grants as Default, not Root identity 2026-10-19 01:39:27 +11:00
sam ab43c4e337 fix(archied): stop flagging embedding and transcription aliases as retired models 2026-10-19 01:07:39 +11:00
sam 02d4e162b8 fix(ui): fit phone workflows and allow dynamic handoffs 2026-10-19 01:04:32 +11:00
sam cc4f20ce30 fix(ui): align alert times in a right column and lift the body contrast 2026-10-19 01:02:38 +11:00
sam 10e1207242 fix(ui): date an alert from when it was first raised, not last re-checked 2026-10-19 01:01:19 +11:00
sam 24c3f7e857 feat(ui): show when each alert last fired 2026-10-19 00:43:23 +11:00
sam a76c54d1ac feat(e2e): list checks by default and run all explicitly 2026-10-19 00:38:17 +11:00
sam 9fea68815e fix(ui): one chat toolbar row, compact session actions menu, smaller bubble text 2026-10-19 00:32:56 +11:00
sam 9ff62f2cc4 fix(ui): section icons in the phone menu 2026-10-18 23:53:44 +11:00
sam 3f0fd7409d build(ui): regenerate dashboard 2026-10-18 23:50:32 +11:00
sam bb8f716abd fix(ui): put the workflow overflow menu at the end of the editor toolbar 2026-10-18 23:50:17 +11:00
sam 4201512912 fix(ui): end the switch otherwise edge at a marker in its own column 2026-10-18 23:50:09 +11:00
sam 409b5e6e54 fix(ui): draw no run state on the canvas for a run without a pinned definition 2026-10-18 23:50:03 +11:00
sam 490532643e fix(ui): hide the Runs tab for a never-published workflow 2026-10-18 23:49:55 +11:00
sam b6f4481038 fix(ui): drop the stray dot beside the end insert point 2026-10-18 23:49:50 +11:00
sam 227a991388 fix(ui): move workflow enable toggle into the editor toolbar, tie it to the published version 2026-10-18 23:49:41 +11:00
sam 18bb7b7dcb fix(ui): let the phone canvas fill the height reserved for the chat launcher 2026-10-18 23:49:35 +11:00
sam d40ba948e9 fix(ui): give the mobile workflow picker the header row, drop the duplicate Draft badge 2026-10-18 23:49:17 +11:00
sam 7f5fbe4135 fix(ui): show workflow validation errors on the failing step and link to it 2026-10-18 23:49:09 +11:00
sam 86d4066084 fix(ui): render watched-run actions secondary so Publish stays the toolbar primary 2026-10-18 23:48:58 +11:00
sam 912f5e99ff fix(ui): label run picker statuses with the shared status name 2026-10-18 23:48:47 +11:00
sam 1d4278c5d2 fix(ui): open draft change review only when there are changes 2026-10-18 23:48:42 +11:00
sam 3871b820d9 fix(ui): grey out disabled Publish and give the reason on hover 2026-10-18 23:48:42 +11:00
sam 18d36b00bc fix(ui): dismiss all alerts and show the full alert list 2026-10-18 23:48:42 +11:00
sam 5e62f8311f fix(ui): short run picker label that ellipsises 2026-10-18 23:48:42 +11:00
sam 8e0614436b fix(ui): open the workflow canvas at the top and keep the list within the viewport 2026-10-18 23:47:18 +11:00
sam 68b8e5d00a fix(ui): open validation errors from the indicator and link each to its step 2026-10-18 23:47:14 +11:00
sam a202c280d8 fix(ui): enable Publish only when the draft has changes 2026-10-18 23:47:01 +11:00
sam ff5cab992b fix(postgres): task alert body carries the truncated task title, not a restated title 2026-10-18 23:46:48 +11:00
sam 46f3c881ec fix(ui): fill the viewport instead of a rounded inset frame 2026-10-18 23:46:34 +11:00
sam a54fec0b43 fix(ui): titles on truncated step badge and trigger labels 2026-10-18 23:46:30 +11:00
sam f2a1aedbc2 fix(ui): workflow names in the sans face 2026-10-18 23:46:25 +11:00
sam fbe0742ef6 fix(ui): group run picker and run actions apart from workflow edit actions 2026-10-18 23:46:19 +11:00
sam a0524c0cf3 fix(ui): make the whole alert item open its link 2026-10-18 23:45:54 +11:00
sam bc7f4390b1 fix(ui): bound option select lists to the trigger side and ellipsise labels 2026-10-18 23:45:28 +11:00
sam e5520ae4e5 fix(ui): fade the hidden edges of horizontally scrolling tab rows 2026-10-18 23:45:28 +11:00
sam 06014f4a39 fix(ui): keep OIDC save in its card and make the redirect URI copyable 2026-10-18 23:45:27 +11:00
sam addd9b8f14 fix(ui): give every workflow row the same status line with a titled delivery bar 2026-10-18 23:45:27 +11:00
sam 0d78e26e8d fix(ui): mark the step failing validation on its canvas node 2026-10-18 23:45:27 +11:00
sam bc291255e8 fix(ui): move neighbouring columns aside when a step card opens 2026-10-18 23:45:27 +11:00
sam 5aba9b8707 fix(ui): drop stale alert loads so badge and list agree 2026-10-18 23:45:27 +11:00
sam 6c555adb79 fix(ui): give canvas zoom controls tooltips and larger hit targets 2026-10-18 23:45:27 +11:00
sam 3eca2ef5df fix(ui): step page, workspace, card and canvas surfaces apart 2026-10-18 23:45:26 +11:00
sam 491c1fa683 fix(ui): hide the chat launcher on the workflow page, where the Archie bar is the entry point 2026-10-18 23:45:26 +11:00
sam 4fe217ef0e fix(ui): dim the top bar under the section sheet 2026-10-18 23:45:26 +11:00
sam 872958127a fix(ui): label the no-run picker option as the current definition 2026-10-18 23:45:26 +11:00
sam 32735a2ab1 fix(ui): rename a step to a valid step id 2026-10-18 23:45:26 +11:00
sam f300b96251 fix(ui): anchor the alerts badge beside the bell instead of over it 2026-10-18 23:45:26 +11:00
sam b1d38bb7b7 fix(ui): put the new workflow button on the workflow list 2026-10-18 23:45:26 +11:00
sam 0af9ac496e fix(ui): mark each trigger on the start node with its kind 2026-10-18 23:45:25 +11:00
sam fd30a24079 fix(ui): product logo heads the phone section sheet 2026-10-18 23:45:25 +11:00
sam 0749f45054 fix(ui): outline the workflow toolbar overflow button to match Test and Run 2026-10-18 23:45:25 +11:00
sam 168ddde0dd fix(ui): align branch lane ends and route the unmatched switch path down its own lane 2026-10-18 23:45:25 +11:00
sam 0d6d5e7dd3 fix(ui): one name for the workflow chat bar 2026-10-18 23:45:25 +11:00
sam 27c70d8e24 fix(ui): style notification group labels as panel headings 2026-10-18 23:45:25 +11:00
sam 0275e9e75f fix(ui): one insert chip per earlier step, inserting its summary 2026-10-18 23:45:24 +11:00
sam c618b30013 fix(ui): size the alerts panel to the phone viewport 2026-10-18 23:45:24 +11:00
sam cbb2e823da fix(ui): select the next workflow after deleting one 2026-10-18 23:43:24 +11:00
sam 113da1cd4b docs: the production-readiness goal until 1 December 2026-10-18 23:05:28 +11:00
sam a9ae4ab3f1 docs: forge is one of many inputs or outputs; drop the expired temporary note 2026-10-18 22:57:18 +11:00
sam 3be983c650 docs: a forge is an event source and output destination, not core 2026-10-18 22:55:22 +11:00
sam 7b680f8ac6 fix(ui): icon-only run button matches the 32px icon size 2026-10-18 22:52:19 +11:00
sam b6057a0a11 build(ui): regenerate dashboard 2026-10-18 22:42:51 +11:00
sam 3bebdb2af7 fix(ui): keep the workflows toolbar readable on the 36px ladder
The run selector is the only control that gives up width, and beside the
workflow list it had none left: Open and the run's version move into the one
menu at every width, so the picked run stays readable from 390 to 1440.

Step editor and binding fields take the next rung (h-8) so they match the
selects and switches they sit beside.
2026-10-18 22:42:14 +11:00
sam dd80fcb337 build(ui): regenerate dashboard 2026-10-18 22:29:59 +11:00
sam 2b523fe7e0 fix(ui): burger section sheet at phone width, 36px control scale
The coarse-pointer rule gave every button, link and field a 44px minimum on
touch, which made the phone dashboard look like a toy and pushed the section
strip into overlapping its neighbours. Controls now keep their own size, and
the shared ladder is one step taller (default 36px, sm 32px) so a finger still
hits something. Inputs stay 16px only where iOS would zoom.

Below md the sections move into a sheet with the current page marked; the bar
keeps brand, search, alerts and the operator. Page titles drop to 18px so the
title and its action sit on one centred line.
2026-10-18 22:29:25 +11:00
sam 39e33e75a3 fix(ui): one workflows toolbar row, one menu, no repeat step type
The step editor's More disclosure no longer fills when open, so only the
chevron moves. A step card keeps its type chip only when its title does not
already say it.

The editor header is one toolbar at every width: view tabs left, the run
selector and actions right, and a single menu holding the sections that do
not fit, the run's own actions and the draft's change list. Publish is the
one primary action. Restore replaces Discard draft and the per-workflow
Restore default, which settings owns.

The page header no longer wraps, and run rows on a phone no longer squeeze
the run title.
2026-10-18 22:29:25 +11:00
sam 991b40047a fix(ui): Instructions replaces SOUL in routes and agent pages; terse alerts; missing-key hint 2026-10-18 19:27:11 +11:00
sam 39e44e9da9 build(ui): regenerate dashboard 2026-10-18 15:55:08 +11:00
sam 499898a4fc fix(ui): distinguish loading, failed and empty lists, one role label set, en dash for no value 2026-10-18 15:54:31 +11:00
sam de7571f91e fix(ui): keep the chat launcher and Archie bar clear of controls and the canvas
Reserve bottom space for the floating launcher at phone width, drop the
duplicate provider class and the setup guidance sentence, give the source
and model rows room to size, place the Archie bar below the canvas, use the
shared Empty on the not-found page, and let the org overview list titles.
2026-10-18 15:54:31 +11:00
sam fd8d2c1941 fix(ui): one text colour scale, Empty for page empty states, token requests through api 2026-10-18 15:03:44 +11:00
sam e953fc8891 fix(ui): trim workflow and log captions, select components for event binding 2026-10-18 15:02:00 +11:00
sam b9d28418e8 fix(ui): tighten tasks page prose and phone layout 2026-10-18 15:02:00 +11:00
sam 3f46d2ec33 fix(ui): trim settings prose, inline switches, wrap narrow add forms 2026-10-18 15:02:00 +11:00
sam 81f1be388e fix(ui): trim view captions and empty-state copy in org, accounts, curators and skills
Drop captions that restated headings, cut the duplicate Policies card title,
use the Select component for account roles, let org agent actions wrap on
phone width, and use em-free placeholders.
2026-10-18 15:02:00 +11:00
sam 4b921227c5 fix(ui): trim view prose, en dash placeholders, collapse fixed grids on phones
Drop empty-state essays that repeated their titles, the harness native select
becomes the Select component, and the binding and source forms collapse to one
column below sm. Issue-ID and history narration removed from comments.
2026-10-18 15:02:00 +11:00
sam c0bd7bb6a3 fix(ui): drop history narration and em dashes from chat and dashboard comments 2026-10-18 15:02:00 +11:00
sam 0cec2ec16d docs(ui): record the presentation rules 2026-10-18 14:57:50 +11:00
sam 7120cf52a2 fix(ui): check step names drop the repeated gate 2026-10-18 13:20:52 +11:00
sam cc9151425f fix(ui): plus-only new workflow; restore default workflows moves to task settings 2026-10-18 13:18:21 +11:00
sam c744928e07 fix(ui): the workflow switch needs no Enabled label 2026-10-18 13:15:53 +11:00
sam 6529613496 fix(ui): drop the log and change-file status captions 2026-10-18 13:14:52 +11:00
sam 010c8b28dd docs(ui): no captions that describe the view 2026-10-18 13:10:26 +11:00
sam 198702010f fix(ui): drop captions that only describe the view 2026-10-18 13:09:55 +11:00
sam ffffaa9fe6 fix(ui): put the Archie bar under the canvas on phones so it cannot cover a step 2026-10-18 13:04:43 +11:00
sam 90b7d28627 fix(ui): pick the workflow and the revision from a select on narrow screens
The workflow list scrolled sideways off a phone screen and the history grid
pushed the diff off it. Below lg the list becomes a header select with the
draft badge; below md the revision list becomes a select above a full-width
diff, with the two canvases stacked.
2026-10-18 12:32:32 +11:00
sam d8b4e04861 fix(ui): keep the YAML gutter aligned on phones and fit the editor to a phone viewport
The gutter printed one number per source line while the text layer wrapped,
so every line after a long one was numbered wrong. The textarea no longer
wraps: the gutter, the highlight layer and the textarea share one row per
line and scroll together on both axes.

Below md the section tabs that do not fit collapse into one menu that sets
the same tab, and the actions share one right-aligned row. The canvas is
sized to the viewport left on a phone, frames a graph or card wider than the
canvas instead of clipping its edges, and clears the chat launcher.
2026-10-18 12:32:21 +11:00
sam 8c1756d312 fix(ui): scale touch targets to the pointer, not the window width
A coarse-pointer-only floor keeps switches, tab triggers and scrolled nav
strips from being deformed on a phone, and the topbar reveals the current
section after a route change.
2026-10-18 12:32:10 +11:00
sam 5989f0b45f fix(ui): finish an Archie turn across tab switches and name map entries in the settings review 2026-10-18 02:52:49 +11:00
sam 846626fabf feat(gateway): read instructions and access policies from the workflow tools
settings_get now reads three more kinds:
- soul, the instruction text layered into a workflow run;
- task-policy, the diff cap and alert delivery settings;
- org-model-policy, which models an org may use.

None of them holds a secret value: task-policy's notify_secret and the
secrets elsewhere in the readable kinds are SecretRef references (engine and
key), never the resolved value.

access_policies_list is new: the caller org's Cedar policies (id, level,
scope, text), and the instance policies when the caller owns the instance,
which is what the dashboard lists for the same read. It is guarded as
access.ActionRead on access.KindPolicy, the check the dashboard makes.
IntegrationSource gained Policies, implemented over the State Store's
ListPolicies.

workflow_get now says how its instructions field layers: after the
instance's and the organisation's, before the repository's.
2026-10-18 02:39:25 +11:00
sam 7768fa808d fix(gateway): workflow and integration tools ask the access policies as their caller 2026-10-18 02:35:59 +11:00
sam 39c3c47ea2 feat(gateway): workflow and integration tools for chat and Kit harnesses alike 2026-10-18 02:32:30 +11:00
sam f5770fdc6e fix(workflows): lock the editor while Archie writes the draft 2026-10-18 02:29:12 +11:00
sam b4595bf8bb feat(workflows): iterate on a workflow's draft with Archie from the canvas 2026-10-18 02:27:41 +11:00
sam 8e3711b73c feat(workflows): edits save as a draft and reach the running workflow only on publish 2026-10-18 02:21:54 +11:00
sam 55deeaa88c feat(ui): revert single changes in settings and workflow review 2026-10-18 02:18:23 +11:00
sam f10199f0b6 feat(ui): workflow canvas cards expand in place instead of side panels 2026-10-18 01:59:09 +11:00
sam eb6aaca1f5 feat(credentials): grant credential services to dashboard identities, chosen from pickers 2026-10-18 00:43:31 +11:00
sam 9167c861d6 fix(postgres): run stored workflows that name the root identity as the seeded agent 2026-10-18 00:29:14 +11:00
sam 2d1bbb6e6a feat(tasks): a work request's description is optional 2026-10-18 00:24:42 +11:00
sam d82e316f9b fix(ui): keep a numeric workflow input as text so the run form does not crash 2026-10-18 00:08:41 +11:00
sam 33f5290015 feat(instructions): layer instance, organisation, workflow and repository instructions into every agent stage 2026-10-17 23:42:39 +11:00
sam aa1e2ca660 feat(kit): central tools for harnesses through the egress proxy and gateway task-tool RPCs 2026-10-17 23:42:37 +11:00
sam 86600c3884 build(ui): commit the dist assets the accordion and connection fixes changed 2026-10-17 23:16:22 +11:00
sam c6c7a44c5b fix(ui): show a connection's saved forge and identities; selection data lives in the stores 2026-10-17 23:05:14 +11:00
sam 0652ded616 fix(ui): let accordion content overflow sideways so row tints keep their margin 2026-10-17 23:02:31 +11:00
sam 2d3b6d0d87 fix(ui): pad tinted setting rows so the tint is not clipped 2026-10-17 22:58:58 +11:00
sam b25263308b feat(repos): access check reports the operations the agent can perform 2026-10-17 22:58:01 +11:00
sam 1410fbc565 fix(ui): drop redundant connection labels and hints 2026-10-17 22:26:31 +11:00
sam c72c443090 feat(ui): choose a connection's permitted identities from the identity list 2026-10-17 22:07:27 +11:00
sam 6f29790b76 feat(ui): choose a connection's forge type from the enabled forge extensions 2026-10-17 22:06:13 +11:00
sam d936609188 build(taskfile): rebuild binaries when embedded files change 2026-10-17 21:56:25 +11:00
sam 8aa59bdb51 fix(postgres): allow the agent org upgrade phase 2026-10-17 21:55:42 +11:00
sam f0eee80ab7 fix(staterpc): derive harness secret org from caller grants 2026-10-17 21:44:08 +11:00
sam 7f9486fff1 refactor(servicekit): stop linking the State Store and control plane into archie-messaging 2026-10-17 17:22:53 +11:00
sam e9f45eeb8b feat(ui): default the workflow's run-as identity to the seeded agent 2026-10-17 17:21:58 +11:00
sam 127e5e70a0 build(taskfile): drop unused tasks and share the dev State Store wait 2026-10-17 17:21:10 +11:00
sam 334787c140 fix(install): name the required Go version when its toolchain is unavailable 2026-10-17 17:19:08 +11:00
sam 2cdf3b2c85 build(dev): serve the dev State Store over TLS on the Docker bridge so task containers reach it 2026-10-17 17:19:08 +11:00
sam bf14695eab feat(workflow): pr-review submits REQUEST_CHANGES on blocking findings and lists unanchored ones in the review body 2026-10-17 17:17:48 +11:00
sam a4da914994 fix(identity): emit RFC 4122 shaped stable IDs and migrate stored ones 2026-10-17 17:16:20 +11:00
sam fefbe19011 fix(archiemessaging): announce READY after channels bind; run notifying units as Type=notify 2026-10-17 17:15:34 +11:00
sam a2ade2ee42 fix(config): treat a [[curators]] entry without enabled as on 2026-10-17 17:15:34 +11:00
sam 2e7158a760 fix(workflow): remove the pr-review snapshot when any phase ends the run 2026-10-17 17:14:31 +11:00
sam 1cd0ed22f5 refactor(curator): rename SessionSummary to SessionRef 2026-10-17 17:12:52 +11:00
sam db982f2d93 refactor(workflow): drop the root identity alias from workflow definitions 2026-10-17 17:09:37 +11:00
sam 44a10943c3 feat(webui): link parked tasks to the page that fixes their blocker 2026-10-17 17:08:24 +11:00
sam 055e0250bd feat(identity): seed a narrow agent identity and run shipped workflows as it 2026-10-17 17:04:43 +11:00
sam 48dc39a3d5 fix(ui): 44px touch targets on narrow and coarse-pointer viewports 2026-10-17 17:01:27 +11:00
sam f45ea9e0aa feat(workflow): configure review precision and approval on the review.pr step 2026-10-17 17:00:55 +11:00
sam ab16bc673d fix(releaseupdate): run the release's watchdog and bound control-plane calls 2026-10-17 17:00:04 +11:00
sam 7b504f9ed6 refactor(archied): discover issues through organisation connections 2026-10-17 13:38:46 +11:00
sam 9d7287c647 feat(taskactions): retry a parked task on the current workflow definition 2026-10-17 13:35:12 +11:00
sam c80d4750a8 feat(archied): dispatch every organisation's schedules 2026-10-17 10:19:32 +11:00
sam e579b908f3 chore(postgres): delete unused queries 2026-10-17 10:17:14 +11:00
sam 01acb97f96 chore: delete code no binary or test reaches 2026-10-17 10:14:26 +11:00
sam 7986ccb3f7 fix(workflow): clip park details within the store cap and share the diff-rule blocking level 2026-10-17 10:11:07 +11:00
sam e452451926 fix(ui): state credential and connection status without internal service names 2026-10-17 10:10:03 +11:00
sam 9b7e7fc221 refactor(postgres): split lifecycle exit side effects out of Apply 2026-10-17 10:10:02 +11:00
sam 42ba637935 fix(postgres): keep every organisation an active owner 2026-10-17 10:07:45 +11:00
sam 6aced84146 fix(daemon): open model egress only for workflows with a model step 2026-10-17 10:03:12 +11:00
sam 05987f04e2 feat(daemon): execute and verify organisation repository connections 2026-10-17 09:32:39 +11:00
sam 32642af4a9 feat(ui): give organisation, instance and account clear homes
The Access area mixed organisation, instance and personal settings under
one name. Split them: /org is the organisation's own area (members,
identities, connections, models, schedules, playbooks), /settings is
instance administration only, and personal security stays in the account
menu. Setup checklist steps now link to the page that fixes them.
2026-10-17 09:01:41 +11:00
sam 62ee8a0381 fix(controlplane): name a migrated connection for its host
The seeded root connection was called "Instance forge", which names two
archie concepts an operator never chose. Name it for the host it points at
instead.
2026-10-17 08:59:57 +11:00
sam 30216dd367 fix(e2e): build stack with release metadata 2026-10-17 08:47:05 +11:00
sam cbc4cf309d fix(webui): bind task requester to authenticated principal 2026-10-17 08:42:08 +11:00
sam 4217a50874 fix(ui): connections copy states the field, not the model
Drop the sentence explaining that the credential is a reference and that an
identity with no entry is not granted: both lectured at the operator instead of
labelling the field. The external account needs no hint, the forge type keeps
one line saying where the value comes from, and the identity button reads the
way the credential-grants control already does.
2026-10-17 03:25:30 +11:00
sam a8a27eb4a4 fix(ui): clarify connection permission guidance 2026-10-17 03:24:20 +11:00
sam 8410271fdb feat(ui): configure forge connections in the dashboard
A Connections page under Settings lists the organisation's forge connections:
host, forge type, the reference to the credential (never its value), the
external account it belongs to, and the operations each execution identity may
perform through it. The chat agent's page registry names the page too.
2026-10-17 03:20:17 +11:00
sam fe97e92dd2 fix(daemon): execute dashboard identities with scoped authority 2026-10-17 03:13:30 +11:00
sam 9ab0121af0 feat(archied): a rotated connection reaches the next operation
The connections kind joins the live resource watches. On a new revision
archied re-resolves the instance forge from the settings it just published and
replaces every holder of the client: the boot forge, the worktree token, the
daemon's root forge and the root task RPC servers, which are now returned from
registration so a task that is already connected asks the new credential
rather than the one the process booted with.

This commit also carries the execution-identity agent's concurrent edits to
these three files, which the shared working tree had not committed yet.
2026-10-17 03:09:43 +11:00
sam 6132c12835 feat(controlplane): the instance forge is its root connection
Layering reads forge-connections and takes the root connection for the
instance's own forge, keeping the file's webhook intake and secret, which are
instance infrastructure rather than an account. A document with no root
connection disables the forge instead of falling back to a credential the
operator may have withdrawn.
2026-10-17 03:07:09 +11:00
sam cb48a27d16 feat(controlplane): organisation forge connections
A connection is an organisation's own resource: the forge host, the
credential reference and the external account it belongs to. It records a
reference, never a token value, and names per execution identity the
operations that identity may perform through it.

The file's [forge] sections seed it: the root's becomes the root connection
and each identity's own forge becomes a connection only that identity may
use, so the migration keeps exactly the grants the file expressed.
2026-10-17 03:05:01 +11:00
sam 3953a3a06c refactor(ui): move personal tokens and instance authentication out of Access
Personal API tokens are the signed-in operator's, and the instance URL and
OIDC providers are the instance's, so neither belongs under the organisation
Access area. Tokens render in the account page and Authentication moves to
Settings; the old paths redirect.
2026-10-17 02:41:24 +11:00
sam 139338cf34 docs(prompts): define organisation automation handoff 2026-10-17 02:25:32 +11:00
sam 41cd938748 fix(ui): repair settings editing and workflow diagnostics 2026-10-16 23:55:58 +11:00
sam 3229de9b3b fix(e2e): recover reliable local stack startup 2026-10-16 22:25:49 +11:00
sam dcc201e7bb fix(tasks): limit titles and display descriptions 2026-10-16 21:50:13 +11:00
sam 1b8abd3509 chore(release): v1.55.0 2026-10-16 03:57:48 +11:00
sam 7ebf842c5c feat(agent): frame the default SOUL around event-driven automation 2026-10-16 03:57:08 +11:00
sam 74699fcd21 refactor: remove personas
Personas were a misread requirement: SOUL is the chat identity and
identities are per action. The selected persona's prompt never reached the
model. Drops the resource, /personality, the chat selector, the settings
page and ChatService.SetPersona, and deletes stored persona documents.
2026-10-16 03:57:08 +11:00
sam f8b061c314 chore(release): v1.54.3 2026-10-16 03:46:35 +11:00
sam c5158edb6c feat(gateway): chat reads workflows and validates drafts
workflow_list, workflow_get and workflow_step_types read the org's
definitions and step catalog; workflow_validate runs the editor's save
check on a proposed definition without saving it.
2026-10-16 03:46:27 +11:00
sam 9ad270b9a4 chore(release): v1.54.2 2026-10-16 03:33:58 +11:00
sam 51328c9585 fix(deps): ai-sdk v0.3.1 so Gemini Interactions tool calls get valid arguments 2026-10-16 03:33:49 +11:00
sam aa1ca9e653 chore(release): v1.54.1 2026-10-16 03:11:22 +11:00
sam cb29967e7b fix(releaseupdate): find releases in the public releases repository
The source repository is private, so the updater and install.sh got 404.
Releases are now published to samcharles93/archie-releases by
task release:publish.
2026-10-16 03:11:14 +11:00
sam 474fd59759 chore(release): v1.54.0 2026-10-16 03:00:32 +11:00
sam 40ee9ffafa fix(rpc): bound gRPC servers and return listener failures
Cap concurrent streams, the handshake and dead peers' streams on every
service, drain shutdown for at most 10s, and stop messaging when its
listener dies instead of running on without Deliver.
2026-10-16 02:57:26 +11:00
sam 939b912889 refactor(ui): unify account administration under Access 2026-10-16 02:57:13 +11:00
sam 83aa17cf8b feat(identity): add browser setup and user accounts 2026-10-16 02:41:24 +11:00
sam 9cdae5642e feat(rpc): mTLS between services from operator-issued certificates
Replace the service bearer tokens with [tls] ca_file and cert_dir. Caller
identity comes from the verified certificate, not metadata. Without TLS,
services listen and dial on loopback only. Task containers get only the CA
and keep their grant.
2026-10-16 02:37:51 +11:00
sam dcf2972f26 feat(ui): start tasks from the dashboard and slim it to activity and setup 2026-10-14 23:28:37 +11:00
sam f96c44d092 refactor(scheduling): remove unused engine accessors 2026-10-14 23:10:35 +11:00
sam f537d5f8cd refactor: delete wrappers superseded by live entry points
Remove controlplanerpc.NewClient (superseded by NewRPCClient), Loader.Overlay
(-config-overlay reaches Resolve directly), and setup.Run (RunParams is
the live entry point). Move ResolverFunc into a test file, since only
tests adapt functions to the egress Resolver.
2026-10-14 23:10:35 +11:00
sam c833b651a9 fix(workflow): set BuildNoChanges from writable stages and clear it on commit
A writable agent stage that passes now marks BuildNoChanges; repo.commit
clears it when the stage commits changes. The flag had no setter, so the
signal was lost in the YAML migration. The outcome of an empty commit
stays with if_empty: unset still fails, complete closes the issue, skip
moves on.
2026-10-14 23:10:34 +11:00
sam 062f5332a0 refactor(gateway): delete unused wrappers and in-memory session store
Remove gateway re-exports of messaging helpers with no callers, the
unused DeltaFunc adapter, DefaultPersonas, NewStoreTaskCreator, the
SortBySeq stub, and the in-memory session store that nothing constructs.
2026-10-14 23:10:34 +11:00
sam d9fe384fd9 build(deps): bump ai-sdk v0.1.43 -> v0.3.0 and update dependencies
Gemini 3.x/4 chat now routes through the Interactions API transport, which
replays thought signatures on tool turns; long decode stays opt-in. Also
takes go get -u updates (x/*, genproto, goose, nats-server, modernc sqlite).
2026-10-14 23:10:34 +11:00
sam 8a7220f5e9 fix(gateway): isolate model selections by org 2026-10-14 21:19:34 +11:00
sam 5b9ff6fa47 fix(gateway): restore provider model selection in chat
Restore provider groups and concrete model references in chat snapshots. Permit catalog selections while retaining named aliases and tenant model restrictions. Show the active model in /profile without requiring a task identity.

Refs: archie-core-mvek6
2026-10-14 21:03:30 +11:00
sam 66b22f4833 build: trim filesystem paths from service and agent binaries 2026-10-14 03:49:31 +11:00
sam acec5d392d feat(archied): read-only run-scoped sandbox view over the harness contract (#1662)
* feat(archied): read-only run-scoped sandbox view over the harness contract

Serve RunTarget: the daemon resolves a running task and attempt to its Kit
container and follows its output, refusing a finished or unknown task with a
stated reason. The dashboard adds a Sandbox tab behind the task log's read
authority. Takeover stays out of scope until the sod1 authority is wired.

* fix(archied): scope and close sandbox views correctly

Forward harness activity into container output, bind containers and dashboard views to their attempt, enforce the asserted org, and report unavailable dependencies and interrupted streams accurately.

Refs: archie-core-qi91, archie-core-252tj
2026-10-14 02:57:32 +11:00
sam 59be81c7f6 fix(webui): an absent setting equals its zero value in drafts; setting rows get roomier padding 2026-10-13 20:20:03 +11:00
sam c0ac39b8da fix(webui): the danger setting row tints without shifting its content 2026-10-13 19:55:05 +11:00
sam 7b19935a14 build(webui): add the CardAccordion chunk missing from the bundle 2026-10-13 19:49:25 +11:00
sam fa7d0d83c1 fix(archied): report schedules apply status at start and on a timer 2026-10-13 19:08:55 +11:00
sam 7542e3b15e fix(archied): report workflow definitions apply status at start and on a timer 2026-10-13 19:06:53 +11:00
sam 6412e6d116 feat(webui): settings lists share a card accordion that opens the new item and blocks adding while unsaved 2026-10-13 19:06:01 +11:00
sam b1dbe519b0 feat(webui): repositories list is an accordion; adding opens the new one and waits for save 2026-10-13 19:04:14 +11:00
sam 3103f87b71 fix(applystatus): the gateway no longer owes an apply status for channel and plugin settings 2026-10-13 19:00:52 +11:00
sam 8664e8cd97 fix(webui): drop settings hints that restate their label 2026-10-13 18:11:12 +11:00
sam 9e566e7278 fix(webui): shorten route descriptions, setup steps, alerts and panel errors 2026-10-13 18:10:39 +11:00
sam f02a3b6d02 fix(agent): drop the one-question cap from the chat prompt and SOUL 2026-10-13 17:49:35 +11:00
sam bf6f3512b1 feat(agent): default persona and SOUL share a reporting-focused identity prompt 2026-10-13 17:47:46 +11:00
sam 00112ae205 fix(webui): attention vocabulary no longer addresses a single user 2026-10-13 17:42:11 +11:00
sam 8001c893bd fix(webui): cut tutorial and marketing prose from labels, hints, empty states and confirms 2026-10-13 17:37:53 +11:00
sam 0e25291d47 fix(webui): review settings drop the in-force echo and rewrite the approval hint 2026-10-13 17:28:31 +11:00
sam 68fb3a7e19 fix(webui): form fields sit on the card colour so they no longer read as disabled 2026-10-13 17:24:48 +11:00
sam 541575a073 fix(archied): load and report EDA playbooks at start instead of at the first dispatch 2026-10-13 17:22:01 +11:00
sam d4d24cb1db fix(webui): default-alias warning states the action only 2026-10-13 17:17:06 +11:00
sam 20cb2fd99d fix(webui): task page drops filler copy, the unattributed-events note and the New run tooltip 2026-10-13 17:16:25 +11:00
sam 4fd6efb7f0 fix(webui): alerts drop UI-explaining prose and align Dismiss with the title 2026-10-13 17:14:43 +11:00
sam 9eabc624ee fix(config): a task snapshot carries only the model limits its aliases resolve to 2026-10-13 17:07:40 +11:00
sam 01418b7e81 fix(webui): harness terminal-unavailable message says what the operator can do 2026-10-13 17:02:45 +11:00
sam cac763a339 feat(webui): finish redesign dashboard task and secret settings 2026-10-13 16:41:35 +11:00
sam 0dde93e57e fix(taskactions): a failed callee cancel no longer leaves the caller's run going
Issue: archie-core-kig5j
2026-10-13 16:22:40 +11:00
sam 7435b6efe5 fix(eda): the undispatched-capture batch lists only captures an enabled binding still owes
Issue: archie-core-kfjz1
2026-10-13 16:21:21 +11:00
sam 796c7a711b fix(postgres): age retention spares captures still waiting to be dispatched
Issue: archie-core-jrh2m
2026-10-13 16:19:12 +11:00
sam 4ac9fd852f fix(postgres): assign bootstrapped agent identities to the default org on every start
Issue: archie-core-n5yj5
2026-10-13 16:18:19 +11:00
sam 06d6293a9d fix(controlplane): instance settings are written by the system org only
Issue: archie-core-f5zso
2026-10-13 16:17:38 +11:00
sam 0c904fb9ef fix(controlplane): playbook dispatch resolves and caches per the task's org
Issue: archie-core-5t4z7
2026-10-13 16:16:31 +11:00
sam 59645969ee fix(e2e): repository policy applies live, so seeding no longer restarts archied
Issue: archie-core-m5aqb
2026-10-13 16:15:07 +11:00
sam acacdfdab5 fix(statestore): an invalid stored policy raises an alert and resolves when it validates
Issue: archie-core-kgxw.16
2026-10-13 16:14:16 +11:00
sam 2090c41960 fix(ops): external NATS needs a token and publishes monitoring on loopback only
Issue: archie-core-ov11
2026-10-13 16:09:23 +11:00
sam e5a67b8ff0 fix(webui): a source create is authorized against the workspace it names
Issue: archie-core-ed8tw
2026-10-13 16:00:37 +11:00
sam 8e6dfd785f fix(webui): channel reload route is authorized as the channel action
Issue: archie-core-4laa1
2026-10-13 15:59:36 +11:00
sam b9547b01a8 fix(staterpc): an org-scoped caller cannot read or write another org's harness secret
Issue: archie-core-jo15w
2026-10-13 15:58:51 +11:00
sam 0720e9629c fix(statestore): a restart never resolves a service alert still inside its grace
Issue: archie-core-07lyl
2026-10-13 15:56:23 +11:00
sam bb67bd77f1 fix(statestore): service-unhealthy grace counts from the last stored report and covers silent services
Issue: archie-core-07lyl
2026-10-13 15:29:29 +11:00
sam 8ecda341e0 fix(servicekit): report apply status only for kinds the process re-applies live
Issue: archie-core-mt91
2026-10-13 15:28:43 +11:00
sam dee78a876a fix(postgres): clamp event, token and denial limits to int32
Issue: archie-core-g14d
2026-10-13 15:27:36 +11:00
sam 33ccfb2505 fix(daemon): run-time workflow check sees the binding event's signature and address
Issue: archie-core-bmro8
2026-10-13 15:10:31 +11:00
sam 0330a65054 fix(postgres): confine identity writes and GetPrincipal to the caller's org
Issue: archie-core-wkey2
2026-10-13 15:07:48 +11:00
sam 4eb9c20c0c fix(workflows): callees of a test run inherit the test source 2026-10-13 12:46:48 +11:00
sam 1f4910a651 feat(workflows): test-run unsaved drafts and browse workflow version history
A test run pins a validated draft, runs with forge and push writes
suppressed and recorded per step, and is excluded from workflow stats.
The History tab lists revisions that changed a workflow, diffs them as
YAML and on the canvas, restores into the editor, and ties runs to the
revision they used.
2026-10-13 12:27:40 +11:00
sam 150bfd4605 fix(postgres): quote the alert lock key so a NUL cannot reach Postgres text 2026-10-13 03:15:06 +11:00
sam 3bf64933b0 fix(ui/topbar): replace Jump to with a command palette, drop filler chrome (#1650)
* fix(ui/topbar): replace Jump to with a command palette, drop filler chrome

Jump to opens a shadcn-vue Command dialog that finds pages, tasks and
workflows by name. The connection indicator shows only when the stream is
lost, the dead documentation link is gone, and the profile menu label has
no stray whitespace.

* fix(ui): trim stray whitespace from template text and drop em dashes from copy

Element text that started or ended with a line break rendered with leading
and trailing spaces. Also removes the unused 'soon' nav state and the nav
group components no route reaches.

* fix(ui): drop the space a hidden spinner left before button text

* fix(ui/status): one dense Status page, full-width settings, problems-only apply status

Status drops its tabs and the duplicate health card; services list only
what is wrong. Settings pages use the full width, the resizable sidebar
handle is gone, and apply status shows only processes that have not
applied a change. PageHeader puts the title and actions on one line.

* refactor(ui): use shadcn ToggleGroup and Badge, drop SegmentedControl and StatusPill

Status badges show only when a state needs attention: no Running, Enabled,
Active, Listening or live pills next to healthy rows. Removes the unused
pagination, radio-group and scroll-area components.

* fix(ui/history): use the shadcn Table with fixed columns so nothing is clipped

* fix(ui/workflows): apply ?workflow= only once the workflow is listed

Selecting it before the definitions loaded opened an empty canvas.

* refactor(ui/workflows): use shadcn Input, NativeSelect, Checkbox and Button in editors

Replaces hand-rolled inputs, selects, the repository mode switch and icon
buttons in the workflow editor, bind dialog, harness page, sources panel
and review gate. Adds the upstream shadcn-vue NativeSelect.

* style(ui): rounded-rectangle controls instead of pills

Halves the radius scale so inputs, selects and buttons stop reading as
pills, and badges and chips lose their full rounding.

* fix(ui/alerts): centre the bell's failed state and stop it contradicting Needs you

* fix(ui/tasks): one header line, aligned columns, no placeholder issue numbers

Tasks puts its filters beside the title and drops the stat tiles the
dashboard already shows. Sort headers align with their cells, chat tasks
no longer show their synthetic issue number, and Logs and the task
not-found page use the shared header.

* fix(ui/dashboard): shared header and cards, empty cards stay silent

Needs you uses the shadcn Card and drops its duplicate Open button; quality
gates and token outlook render only when there is something to show; the
throughput strip moves into the dashboard, its only user.

* refactor(ui/stores): one Pinia store per feature

Splits the site-wide control-plane store and the module-level refs into
settings, workflows, tasks, events, org and session stores. Identity
requests move into lib/api. Drops store fields nothing read: per-resource
stream state, the states map and loadApplyStatus.

* fix(ui/org): one header for the org area, sections drop their repeated titles

The org name is the page title with the admin's org switcher and New org
beside it; Members and Workspaces tables sit in cards like other pages.

* fix(ui/events): shadcn Tabs for the capture, map and bind steps

Replaces the numbered step strip with line tabs that carry each step's
count; the Listening pill is gone and Capture off shows only when it is.

* fix(ui/workflows): confirm a workflow delete in an AlertDialog, not window.confirm

* style(ui/settings): denser setting rows
2026-10-12 04:40:21 +11:00
sam 94d2f98cc0 feat(e2e): local stack, seed and browser checks for release validation 2026-10-12 04:28:26 +11:00
sam 2df2f72fc2 fix(ci): guard apparmor userns sysctl in deploy workflow 2026-10-12 04:17:11 +11:00
sam 8a3ba32c5a Feat/operator alerts (#1635)
* feat(state): durable operator alerts owned by the State Store

Alerts dedup on org+kind+subject, resolve themselves when a condition
clears, and are raised, resolved, dismissed and listed through the state
contract. Task transitions raise needs-human and failed alerts in the same
transaction; the store checks service health and prunes closed alerts.
Each raise and resolve queues a webhook delivery whose attempts are kept.

* feat(notify): deliver operator alerts to the webhook; raise config and release alerts

notify.webhook now receives raised and resolved alerts above a severity
threshold with HMAC-signed payloads, bounded retry and every attempt recorded
on the alert. archied raises model alias, provider and credential-binding
alerts from the effective configuration, an update alert from the release
channel, and a credential-rejected alert from the egress resolver. The
dashboard API lists and dismisses the caller's org's alerts.

* feat(ui): alert bell in the top bar and webhook alert settings

The bell lists the org's open alerts by severity with dismiss and a link per
alert, and refreshes from the event stream. The task settings page gains the
webhook severity threshold and signing secret. ui/dist rebuilt.
2026-10-12 03:30:46 +11:00
sam f34f60f9c7 Feat/org epic (#1634)
* fix(postgres): scope OpenPRs to the caller's org

A principal-carrying caller read every org's pr_open tasks. The query now
honours the request scope; the daemon's unscoped review scan still sees all
orgs.

Issue: archie-core-kgxw.23

* fix(statestore): serve task logs only to the task's org

ReadTaskLog and StreamTaskLogContent took a task ID and read the file with
no org check. The State Store's task-log reader now confirms the task is
visible under the caller's scope first; unscoped services read as before.

Issue: archie-core-kgxw.24

* fix(postgres): scope ListPolicies to the caller's org

Every org's policy text reached any principal-carrying caller. A scoped read
now sees its own org's policies, plus instance policies when scoped to the
system org. The engines and the lockout guard decide for every org, so they
read the full chain unscoped: the dashboard engine loads without the
request's principal and the guard lifts the caller's scope.

Issue: archie-core-kgxw.25

* fix(postgres): scope identity reads to the caller's org

ListIdentities and GetIdentity (and its alias fallback) returned every
identity to any caller. A caller scoped to an org now sees only that org's
members and assigned agents; the system org and unscoped services still see
the whole instance.

Issue: archie-core-kgxw.26

* fix(postgres): hide instance status from other orgs

ListPresence, ListChannelStatus, ListApplyStatus and GetConfigSnapshot
answered any org principal with instance-wide state. They now return nothing
unless the request is unscoped or scoped to the system org. The dashboard
reads the published config as itself, since its handlers project it for
callers of every org.

Issue: archie-core-kgxw.27

* feat(postgres): assign new agents an org and role at creation

A bot or service account created through the API served no org until the
next State Store boot granted it one. Create now assigns it to the org the
request acts in with the developer role in the same transaction, so it is
authorized immediately.

Issue: archie-core-kgxw.14

* feat(edastore): create event records in a chosen workspace

Sources are created in a workspace of the caller's org, the default one when
none is named; event types and bindings take their source's workspace and
mappings their event type's, the same rule the org backfill applied. The
binding, mapping and event type contracts carry the workspace, the four list
endpoints accept ?workspace=, and the Events page has a workspace selector
that filters every step and picks where a new source goes.

Issue: archie-core-kgxw.11

* feat(webui): authorize a record in its workspace

The API built every access request with no workspace, so workspace
policies and per-workspace roles never applied. A request naming a source,
binding, mapping, event type or task now reads the record's workspace under
the caller's scope and authorizes in it; tasks carry their workspace on the
State Store contract for this.

Issue: archie-core-kgxw.9

* feat(access): expose workspace environment to policies

Policies can test resource.workspace.environment. The workspace attribute
is the workspace entity, which carries its environment; the principal
brings its org's workspaces from the State Store, so the dashboard and the
daemon's run checks describe a resource's workspace without another lookup,
and the daemon now authorizes runs in the task's or binding's workspace.

Issue: archie-core-kgxw.10

* fix(webui): ask read_secret when a source secret is read

Rotating a source's secret returns its value, but the route asked update,
which every developer holds, so no policy could narrow who reads a secret.
It now asks read_secret on the secret, which the shipped roles give admins
and an object policy can narrow further.

Issue: archie-core-kgxw.17

* refactor(org): delete the unused upgrade-incomplete sentinel

Nothing returns org.ErrUpgradeIncomplete: the State Store finishes the org
upgrade before it serves.

Issue: archie-core-kgxw.18
2026-10-12 03:24:04 +11:00
sam 8540c9f7c8 feat(releaseupdate): transactional self-update through archied (#1633)
archied update install verifies the release zip, checks every binary
reports the release, pulls the agent image by digest, backs up the
database in-process and stages the binaries before handing off to
archied update watchdog in its own process. The watchdog restarts units
in release order, requires archied healthy for 120s and otherwise rolls
back binaries and image policy, restoring the database only when a
migration ran. Boot recovery resumes the frozen watchdog.

Deletes scripts/archie-update-install, scripts/archie-update-watchdog,
the updater's --from-source and --auto, CommandInstaller,
ScriptInstaller and the update-image and update-topology subcommands.
2026-10-12 03:21:02 +11:00
sam 3014db85e7 Fix/workflow eda audit (#1627)
* fix(webui): accept the merge task action

The action whitelist omitted merge, so the dashboard's Merge button on a
pr_open task was refused with 400 unknown action.

Closes: archie-core-slpoz

* fix(workflow): give each parallel branch its own outputs

Branches shared the task's Outputs map, so concurrent declared-output
writes raced (or were lost when the map started nil). Each branch now
writes a copy; join merges new outputs in branch-name order and refuses
one written by two branches as a second write.

Closes: archie-core-3a7w2

* fix(postgres): dispatch captures oldest first and keep pending ones

ListUndispatchedCaptures ordered newest first and listed captures no
binding can match (failed HMAC), so sustained intake starved older work
and bad signatures held the batch. It is now oldest first and lists only
dispatchable captures. Count retention no longer evicts a capture that
is still pending for an armed binding. The daemon lists only sources
with an enabled workflow, so captures waiting on a disabled one do not
hold the oldest-first batch.

Closes: archie-core-2et4b, archie-core-o0s0z

* fix(ui): refuse renaming a workflow onto an existing id

Saving upserts by id, so editing a workflow's id to another workflow's
id removed the open one and overwrote the other. The editor now refuses
that save and says why.

Closes: archie-core-wpoz8

* fix(workflow): reject unknown step settings at save

Step factories decoded settings with yaml.Node.Decode, which drops keys
it does not know, and settings-less steps ignored settings entirely, so a
misspelt key (readOnly for read_only) saved and silently did nothing.
Every factory now decodes strictly and settings-less steps refuse
settings; ParseDefinition runs the factories, so the save refuses them.

Closes: archie-core-8b5nk

* fix(postgres): keep a stored capture when its prune fails

InsertCapture committed the capture, then returned the prune's error, so
intake answered 500 and a sender without a delivery header retried into
a duplicate capture and a duplicate dispatch. A failed prune is now
logged and the stored capture's id returned.

Closes: archie-core-3miuh

* fix(crondelivery): fail and advance a job no runner can deliver

Router.Run returned nil for a kind with no runner, so the engine reported
a successful run while the schedule never advanced and the job fired on
every tick. The run now fails with the refusal, which the engine reports,
and the schedule advances (a one-shot is removed). The router's own
refusal event is gone with it.

Closes: archie-core-s6ahh

* fix(taskactions): stop the runs of cancelled callees

CancelExecution cancelled a caller's waited-on callees in the store, but
only the caller's run was stopped, so callee containers ran to the end.
CancelExecution now returns the callees it cancelled (nested included)
in place of the step ids nobody read, and every cancelling action stops
their runs too.

Closes: archie-core-9labz

* fix(workflow): treat a zero json.Number as false in when

Task inputs and step results decode numbers as json.Number, which truthy
did not unpack, so when: inputs.count held for a count of 0.

Closes: archie-core-uv270

* fix(webui): read a workflow's runs with a workflow-filtered page

The workflows page and the canvas run picker filtered the newest 100
tasks of every workflow client-side, so on a busy instance a workflow's
older runs were invisible. GET /api/tasks takes a workflow filter, carried
through the State Store's Tasks request to the query, and both views ask
for the selected workflow's runs.

Closes: archie-core-tpiw1

* fix(ui): load the restored workflow into the editor

Restore Defaults saved the shipped definition but left the open draft in
the editor, still marked unsaved, so a later save re-applied it. The
editor now reloads the restored definition.

Closes: archie-core-85e7w
2026-10-12 03:20:00 +11:00
sam aea7c5c9f1 build(tools): provision PostgreSQL 18 in the cloud setup for full checks 2026-10-12 03:00:46 +11:00
sam c792c552cf build(tools): link cloud setup tools onto the default PATH 2026-10-12 02:44:11 +11:00
sam a71f1e0817 ci: drop the Postgres client from the deploy gate 2026-10-12 02:19:51 +11:00
sam 76905c8ec6 ci: run every job on the self-hosted runner 2026-10-12 02:10:14 +11:00
sam 85d8b771f0 Merge pull request #1602 from samcharles93/feat/workflow-runs-as
Feat/workflow runs as
2026-10-12 02:08:30 +11:00
sam d31a950daa feat(workflow): shipped workflows run as the instance root 2026-10-12 01:53:55 +11:00
sam f765e23812 feat(daemon): run each workflow as its declared identity
Every attempt checks that the identity that started the task and the
identity the workflow declares may both run it, recording a denial for
either. A workflow that declares no identity is refused rather than
running as its starter or the root. A workflow.call callee is started by
its caller's declared identity instead of inheriting the caller's row.
The workflow settings panel marks the identity as required and offers
the agent identities.
2026-10-11 14:49:38 +00:00
sam d66dca44e0 Merge pull request #1601 from samcharles93/fix/atomic-dispatch
Fix/atomic dispatch
2026-10-12 01:29:16 +11:00
sam b8f8f9a272 fix(postgres): allocate synthetic issue numbers from a per-repo counter
InsertChatTask and EnqueueCallTask computed MAX(issue_number)+1, so
concurrent inserts in one repository took the same number and the second
failed on the unique key. Both now bump a chat_issue_numbers row, seeded
from the existing maxima, whose row lock serializes allocation.
2026-10-11 14:21:27 +00:00
sam e128f82e11 build(ui): install dashboard deps from the lockfile without rewriting it 2026-10-12 01:21:16 +11:00
sam daab5732e8 fix(daemon): claim binding dispatch and enqueue its task atomically
EnqueueBindingTask now takes the capture and claims the ledger row,
inserts the task, stamps its provenance and links the ledger row in one
State Store transaction. A failure anywhere leaves the delivery
undispatched for the next cycle; a replay or concurrent claim is refused
by the ledger's unique index. SetDispatchTask is removed.
2026-10-11 14:19:43 +00:00
sam eb5703b7dd ci: drop the Postgres client the removed tests needed 2026-10-12 01:17:11 +11:00
sam ce5fc3e226 test(postgres): remove database-backed tests and the testcontainers harness 2026-10-12 01:17:02 +11:00
sam c2a649ded4 docs(agents): forbid database-backed tests 2026-10-12 01:15:19 +11:00
sam 1b0a89ca2e fix(tools): keep bd hook setup out of the checkout 2026-10-12 01:14:38 +11:00
sam 1441585e06 chore: reindent beads config and add agent profile 2026-10-12 01:01:19 +11:00
sam f3576342b6 chore(tools): rely on preinstalled gh in cloud setup 2026-10-12 00:46:51 +11:00
sam ede2102c60 chore(tools): install gh in cloud setup 2026-10-12 00:43:37 +11:00
sam 16d98dd47c chore(tools): install bd via upstream installer and disable attribution in cloud setup 2026-10-12 00:41:07 +11:00
sam 7aca31b18f chore(tools): add Claude cloud environment setup script 2026-10-12 00:12:18 +11:00
sam e97f1fa609 fix(ci): limit gate concurrency to runner memory 2026-10-11 22:28:11 +11:00
sam 62f0baba36 fix(ci): use repository-scoped quality runner 2026-10-11 22:10:52 +11:00
sam 40fa6f9d7d fix(ci): check namespace support before installing tools 2026-10-11 21:33:56 +11:00
sam 6ce605d6ea fix(ci): allow extension namespaces in quality container 2026-10-11 21:30:43 +11:00
sam feba855326 style(ui): tidy org page layouts and empty states
Members and Workspaces get fixed column widths and their add forms move
into labelled sections. Agents lists agents first and moves credential
grants below. Access puts New policy in the card header. Tokens states
when none exist.
2026-10-11 15:59:30 +11:00
sam 47f75f71a7 docs: remove incorrect notice 2026-10-11 12:17:31 +11:00
sam 4e060ce5ef fix(ui): stage history restore as a draft applied from the save bar 2026-10-11 11:35:02 +11:00
sam e2e24f9d56 ci(deploy): pull the container image the uncached test suite needs 2026-10-11 04:26:08 +11:00
sam 5aa5c2a6c8 chore(release): v1.53.0 2026-10-11 04:23:10 +11:00
sam 41b2daed0c Merge branch 'work/53jc' 2026-10-11 04:11:43 +11:00
sam e0a79b3990 Merge branch 'work/ry4k' 2026-10-11 04:11:43 +11:00
sam e2d6b75b10 fix(prreview): restore the benchmark runner on configured models and public PRs 2026-10-11 04:11:40 +11:00
sam b4be999777 fix(gateway): remove the web /restart command that no process could serve 2026-10-11 04:11:37 +11:00
sam 5c3bf0b642 feat(storepkg): auto-update policy, applied by a State Store ticker 2026-10-11 04:10:53 +11:00
sam be2b897149 refactor(servicediscovery): delete unreachable contract and NATS implementation 2026-10-11 04:09:56 +11:00
sam f5a39cfb9b fix(daemon): bound a package workflow's triggers by its accepted authority 2026-10-11 04:08:02 +11:00
sam f5a6fa5b32 fix(postgres): number the outcome-posted migration after package updates 2026-10-11 04:04:45 +11:00
sam 93ec6d916b Merge branch 'work/mt9xo' 2026-10-11 04:03:52 +11:00
sam c36fb29683 Merge branch 'work/zcg8' 2026-10-11 04:03:52 +11:00
sam cac0f43b58 Merge branch 'work/mqti13'
# Conflicts:
#	internal/contracts/state/v1/state.pb.go
2026-10-11 04:03:52 +11:00
sam 805364f201 feat(archied): post a chat task's outcome back to its chat 2026-10-11 04:03:30 +11:00
sam 3b2a3a7630 fix(webui): the setup checklist and skill catalogue are system-org only 2026-10-11 04:01:46 +11:00
sam bf29d3640e fix(daemon): reown worktrees a killed container left root-owned 2026-10-11 04:01:19 +11:00
sam de15bffc2f fix(telegram): publish /approve, which the router already serves 2026-10-11 03:57:10 +11:00
sam 1377e7ebf2 feat(webui): add a member by provider subject or email
POST /api/orgs/{id}/members binds a person by subject, or by email as a
placeholder. The first sign-in whose provider vouches for that email
claims it: the State Store moves the binding onto the provider's subject
in one statement, so a second account with the same address finds
nothing to claim and later sign-ins rest on the subject alone.
2026-10-11 03:54:49 +11:00
sam d53ebbda95 fix(daemon): last poll reports the least recently polled loop 2026-10-11 03:53:11 +11:00
sam b227df3c3f feat(storepkg): widening updates wait for approval, rollback restores the previous pin 2026-10-11 03:48:31 +11:00
sam a3e0e5c1bb fix(daemon): bound a package workflow's tools by its accepted authority 2026-10-11 03:48:31 +11:00
sam 116f8a10fb style(webui): rewrap the assets comment 2026-10-11 03:48:17 +11:00
sam 116b03534f fix(staterpc): a task's own credential cannot replace its workflow pin
The pinned definition carries the package a run's authority is read
from. A task-scoped Update now reaches the store without a definition,
and UpdateTask keeps the stored pin when none is sent; the workflow name
still moves for handoffs and the daemon re-pins it.
2026-10-11 03:47:17 +11:00
sam b697a12b89 fix(webui): an unserved /api path is a 404, not the dashboard page 2026-10-11 03:46:40 +11:00
sam 7b64699ff1 refactor(workflow): delete routing overrides nothing applied 2026-10-11 03:43:25 +11:00
sam 1598b3cc74 docs(agents): extend the finish-and-shrink rule to 2026-10-20 2026-10-11 03:39:31 +11:00
sam 212742e880 feat(forgerpc): bound a package workflow's forge calls by its accepted authority 2026-10-11 03:37:16 +11:00
sam 6693e60f6f fix(access): an unloaded chain is a refusing engine, not nil
Webhook intake answers 503 and counts no refusal while the chain loads.
The readiness probe reads the chain on every check. The UI never exits on
a first-load failure. An invalid instance policy closes the instance but
lets an instance admin repair policies. Outage pages are 503, and the
health detail names the unloaded chain.
2026-10-10 22:19:02 +11:00
sam c097e50405 fix(archieui): warn when the dashboard is reachable off-host over plain HTTP
The dashboard serves plain HTTP, so a non-loopback bind carries the
session cookie and provider token in clear unless TLS terminates in front.
Warn at startup unless the operator declares a proxy with
[web].trust_forwarded_headers, and record the choice in deployments/README
where the dashboard is deployed. Point the non-loopback token error at
that surviving doc, not the deleted UI-boundary PRD.
2026-10-10 22:09:05 +11:00
sam ccbc9c7844 fix(webui): the wildcard listen address is not loopback
IsLoopback(":8484") returned true: the empty host fell through the
switch as loopback, so a wildcard bind skipped the non-loopback token
requirement and served every interface unauthenticated. An empty host is
the wildcard, not loopback.
2026-10-10 22:09:05 +11:00
sam 948a8d34fd test(worktree): give each transport its own branch
The four subtests share one bare repo but pushed the same feat/1-test
branch. Their commits have the same tree, message, author and parent, so
two commits in the same second hash identically and the second push is a
no-op -- passing by luck -- while a second of clock drift makes it a
non-fast-forward failure. One issue per subtest gives each its own branch.
2026-10-10 22:05:22 +11:00
sam e078b5c4bc fix(webui): refuse API requests until the access chain loads
A State Store that was unreachable at startup left the access chain nil,
and authorize treated nil as no chain at all: every request passed the
credential check, no principal or org reached the context, the State Store
defaulted each call to org-sys, and the instance-only surfaces were served.
The dashboard stayed open until a restart.

Build a chain with no engine when the first load is Unavailable; it refuses
every request with 503 (or the notice page for a browser) until the first
load succeeds, and Run keeps retrying so the dashboard recovers without a
restart. A denial is not recorded, because nothing was evaluated.
2026-10-10 21:55:02 +11:00
sam 4a24c0b31f fix(memory): each org's agent memory is its own 2026-10-10 21:20:37 +11:00
sam e988d3cc40 fix: close cross-org writes and move existing rows into their owner's org 2026-10-10 20:31:54 +11:00
sam cd20aeadad fix(webui): instance health, logs, config and identities are system-org only 2026-10-10 20:20:07 +11:00
sam 1bb7ba1248 fix(postgres): tasks, events, steps and run stats stay in their org 2026-10-10 20:18:29 +11:00
sam fdafec3d9d fix(postgres): event sources, types, mappings and bindings stay in their org 2026-10-10 20:14:23 +11:00
sam 0fcf792db3 feat(gateway): chat sessions belong to one org
Sessions carry an org; listing, reading and writing a session, its
messages and its turns are limited to the caller's org. Another org's
session reads as not found and cannot be overwritten or appended to.
Sessions from before orgs belong to the system org.
2026-10-10 18:57:26 +11:00
sam 9cd52dd9aa feat(archiegateway): chat resolves models in the caller's org and bills it
The State Store answers the calling principal's org aliases
(CallerModels) and bills chat usage to that org; usage records no longer
carry a caller-named org. Chat lists and resolves aliases for the
caller's org and fails rather than substitute one it may not use.
2026-10-10 18:53:57 +11:00
sam 5290dab199 feat(controlplane): per-org model access, org aliases and org providers
The system org sets each org's allowed models and whether it may add its
own providers (org-model-policy); an org with no entry may use nothing.
An org's aliases and providers are checked against that policy on save
and filtered by it at resolution. Tasks get their org's providers, keyed
by the org's credential binding through the egress proxy. Org Settings
gains a Models tab; instance Models gains Org access.
2026-10-10 18:48:40 +11:00
sam e17c7895e4 feat(daemon): resolve a task's models and credentials in the task's own org
The State Store answers a task's effective model aliases (instance aliases
with the task org's own over them), deriving the org from the task. Model
egress and the run credential resolver use the task's stored org instead
of the identity mapping in config.
2026-10-10 18:40:53 +11:00
sam e4ea2eaabc feat(statestore): record a usage row for every model call
Task agent runs and MCP sampling record against their task (billed to the
task's org); gateway chat turns, titles, sampling and curators record
against the system org. Rows carry source, workflow, step, alias,
provider/model and tokens for later chargeback.
2026-10-10 18:32:43 +11:00
sam 12b9a57404 feat(config): model aliases replace model roles, resolved by one resolver
Agent steps, implement, pr-review, MCP sampling, chat, embedding and
transcription resolve a model alias (empty means the purpose's default)
and fail on an unknown alias instead of falling back. The step editor and
chat pick aliases; workflow definitions naming an unknown alias are
refused on save.
2026-10-10 17:29:52 +11:00
sam 514c6cf61c fix(daemon): keep model provider keys out of agent containers via the egress proxy 2026-10-10 17:12:09 +11:00
sam bef0ecea3a feat(ui): workflow list shows running count and latest run result 2026-10-10 11:50:27 +11:00
sam 5bb5d9b660 feat(ui): quieter workflows page: hover data edges, apply chip, restore behind confirm 2026-10-10 11:49:32 +11:00
sam f30405ea2b fix(ui): input group addon no longer steals clicks from its select 2026-10-10 11:26:42 +11:00
sam f9efae8a5e fix(archiegateway): keep the chat model list non-nil when empty 2026-10-10 11:17:37 +11:00
sam 819cfc655b refactor: slices.Sorted over map keys and one shared IsNil check 2026-10-10 11:14:36 +11:00
sam 5afe5bcf99 refactor: use slices.Index/Delete and slices.Clone for small copies 2026-10-10 11:14:36 +11:00
sam 0c25b2f4a6 refactor(workflow): decodeSettings returns a typed value 2026-10-10 11:14:36 +11:00
sam 252895e01c refactor(staterpc): use mapValues for proto list conversions 2026-10-10 11:05:59 +11:00
sam 3ea49c7e07 refactor(gateway): drop duplicate string arg helpers 2026-10-10 11:05:59 +11:00
sam 66a27bd7ef refactor(controlplane): make layerResource decode into a typed value 2026-10-10 11:05:59 +11:00
sam b070ce4715 refactor(eda): use slices.Sorted over maps.Keys for ordered keys 2026-10-10 11:05:58 +11:00
sam 84b581fde6 refactor(webui): decode JSON request bodies with generic decodeBody 2026-10-10 11:05:58 +11:00
sam af5e11a734 refactor(domain): share one generic lifecycle registry for curators and memory engines 2026-10-10 11:05:58 +11:00
sam 522ced45ff feat(ui): lanes for parallel and switch steps on the workflow canvas 2026-10-10 10:52:52 +11:00
sam 79d7f2fa68 feat(workflow): switch step runs the case matching a reference 2026-10-10 10:52:52 +11:00
sam eb3ee14a0e feat(ui): step roles, numbers and run trace on workflow canvas 2026-10-10 10:37:47 +11:00
sam 6ed6b28d02 build(ui): refresh dashboard bundle 2026-10-09 20:06:01 +11:00
sam 2f4e9bbe14 Merge branch 'main' into codex/control-plane-4q28 2026-10-09 20:03:52 +11:00
sam 3057f054b2 style: remove space between icons and labels 2026-10-09 19:56:27 +11:00
sam a4e7ea8cc3 fix(kit): migrate runtime to sandbox kit m8 2026-10-09 18:31:56 +11:00
sam c812192800 feat(ui): author parallel workflow branches on canvas 2026-10-09 18:18:45 +11:00
sam 81121d03b0 docs(agents): omit status the maintainer can already see 2026-10-09 18:16:45 +11:00
sam e5f03587c9 docs(agents): post externally only when told 2026-10-09 18:09:11 +11:00
sam c25e70a588 docs(agents): act on clear direction and keep replies short 2026-10-09 18:04:38 +11:00
sam b97c79aa0b feat(ui): edit workflow call interfaces on the canvas 2026-10-09 18:04:08 +11:00
sam 2d2c39f9e5 fix(daemon): reconcile call waits from durable steps 2026-10-09 17:56:15 +11:00
sam 673a5bc2ce chore(release): v1.52.0 2026-10-09 13:09:59 +11:00
sam df5ee243b1 feat(harness): create the setup PTY at the browser's size
The setup terminal created its PTY at a fixed 24x80 while the browser
measured its own box and threw the measurement away, so a full-screen CLI
login drew into a corner of a much larger xterm.

OpenRequest now carries a ConsoleSize with the target frame; the route
reads cols/rows from the WebSocket URL, falling back to 24x80 when they
are absent or out of range, and the daemon creates the PTY at that
geometry. The component sends the size it measured before connecting.

Live resize is the follow-on: it needs a control channel on the WebSocket,
which today is a raw byte copy.
2026-10-09 13:07:29 +11:00
sam 71fa670512 fix(harness): keep the setup container alive with archie's own binary
A setup session started its container with "sleep infinity" and opened the
PTY with "sh -l". Neither binary is guaranteed: the spec capability whose
floor is a shell and bash is com.docker.sandbox/sbx@1, and archie's
supported map does not list it, so a Kit image need not provide either. A
missing sleep killed the container at start and a missing sh failed the
exec, both as an opaque error.

The container now runs archie-agent hold as its entrypoint. The agent
binary is archie's own and already mounted into every Kit, so the
keepalive needs nothing the image may lack and the container env stays
empty. Before opening the PTY, harnesssession probes for bash then sh and
returns ErrNoShell naming the Kit reference when neither is present.

Test: TestPickShell covers bash-preferred, sh-only, neither, and a probe
that cannot run.
2026-10-09 13:05:05 +11:00
sam d91ab1ab0f fix(channels): normalize stored settings and deduplicate save errors 2026-10-09 13:02:23 +11:00
sam 1eb05f0d24 test(ui): prune brittle checks and document agent rules 2026-10-09 12:51:57 +11:00
sam a49e939609 fix(ui): clean dependencies and add task table sorting 2026-10-09 12:46:05 +11:00
sam e76e2fd317 chore(lint): pin the linter to 2.14.0
The setup task is the only installer, so the pin follows the version in
use rather than holding it back, and CI follows the pin.
2026-10-09 12:32:05 +11:00
sam 2418a81a9e fix(egress): use context-aware dial and request in the token-endpoint test
net.Dial and httptest.NewRequest fail the noctx linter, so the gate was red
on the commit that added the test.
2026-10-09 12:27:45 +11:00
sam c4a441d1c3 chore(task): install the pinned tooling with task setup
task setup installs the golangci-lint CI pins, the protobuf generators and
the dashboard dependencies, and warns by name about the tools it cannot
install (Go, Task, Node, Docker).

The linter version now lives in one file read by both the setup task and
both workflows, so a local checkout and the gate cannot run different
linters.
2026-10-09 12:27:45 +11:00
sam c5c145f325 test(archieui): restore the archie-ui import-boundary check
Only the daemon owns containers, and the dashboard consumes a harness
session over its gRPC contract. Go imports are atomic, so a single
reference relinks a runtime, and the boundary holds only while something
re-measures it. cmd/archie-ui/architecture_test.go enforced this until it
was purged with the test suite; nothing enforced it since.

The restored check runs go list -deps . and fails if the dashboard links
internal/container, internal/app/archied or internal/agentexec. It is
transitive, which is what "links" means, and runs in the existing test
step.
2026-10-09 11:42:39 +11:00
sam 3683ce9082 fix(egress): refuse a token endpoint the run is not granted
forward intercepted a declared OAuth credential's token endpoint only when
the run was granted the service. For an optional credential it fell
through to the reverse proxy, so the provider's real access and refresh
tokens reached the container un-sentinelized, contradicting the harness
contract's "the real credential never enters the container".

A matched token endpoint is now refused when the service is not granted
(403 for an optional credential; a required one keeps its existing 502).
The table test drives forward against a recording upstream and asserts
both the status and that the upstream was never contacted.
2026-10-09 11:42:39 +11:00
sam 80dc6ec8d0 fix(deps): pin sandbox-kit-spec to the API the code is written against
The dependency bump moved sandbox-kit-spec from v3.0.0-m.6 to m.8 without
adapting the code, so the tree no longer builds: CredentialCapability.Phase
is now spec.Phases, not a string (internal/infrastructure/egress), and
Client.Assemble became a package-level fetch.Assemble that takes a Loader
and a LayerValidator instead of spec.MergeOptions (internal/infrastructure/
kitrun).

Migrating to m.8 is not a version-string change: m.8 pushes kit integrity,
safe layer extraction and resource limits onto the caller, so it is
security-relevant work, not an unblock. Pin back to m.6, which the code is
written against, and leave the migration to a deliberate change.

Verified: go build ./..., go vet ./..., go test -short ./... all pass with
this pin. The gate's ui:check and lint steps fail for unrelated
toolchain reasons recorded separately.
2026-10-09 11:42:33 +11:00
sam 12d6585586 ```
chore: update ui dependencies
```
2026-10-09 11:27:48 +11:00
sam 53916b0f96 chore: bump Go dependencies and toolchain 2026-10-09 11:23:04 +11:00
sam badbbf84bd fix(config): normalize default org for harness credentials 2026-10-09 10:01:35 +11:00
sam d98352d003 feat(settings): classify startup and live runtime settings 2026-10-09 09:57:57 +11:00
sam 542bd88040 feat(logging): aggregate recent service logs in dashboard 2026-10-09 09:57:57 +11:00
sam 81384939a2 fix(gateway): attribute chat settings to signed-in users 2026-10-09 09:57:57 +11:00
sam c8ed5619c6 fix(webui): explain personal token availability 2026-10-09 09:57:57 +11:00
sam 3b79155602 refactor(webui): remove unused configuration schema 2026-10-09 09:57:57 +11:00
sam 552ee93a47 fix(settings): show configuration reload failures 2026-10-09 09:57:57 +11:00
sam 7bf429b599 fix(gateway): read task logs through state store 2026-10-09 09:57:57 +11:00
sam 0792f0ba84 fix(ui): render unknown routes and correct status description 2026-10-09 09:57:56 +11:00
sam 02ab747ca9 fix(configuration): reject unknown conf.d files 2026-10-09 09:57:56 +11:00
sam c53a98ee87 feat(curators): edit and apply definitions live 2026-10-09 09:57:56 +11:00
sam 1e4aa8badc feat(settings): edit profiles bindings and playbooks 2026-10-09 09:57:56 +11:00
sam 1e76c99b48 feat(settings): show resource consumers and apply status 2026-10-09 09:57:56 +11:00
sam ff9b6c7196 feat(presence): report workers and broker on status 2026-10-09 09:57:56 +11:00
sam 7680dc5079 feat(presence): expose service dependency checks 2026-10-09 09:57:56 +11:00
sam d0370ed9f7 fix(daemon): inherit live settings for identity tasks 2026-10-09 09:57:56 +11:00
sam 7e3b3dbd78 test: verify enablement reports channel running 2026-10-09 02:24:47 +11:00
sam 6b71dc8108 fix(workflow): enforce optional result booleans only when required 2026-10-09 02:22:19 +11:00
sam 307f2fc9e2 fix(messaging): refuse failed channels as enablement success 2026-10-09 02:22:19 +11:00
sam 455de3d799 fix(workflow): retry a transient read while awaiting a callee 2026-10-09 02:21:49 +11:00
sam 4e74ed37b4 fix(workflow): preserve a reference's type between steps 2026-10-09 02:10:43 +11:00
sam 7ef58293be feat(harness): serve a daemon-side setup session to the dashboard
The dashboard's setup terminal was a 503: it had a WebSocket route, an
authorizer and an xterm.js surface, but nothing owned a container. The
daemon owns containers, so the session contract lands there and the
dashboard consumes it over a new gRPC contract.

One session concept, two targets. A setup session is addressed by Kit
profile and is ephemeral; a run session (archie-core-qi91) is addressed by
task and attempt and is bounded by the task. This slice serves setup and
answers Unimplemented for run.

The contract, the authorisation, the lifetime and the egress phase are
settled in docs/prds/external-agent-harness.md, "Session contract". The
short version: the daemon serves harness.v1.HarnessService; the dashboard
authorizes the operator as an update on the secret and then dials the
daemon with the harness service token, required even on loopback because a
session is a shell holding an org's credential; the setup container runs
no worker, mounts no worktree, holds a keepalive, and carries an empty
container environment. Install hooks run at the install phase and the
session enters runtime before the shell, so a runtime-phase credential's
token endpoint is the one the proxy intercepts.

Capture is gated by the egress proxy on a granted service, and a setup
session has no task, so the daemon registers a session grant: the
session's proxy token resolves to the org's bindings for the Kit's
declared services. The real token never enters the container: the token
endpoint response is sentinelized and stored as the org's harness secret.

Every teardown path releases the pool slot, revokes the egress session and
the grant, removes the sandbox network, and removes the session's volumes.
The listener requires HARNESS_TOKEN and stops with a 10s grace before
Stop, so an open session cannot hold shutdown to the watchdog leash.
2026-10-09 01:38:41 +11:00
sam 27c9647a13 fix(container): reap orphaned processes in Kit containers 2026-10-09 01:37:57 +11:00
sam 89541eb3b0 chore(lint): drop nolint directives that suppress nothing
29 of 59 directives did nothing. Removing each one individually and
re-running the gate revealed no issue from any of them: 20 named gosec,
which is not enabled in .golangci.yml and never has been, plus 4 nilerr
in functions that return no error, 2 dupl where dupl reports nothing
repo-wide, and one each of contextcheck, nestif and unused. The funlen
name on settings.go:147 is gone for the same reason; its gocyclo and
cyclop names are both live.

The unused directive in webui/authorize.go sat on `var _ = slog.Default`,
a statement that only existed to keep the log/slog import alive. Both go.

The 30 remaining directives all suppress a real issue.
2026-10-08 23:29:19 +11:00
sam 3a3a714cc4 fix(modelcatalog): never serve a disabled provider from the ambient key
disableProvider already cleared a failed provider's credential, but that
made it indistinguishable from a provider nobody configured, so
usableProvider fell back to the catalog's ambient env var (e.g.
OPENAI_API_KEY) and sent turns with a key the operator did not choose.
Mark the provider Disabled when its key fails to resolve, refuse it in
usableProvider, and carry the flag through mergeProviders so a catalog
refresh cannot resurrect it.
2026-10-08 22:59:23 +11:00
sam b107e4452a fix(webui): keep the dashboard token out of the startup log
DashboardURL no longer takes a token, so the startup line cannot embed
?t=<token> in the printed URL. The log now names the token file instead.
2026-10-08 22:57:28 +11:00
sam 2b514cb526 feat(scheduling): refuse a job payload that names a dangerous command
A scheduled job runs unattended, so a payload that restarts the daemon,
formats a disk or powers the machine down is refused when the job is
created rather than when it fires. scheduling.RefuseDangerousJob is the
one rule every creation path reaches: the dashboard, any control-plane
client and the config seed all replace the schedules document through the
same validator, so a new token is added in one place.
2026-10-08 22:45:28 +11:00
sam 630c30de79 fix(archiemessaging): apply channel enablement live 2026-10-08 22:44:15 +11:00
sam a69b3455d3 refactor(tools): back generate_video with ai-sdk's minimax video provider
Delete the hand-rolled MiniMax HTTP/poll client; ai-sdk v0.1.43 already
ships provider/minimax implementing video.Provider with the same endpoints,
defaults and poll semantics. The tool now takes a video.Provider and the
composition root builds it, matching the transcription and embedding
capabilities.
2026-10-08 22:42:49 +11:00
sam ddf8383784 fix(archiemessaging): recover a channel that fails on its own 2026-10-08 22:36:09 +11:00
sam c1bbeba18f fix(archied): wait for in-flight tasks on a single-cycle run
A drain pass no longer waits for the tasks it submitted, so -once (the
systemd timer and test invocation) returned while their containers were
still running and the process then tore them down. Wait for the pass's
tasks here, restoring what the flag means.
2026-10-08 22:31:07 +11:00
sam 1f99fb592e fix(daemon): let a run waiting on a callee release its capacity
A wait:true workflow.call run held its global slot and its repo's place for
the callee's whole life, and the drain pass waited for its own tasks, so a
callee queued by that pass was never claimed. With containers.max_concurrency
saturated, or a repo that does not allow concurrency, the wait could not end.

A drain pass now returns once the stream and the claim fallback are empty, and
shutdown waits for in-flight work once. Suspend/Resume give a run's slot and
repo place back while it waits on a callee, driven by the workflow call events
on the daemon's bus; a hold records one slot and one place, so a second
re-acquire gives back what it took.
2026-10-08 22:31:07 +11:00
sam aae01431b4 refactor(workflow): keep the call key change inside the lint gate
golangci-lint failed on the change and had not before: gofumpt wants
StartCall's same-typed parameters grouped, and runWorkflowCall reached a
cyclomatic complexity of 16. The unwaited call's early close moves into
closeUnwaitedCall on *TaskContext -- it needs only the call step, the
callee and the settings -- which leaves runWorkflowCall below the limit
with its behaviour unchanged.

The walk's id-less call case is deleted: ParseDefinition now refuses that
definition before validateWorkflowCalls runs, so it passed for the wrong
reason. The refusal is pinned where it happens instead, by the compile
case in TestWorkflowCallKeyIsTheDeclaredPath, now asserting the whole
message so it still names the step it refused.
2026-10-08 22:31:07 +11:00
sam 3c99f69fee fix(workflow): key a call on its callee, and free a terminal child's key
A call's key was the step's declared path alone, so one task running a
second definition at a colliding path -- workflow.handoff, human.approve
and a definition re-pin all change it -- was handed the first callee's
child, waited on the wrong workflow and published its outputs. The key
now carries the callee too, while the step row and the call's events stay
named and staged for the call site, so a rail pairing an event with its
step still attaches them.

A child that reached dead or closed_wont_do can never do the work and
holds no result the caller can use, so it leaves the call key's index and
frees the key for the caller's retry to start a fresh child. parked and
rejected keep theirs: a parked child is recoverable by retrying it, and a
rejected child ran.

The id a call step must declare is now refused where the definition is
compiled, which is also the path a pinned definition takes, so an id that
spells a step type is accepted again and no stage needs a heuristic.
2026-10-08 22:31:07 +11:00
sam b7fd13923a fix(workflow): key a workflow.call on its declared step path
A call site had no durable identity, so any retry of it -- a lost
EnqueueCallTask reply, a failed call-step record, a requeued attempt that
re-runs the stage -- started a second child and its work happened twice.

The call step's declared path within the run is that identity: wrapStep
sets it (branch-qualified, restored on return), a workflow.call step must
declare an id so two call sites cannot share one, and the key crosses
EnqueueCallTaskRequest.call_key into tasks.call_key, which EnqueueCallTask
upserts on so the retry returns the child already started.
2026-10-08 22:31:07 +11:00
sam 0a47a95cc3 fix(agentexec): enforce capture tool result schemas 2026-10-08 22:30:12 +11:00
sam ef8d9af469 fix(workflow): apply step retry and on_failure to command.run 2026-10-08 22:22:13 +11:00
sam 549f36a1f2 fix(ui): stop the command palette scrolling sideways 2026-10-08 21:58:22 +11:00
sam 187e6e81ee fix(ui): anchor the command palette and stop scroll stealing its highlight 2026-10-08 21:57:20 +11:00
sam e60ad551f0 fix(webhook): authorize delivery against the source's org 2026-10-08 21:43:28 +11:00
sam a0617ad437 test(postgres): derive the org fixture source from its insert 2026-10-08 21:40:24 +11:00
sam 411736fdaa fix(captures): keep count-retention inside the inserted capture's org 2026-10-08 21:27:54 +11:00
sam bea6567933 fix(captures): scope the capture list to the acting org 2026-10-08 21:26:07 +11:00
sam d6b693a9b2 fix(sources): store the acting org on source creation 2026-10-08 21:25:49 +11:00
sam b8bedf4d7b fix(capture): inherit source org on ingestion 2026-10-08 21:02:21 +11:00
sam 5c53dfb91b fix(workflow): resolve definitions in the owning org 2026-10-08 20:41:08 +11:00
sam e0cbbc0895 chore(release): v1.51.1 2026-10-08 01:42:29 +11:00
sam 40dd546564 fix(release): a dependency bump is releasable for every binary 2026-10-08 01:42:27 +11:00
sam b89d8cbab2 fix(deps): ai-sdk v0.1.43 sends gpt-6 tool calls through the Responses API 2026-10-08 01:41:44 +11:00
sam 4b62912343 chore(release): v1.51.0 2026-10-08 01:37:28 +11:00
sam 8a8c8cf7e9 feat(chat): the dashboard chat records voice, downloads files a turn sends, and offers /model and /personality choices 2026-10-08 01:37:21 +11:00
sam 201529414b fix(gateway): providers resolve again when a secret engine starts after boot 2026-10-08 01:34:55 +11:00
sam 3da1f918a4 chore(release): v1.50.1 2026-10-08 00:40:03 +11:00
sam f8d8e5b1e2 fix(update): the watchdog logs the health report it rolled back on 2026-10-08 00:39:57 +11:00
sam 826d4849df chore(release): v1.50.0 2026-10-08 00:25:35 +11:00
sam 0a18bfe21b feat(chat): the dashboard chat answers tool approvals and questions, and /update offers Install 2026-10-08 00:25:23 +11:00
sam 5976b94fbc fix(gatewayrpc): carry tool approvals and ask_user questions between a channel and the gateway turn 2026-10-08 00:22:37 +11:00
sam 698548d6ef chore(release): v1.49.4 2026-10-07 23:58:52 +11:00
sam d0584279e5 fix(ui): tabbed Status and Extensions, one Add MCP server, repos page renders without repos, save bar rests at the viewport edge 2026-10-07 23:46:34 +11:00
sam 62f248fd2c fix(ui): the Versions table's status column ends at the card's edge 2026-10-07 23:35:12 +11:00
sam 8f2750a266 chore(release): v1.49.3 2026-10-07 23:34:21 +11:00
sam 2ea7f7cd38 fix(ui): the release channel control sits at the Updates card's edge, not mid-row 2026-10-07 23:34:13 +11:00
sam 75b3810856 fix(archieui): the Versions card compares against the running daemon, so an available update can be installed 2026-10-07 23:29:03 +11:00
sam 30419532ba chore(release): v1.49.2 2026-10-07 23:18:11 +11:00
sam fff67838e0 fix(releaseupdate): read GitHub releases directly; drop go-selfupdate and its openpgp dependency 2026-10-07 23:18:03 +11:00
sam 15ebe24927 chore(release): v1.49.1 2026-10-07 23:10:38 +11:00
sam b2c1629925 fix(ui): an expired session reloads to the sign-in page instead of showing a banner 2026-10-07 23:05:52 +11:00
sam 0e8fcf70a0 chore(release): v1.49.0 2026-10-07 22:17:00 +11:00
sam 4673b435b7 fix(extension): confine egress only for packages that declare egress hosts 2026-10-07 22:15:06 +11:00
sam 1e062fd7f0 fix(releaseupdate): reuse a found release for ten minutes to stay under GitHub's unauthenticated rate limit 2026-10-07 01:17:21 +11:00
sam 74a3ec925c feat(releaseupdate): archied update check finds releases through go-selfupdate; archie-update-check is deleted 2026-10-07 01:12:11 +11:00
sam 4944ec8473 chore(release): v1.48.1 2026-10-07 01:00:30 +11:00
sam 204b65a0e3 fix(controlplane): update-settings selects a release channel; services run only the installed update scripts 2026-10-07 01:00:28 +11:00
sam cbedb8a504 chore(release): v1.48.0 2026-10-07 00:57:07 +11:00
sam a8dbab0cff feat(controlplane): update commands are an update-settings kind edited on Status, defaulting to the installed scripts 2026-10-07 00:57:01 +11:00
sam 789ff73fe9 fix(scripts): archie-update-install loads the archie env file so a shell run can back up the bundled database 2026-10-07 00:53:23 +11:00
sam 5176938e95 ci(deploy): build the archied and agent images in parallel so the release zip waits only on the agent image 2026-10-07 00:35:13 +11:00
sam 69a1ee677d chore(release): v1.47.3 2026-10-07 00:33:23 +11:00
sam b3cf2c59a8 fix(webui): extension Accept and Remove dialogs act on the selected extension 2026-10-07 00:32:44 +11:00
sam 8ebaeb6d38 chore(release): v1.47.2 2026-10-06 03:25:44 +11:00
sam ce58768e6b fix(webui): show real source endpoints and New source on the Inspector tab instead of a placeholder 2026-10-06 03:25:12 +11:00
sam d49918ae76 chore(release): v1.47.1 2026-10-06 03:05:39 +11:00
sam 8cb5391035 docs(news): regenerate for the corrected 1.47.0 notes 2026-10-06 03:04:35 +11:00
sam ab9db7cfe3 feat(install): bundled PostgreSQL has no network and is reached by Unix socket; print an AppArmor profile instead of disabling the userns restriction 2026-10-06 03:04:12 +11:00
sam 3d02d1d2d9 fix(install): do not start the services when the bundled PostgreSQL failed to start 2026-10-06 02:38:56 +11:00
sam e503263317 chore(release): v1.47.0 2026-10-06 02:03:15 +11:00
sam a012f1ad37 feat(install): install from a verified release with curl | bash; ship docker-compose.yml in the release 2026-10-06 01:55:37 +11:00
sam 17b6fa7245 fix(setup): keep the generated database password out of config.toml 2026-10-06 01:55:37 +11:00
sam 1d02c7e3e6 ci: allow unprivileged user namespaces for extension confinement 2026-10-06 01:55:37 +11:00
sam 7892c927ce feat(setup): one guided flow; ask for PostgreSQL and generate the bundled database's password 2026-10-06 01:49:34 +11:00
sam 209f2b4adb docs: server quickstart, standalone template first, install starts PostgreSQL 2026-10-06 01:43:16 +11:00
sam 28bb4b4483 feat(storepkg): install packages from a signed default catalogue, listed on the Extensions page 2026-10-06 01:18:25 +11:00
sam 8d73280633 feat(telegram): /stop stops the chat agent, else the tasks it created, or one task; delete the dead approval actions 2026-10-06 01:12:28 +11:00
sam c654ba7cd1 fix(modelloop): mark reasoning models from the carried model limits, in the gateway and the agent worker 2026-10-06 00:57:20 +11:00
sam 0fc8535d87 fix(eda): name a source's delivery header in the dashboard instead of a built-in sender list 2026-10-06 00:54:20 +11:00
sam a355f13a03 fix(eda): dispatch each webhook delivery once, however often the sender retries it 2026-10-06 00:51:45 +11:00
sam cf34d03476 fix(release): push the release commit and its tag atomically 2026-10-06 00:50:12 +11:00
sam f9896f509d fix(webui): list services with the State Store marked down when it is unreachable 2026-10-06 00:48:45 +11:00
sam 9f3ad773cd fix(modelloop): feed the cached model catalog to the runtime so reasoning models get the right token parameter 2026-10-06 00:45:09 +11:00
sam c0586e465c fix(captureintake): decode any form-encoded webhook body to JSON 2026-10-06 00:37:20 +11:00
sam 4fd53d3f44 Reapply "fix(captureintake): unwrap form-encoded webhook payloads"
This reverts commit a9991f6d91.
2026-10-06 00:36:52 +11:00
sam a9991f6d91 Revert "fix(captureintake): unwrap form-encoded webhook payloads"
This reverts commit 378797ef6e.
2026-10-06 00:35:50 +11:00
sam e20860fcab chore(deps): bump ai-sdk to v0.1.42
Picks up the class-scoped request shaping fix: openai-compatible
transports keep max_tokens instead of receiving max_completion_tokens.
2026-10-06 00:24:55 +11:00
sam 378797ef6e fix(captureintake): unwrap form-encoded webhook payloads 2026-10-06 00:10:43 +11:00
sam f555b9171b fix(extension): confine each extension's network to its accepted egress hosts 2026-10-05 23:30:52 +11:00
sam 9c20a8f2e0 feat(ui): org switcher and new org for instance admins 2026-10-05 23:18:50 +11:00
sam 84050080a7 fix(archiegateway,agentexec,agentworker): rely on ai-sdk reasoning token selection
Bump github.com/samcharles93/ai-sdk v0.1.40 -> v0.1.41. ai-sdk now sends
max_completion_tokens for reasoning models and omits temperature when the
model rejects it, so the max_tokens workarounds are no longer needed: the
chat-turn bound is set directly and MCP sampling loses its reasoning
branch. Classic models keep their existing bounds.
2026-10-05 22:56:48 +11:00
sam 7a6603078a fix(ui): trim filler prose and expose appearance in settings nav 2026-10-05 22:20:16 +11:00
sam 07adab1eda feat(ui): org area with members, agents, workspaces, access and tokens 2026-10-05 22:09:42 +11:00
sam 7f2fd08840 feat(org): instance admins manage every org 2026-10-05 22:08:01 +11:00
sam 2d55f9ead2 fix(daemon): withdraw only issues the same dispatch rule found eligible and then lost 2026-10-05 22:04:41 +11:00
sam 9431201d32 feat(taskactions): merge pull request action from the task 2026-10-05 21:40:25 +11:00
sam 3a90225da1 fix(controlplane): report watch outages and align live/restart kind labels 2026-10-05 21:39:07 +11:00
sam 68d0fe9055 feat(ui): edit retry backoff and needs on the canvas 2026-10-05 21:32:30 +11:00
sam 0f0795e6f1 feat(eda): name and delete capture sources; an armed binding blocks the delete 2026-10-05 21:05:58 +11:00
sam 1628cbc312 chore(ui): rebuild dist after merging task log paging 2026-10-05 21:03:53 +11:00
sam b26de90e38 feat(webui): page through task logs 2026-10-05 21:03:08 +11:00
sam 087ce10b86 feat(webui): run details show inputs, outputs and workflow.call links both ways 2026-10-05 21:01:39 +11:00
sam 799632339f fix(ui): show step retries as archie's record, not the agent's report 2026-10-05 21:00:25 +11:00
sam bf73f96de5 feat(workflow): each remediation round names its number, cap and the review it answers 2026-10-05 20:58:05 +11:00
sam bfebdec1bf feat(daemon): record an approving review on the task's timeline 2026-10-05 20:56:13 +11:00
sam e084c55fcc feat(workflow): record each failed attempt of a retried step 2026-10-05 20:54:38 +11:00
sam 2998a2ed13 feat(workflow): later steps read a waited workflow.call's outputs as its result 2026-10-05 20:52:58 +11:00
sam 34077cb4ca feat(daemon): withdrawing an issue declines its queued or running work 2026-10-05 20:50:57 +11:00
sam 4295bf6e46 fix(webui): member changes need the admin grant and owner changes an owner 2026-10-05 20:49:58 +11:00
sam 955e366b9c fix(webui): the org-sys owner is the instance owner 2026-10-05 20:47:52 +11:00
sam d4d3a1ea7e chore(ui): rebuild dist after merging the org API 2026-10-05 20:45:36 +11:00
sam 2f8a91010f feat(org): org, workspace and membership API 2026-10-05 20:44:49 +11:00
sam 9f3e8285b5 feat(eda): pause and resume a binding; resuming goes back through approval 2026-10-05 20:44:25 +11:00
sam add33fb3d9 feat(daemon): the timeline names and links the binding and capture that started a task 2026-10-05 20:39:26 +11:00
sam 0df1c41362 fix(ui): offer resume only where the server accepts it 2026-10-05 20:37:38 +11:00
sam 35a23d5ca1 fix(workflow): refuse undeclared inputs and result fields at save 2026-10-05 20:35:50 +11:00
sam 0acf7981d9 feat(access): the dashboard operator is a person owning org-sys 2026-10-05 20:33:22 +11:00
sam abf3ae0ff9 refactor(archied): drop the unreachable multi-identity webhook skip; validation refuses it 2026-10-05 20:32:43 +11:00
sam 65fbb3e1aa fix(daemon): webhook forge intake does not poll for issues 2026-10-05 20:31:39 +11:00
sam 24c5fc86db fix(postgres): collect inline comments on a review queued behind a running remediation 2026-10-05 20:30:25 +11:00
sam 794b818f4c refactor(org): rename the default org to org-sys 2026-10-05 20:27:46 +11:00
sam 57660a19b5 fix(ui): restoring shipped workflows keeps custom ones 2026-10-05 20:27:38 +11:00
sam de6497dd14 fix(webui): admit dashboard work requests through the State Store and honour the workflow's repository mode 2026-10-05 20:25:20 +11:00
sam dd8729bcf7 feat(webui): page and filter the task list on the server 2026-10-05 20:21:51 +11:00
sam 8c81661e01 chore(ui): rebuild dist after merging workflow step recording 2026-10-05 20:20:40 +11:00
sam 261a50bc40 feat(workflow): record steps skipped by when as skipped 2026-10-05 20:20:23 +11:00
sam cf8868b744 feat(workflow): record parallel branch steps as their own steps 2026-10-05 20:20:22 +11:00
sam dff26fe98b feat(eda): record every terminal binding outcome and flag failing bindings 2026-10-05 20:17:52 +11:00
sam 83cc810e94 feat(eda): link binding dispatches to the captures and tasks they started 2026-10-05 20:16:02 +11:00
sam 1a26bf06b5 feat(taskactions): rejecting a pr_open task closes its pull request 2026-10-05 20:11:38 +11:00
sam 24df173a31 fix(workflow): validate handoff and approve targets at save 2026-10-05 20:09:59 +11:00
sam b38b3f6961 fix(workflow): validate workflow.call inside parallel branches 2026-10-05 20:09:59 +11:00
sam 47558078ce fix(daemon): refuse a disabled workflow on every start path 2026-10-05 20:08:18 +11:00
sam 2f6c53090e fix(daemon): record terminal non-dispatch outcomes so a capture is evaluated once 2026-10-05 20:06:45 +11:00
sam 01f9b5986b refactor(configuration): delete the dead runtime config overlay
The file overlay path has folded partial map-valued entries since
a9029411, answering xrux's open question: a decode that zeroes omitted
fields is the old behaviour, kept only by the now callerless runtime
overlay. Loader.ApplyOverlay, ApplyOverlayValues and
applySchedulingOverlay had no callers anywhere in the tree, so the fold
machinery stays and the dead runtime path goes.
2026-10-05 19:21:05 +11:00
sam d5e07333fa refactor(gateway)!: drop budget_key with the webhook chat channel 2026-10-05 18:10:41 +11:00
sam 515c2edf2f feat(messaging): serve MessagingService.Deliver and deliver chat schedules through it 2026-10-05 18:01:33 +11:00
sam 77723baf75 refactor(config): drop the unwired artifact sender and [artifacts] config
The artifactsync client had no importer and [artifacts] parsed but was never
read, so the capability was dead. Remove the package, the config field and
type, the token defaulting, and the example section. A leftover [artifacts]
key now reports as unrecognised, like any other removed key.
2026-10-05 17:16:32 +11:00
sam b9787cebbe feat(gateway): load SOUL into the chat prompt per turn
SOUL now owns the prompt identity slot via a per-turn source: a stored soul
resource wins once saved, otherwise the identity's SOUL file, then the
shipped default. The gateway watches the resource so a dashboard edit
reaches the next turn without a restart; a file read error degrades to the
default and logs once.

The persona prompt plumbing is replaced by the SOUL source; the persona
surface itself (registry, wire, page, commands) stays for archie-core-7ftt.
2026-10-05 17:14:20 +11:00
sam 9e4ec516c9 feat(releaseupdate): install from release artifacts with journaled rollback, topology check and channels 2026-10-05 17:02:29 +11:00
sam add2546e54 refactor(archieui): leave channel reload unserved by the gateway 2026-10-05 15:15:44 +11:00
sam 3f494b4247 feat(gateway): serve the dashboard skills and curators over ChatService
Add ListSkills, CuratorHealth and ReloadChannel to the gateway chat contract. The
Gateway process supplies its live skill catalogue and curator registry through a
Catalog seam; archie-ui adapts the RPCs to the webui view interfaces and wires
them in compose. The Gateway hosts no channels, so ReloadChannel answers
Unavailable here; the channel request surface is archie-core-np7l.
2026-10-05 15:05:09 +11:00
sam c73ff313ea refactor(config): drop unused dispatch state labels
The daemon stopped setting forge state labels when label-driven retry was removed; the config field, helpers and defaults had no consumer. Remove them and the Scheduling policy page's State labels section.
2026-10-05 15:05:06 +11:00
sam 886a151341 fix(webui): stop returning database_url from /api/config 2026-10-05 15:04:51 +11:00
sam 8ba067ce32 fix(ui): keep JSON copy inline on hover 2026-10-05 14:58:36 +11:00
sam e0db40963e fix(postgres): queue a review that arrives during a remediation
A review reaction that landed while a remediate run owned the task failed the
pr_open guard, was acked and dropped, and the poll cursor advanced past it.
Runs against one task are serialised, so the unit is appended to
tasks.pending_reviews instead; the transition that returns the task to pr_open
promotes the oldest waiting review back to queued. A re-delivered unit is
absorbed by payload equality, never queued twice.
2026-10-05 14:58:14 +11:00
sam 70322bd5fb fix(ui): load task debug reliably and copy JSON output 2026-10-05 14:54:12 +11:00
sam fe30a02072 feat(ui): select review gate findings before approval 2026-10-05 14:43:07 +11:00
sam 6a8481f203 fix(ui): reveal signing secret in canvas source creation 2026-10-05 14:33:27 +11:00
sam 22a4dcf46a feat(ui): bind an event to a workflow from its Start node
Pick a source and one of its captured events, map each declared input to a
payload path or a fixed value with a live preview, and save the mapping and
binding together. Existing bindings open from Starts when for editing and
approval; the Start node updates at once.
2026-10-05 13:20:55 +11:00
sam 6ee7321e6b feat(workflow): resume a parked run from a chosen step
Each finished stage records the run's step results; a retry may name a resume
point, and the next attempt skips the steps before it with their results
loaded. A run with a repository resumes only on its pushed branch. The canvas
offers Resume/Re-run from here on parked runs.
2026-10-05 13:06:30 +11:00
sam 1510c41254 feat(ui): inspect workflow step runs from canvas 2026-10-05 12:53:34 +11:00
sam 895a04047d feat(ui): drive workflows from the canvas: run a workflow, act on the watched run, edit workflow settings from the Start node; the canvas fills the viewport 2026-10-05 11:45:50 +11:00
sam c9099e6f04 docs: WORKFLOWS.md documents the workflow definition schema and step vocabulary 2026-10-05 11:37:51 +11:00
sam c76b973ea8 fix(ui): workflow page header is one tab row with save and a more menu; drop the ID field, step list, version footer and the meaningless origin pill 2026-10-05 11:29:16 +11:00
sam a8d0c82da7 feat(ui): canvas authoring by right-click menu and + insertion points; steps edit in a slide-in panel and show what they do 2026-10-05 01:23:58 +11:00
sam d12e46dc38 feat(ui): the canvas Start node lists what starts the workflow: issue routes, event bindings, playbooks and other workflows 2026-10-05 00:48:08 +11:00
sam e46eeb67dd feat(ui): build workflows on the canvas: step palette, schema-driven settings forms, references to earlier results, reorder and remove 2026-10-05 00:44:22 +11:00
sam 3072ba595f feat(controlplane): serve each step type's settings schema; the workflow editor checks settings before save 2026-10-05 00:39:47 +11:00
sam 720cd7a6f0 feat(ui): the workflow canvas watches a run live: each step shows its state, duration and error, and the view follows the step in progress 2026-10-05 00:34:06 +11:00
sam dfff9f6b11 feat(ui): workflow canvas renders each definition as a step graph with data edges, parallel branches and conditions 2026-10-05 00:27:32 +11:00
sam ae99b47581 feat(workflow): retries, parallel branches, review steps; every shipped workflow is YAML and the per-workflow step types are gone 2026-10-05 00:10:04 +11:00
sam eeccb2e995 feat(workflow): when conditions, handoff, human approval and forge steps; feasibility and triage ship as YAML 2026-10-05 00:06:35 +11:00
sam 4efb835eed feat(workflow): repository step types; implement and tdd ship as YAML in general steps 2026-10-05 00:04:34 +11:00
sam 880a898ecb feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure 2026-10-05 00:02:07 +11:00
sam fba2d4ee09 refactor(workflow): delete the bootstrap smoke-test workflow and its intake kind 2026-10-04 23:41:52 +11:00
sam 666a034202 fix(ui): drop the topbar nav's edge fade that clipped the first item 2026-10-04 23:13:07 +11:00
sam a5279bb187 feat(controlplane): serve the step vocabulary in the workflow-definitions schema; the editor checks step types against it 2026-10-04 23:00:14 +11:00
sam c885eb5bec fix(webui): drop the repository review switch the server no longer accepts 2026-10-04 21:01:52 +11:00
sam e45d69ef58 fix(webui): bind the container runtime document's keys, drop the blank Advanced page
ContainerRuntimePage still bound the Go field names the document carried
before archie-core-qna6 gave container-runtime-policies its own snake_case
shape. Every control read a key the document does not hold, so the fields
rendered empty and DurationInput warned on each mount; the page's Profiles
section wrote to a key the decoder drops. Bind image, max_concurrency,
max_uptime, volume_ttl, pull_policy and network, drop the dead Profiles
section (named profiles live in the agent-profiles resource, filed as
archie-core-x0wk), and pin the key list in a test the migration lacked.

Settings -> Advanced rendered nothing in any deployment: its only card needs
the sandbox dangerous-command authority, which has no implementation
(archie-core-sod1). Drop it from the sidebar, the router and the gateway's
dashboard page index; the page and its components stay in the tree for sod1.

Register CardAction in SetupPanel and EmptyDescription in TaskLogs, which Vue
was resolving to nothing, so the setup percentage and the log empty-state
descriptions render again.
2026-10-04 20:51:57 +11:00
sam a2a6ab3dfb feat(egress): the run credential is the proxy login; Kit secrets resolve per request from live grants 2026-10-04 19:35:26 +11:00
sam a5d747df72 fix(nats): containers log in with their run credential and reach only their task's subjects 2026-10-04 19:33:14 +11:00
sam 2aea980a01 refactor(forgerpc): identity RPC subjects are keyed by identity ID 2026-10-04 18:58:10 +11:00
sam 0e45001b2e feat(staterpc): every run start is audited by the State Store, or the run credential is withdrawn 2026-10-04 18:57:19 +11:00
sam e192308c90 feat(daemon): a workflow that names an identity runs as it; the dispatcher needs run on the workflow 2026-10-04 18:55:37 +11:00
sam 06b8aeebeb feat(controlplane): identity credential grants edited from the dashboard and applied live 2026-10-04 18:53:32 +11:00
sam cc5e0076af fix(forgerpc): forge calls need the run credential and reach only the run's own repository 2026-10-04 18:34:16 +11:00
sam 40d1062e08 feat(staterpc): one run credential per task, kept in the State Store, authorizes its store calls and its push 2026-10-04 18:32:45 +11:00
sam 56f2bf8a5d fix(archieui): a sign-in provider outage is a health issue, not a startup failure 2026-10-04 18:12:23 +11:00
sam 90399f5025 feat(identity): personal API tokens, created and revoked from the dashboard, act as their owner 2026-10-04 18:10:28 +11:00
sam b5edf2986e feat(contracts)!: requests no longer name their org; the State Store derives it from the caller 2026-10-04 17:28:31 +11:00
sam 1f01293f8c fix(controlplane): change history names kinds and reads only the caller's org 2026-10-04 17:25:47 +11:00
sam 7efc96bf70 fix(gatewayrpc): sender_id and rate_limited cross the chat wire 2026-10-04 17:18:38 +11:00
sam 5b3441c553 chore: delete the orphaned PR review benchmark 2026-10-04 17:17:20 +11:00
sam 5a3a693582 feat(skills): skill packages project into a skills resource the gateway reads live 2026-10-04 17:08:50 +11:00
sam 55bb4223c2 refactor(channels): webhook and email run only as extensions; their channel settings go 2026-10-04 17:04:21 +11:00
sam 0e580dd979 feat(channelext): chat channels served by extensions; messaging runs the enabled ones 2026-10-04 15:56:05 +11:00
sam 9ccfc020f7 feat(staterpc): the State Store derives org and actor from the principal archie-ui forwards 2026-10-04 15:54:22 +11:00
sam 755f367ca0 refactor(forge): github and gitea leave core; webhooks parse in the forge extension 2026-10-04 14:26:27 +11:00
sam 153dfc094c feat(forgeext): forge surface served by extensions; forge.type names the installed package 2026-10-04 13:56:32 +11:00
sam 37c6a71343 feat(controlplane): playbooks and agent profiles install from packages; the daemon reads eda-playbooks live 2026-10-04 13:49:03 +11:00
sam 9d7b8d9814 feat(staterpc): attribute State Store calls to the calling service; policy audit records it 2026-10-04 13:48:37 +11:00
sam b693065d09 style(access): adopt task fmt output 2026-10-04 13:44:04 +11:00
sam 3433bc7068 feat(access): instance network rules at the capture receiver; policies reload without a restart 2026-10-04 12:58:00 +11:00
sam be541d6aee feat(access): edit org, workspace and object policies from the dashboard; refuse owner lockout 2026-10-04 11:02:42 +11:00
sam 3a8879e6e9 fix(configuration): an overlay stands in for a missing config file; dev overlay is complete 2026-10-04 03:47:17 +11:00
sam b47e3a0b70 feat(archiemessaging): verify update reports against archied's presence and restore release announcements 2026-10-04 03:39:47 +11:00
sam 9a8c5722fa build(dev): task dev runs archie-messaging 2026-10-04 03:37:22 +11:00
sam 3b07bcb19f feat(presence): services card on the status page and archied status 2026-10-04 03:29:05 +11:00
sam d82651222a refactor(examples): the firewall workflow moves to archipelago 2026-10-04 03:10:23 +11:00
sam 647b9bcce7 chore: remove Yaegi
yaegiutil, the go.mod dependency, the .yaegi host-code entry and the legacy
guard stages for .archie/gate.go and .archie/stages are gone.
2026-10-04 03:08:46 +11:00
sam 2ae46582a8 refactor(skill): delete Yaegi skill scripts and the run_go_script tool
No shipped skill used plugins/. The agent request drops its Plugins field with
the staging code behind it.
2026-10-04 03:07:39 +11:00
sam 38219a7035 refactor(module): the log action is built in; delete the module loader and reconciler
module_dir, logextract and examples/modules go with the Yaegi loader. The plugin
reconciler had only the module directory left to watch, so it goes too.
2026-10-04 03:06:20 +11:00
sam 510172480b refactor(plugin): delete Yaegi daemon plugins and plugin_dir
Nothing consumed plugin.Plugin. The daemon's capability host held only those
plugins, so it goes too. The lint fix to the extensions access test rides along.
2026-10-04 03:04:35 +11:00
sam 785053c470 feat(presence): every service re-stamps a presence record in the State Store 2026-10-04 01:57:13 +10:00
sam f27aafbd66 feat(webui): install, accept and enable extensions from the dashboard 2026-10-04 01:56:10 +10:00
sam 5b42e4cba9 feat(storepkg): fetch packages from any registry, plain HTTP on loopback only 2026-10-04 01:53:00 +10:00
sam 1e435e9224 style: adopt task fmt output; regenerate contracts and sqlc code; gateway cleanup derives its context
goimports during the service refactors rewrote generated files; they are
restored from their generators.
2026-10-04 01:48:32 +10:00
sam a4317f2660 fix(configuration): bindings encryption keys must use the env engine 2026-10-04 01:46:16 +10:00
sam 7c011e8bf7 build(modelcatalog): read catalog metadata from ai-sdk/catalog
ai-sdk v0.1.40 moves the models.dev types into a dependency-free package, so
archied no longer links every provider client for catalog metadata.
2026-10-04 01:39:02 +10:00
sam 07d4fcb627 refactor(agentexec): model loop moves to agentexec/modelloop
agentexec's wire contract, harness adapters and log forwarding no longer
import the AI SDK; the in-process model loop, runtime, tool set and sampling
helpers that do now live in agentexec/modelloop, used by the Gateway and
archie-agent only.
2026-10-04 01:36:13 +10:00
sam 81f430de58 ```
chore: remove inline comments from update script
```
2026-10-04 01:33:18 +10:00
sam bf33ec9535 refactor(agentrun): agent stage contract moves to the domain layer
internal/domain/workflow imported internal/agentexec for its protocol types,
pulling the AI runtime into every binary that touches workflow types. The
request, result and runner contract now live in internal/domain/agentrun;
agentexec keeps the runtime. The model catalog cache moves from servicekit
into modelcatalog and WaitForPeer into staterpc, so archie-state-store and
archie-messaging no longer link the AI runtime.
2026-10-04 01:33:00 +10:00
sam c486fe291c refactor(archieplaybooks): fold archie-playbooks into archied playbooks lint|serve 2026-10-04 01:20:33 +10:00
sam 7d795fdd4f docs(deployments): service data ownership; start order no longer matters 2026-10-04 01:17:48 +10:00
sam 794c7ac8c6 fix(services): services wait for peers instead of exiting; restarted broker keeps its endpoint
State Store calls from the daemon, Gateway and Messaging wait for the store to
come up, so start order no longer matters; the daemon's state_db probe carries
its own deadline so an outage reports degraded instead of hanging. The
Gateway retries its first NATS connect. A restarted daemon reuses the embedded
broker's previous port and token, so the Gateway reconnects instead of
holding a dead address. Fixes a nil catalog the catalog move introduced.
2026-10-04 01:15:11 +10:00
sam d8d6d7318b chore(lint): depguard keeps each service's packages to its own composition 2026-10-04 00:59:54 +10:00
sam e0701b18a3 refactor(archiegateway): own package for the Gateway service
archie-gateway no longer links the daemon, the web UI or archied. Shared
runtime layering, watches, catalog, NATS discovery and the State Store client
live in servicekit; chat task profiles in chattask. The Gateway waits for the
daemon's NATS endpoint instead of starting a second broker, and chat
approvals go through the task-action client instead of a local service with
no daemon behind it. Version stamping uses buildinfo only.
2026-10-04 00:59:02 +10:00
sam 9dd39c9d24 refactor(archied): gateway owns model work; daemon drops chat runtime, tools, memory and curators
The gateway now applies provider, model-role and tool settings live and
runs the curators, which wake on its turns and read its conversations.
2026-10-04 00:48:28 +10:00
sam bf1a4ec6d7 refactor(statestore): own package for the State Store service; access reset moves to archie-state-store 2026-10-04 00:46:11 +10:00
sam 0754c5e0da docs(archied): drop secret engines from the plugin reconciler comment 2026-10-04 00:43:59 +10:00
sam 1936d9c353 feat(secretengine): serve secret engines as go-plugin extensions
A secret engine is now a subprocess serving secretengine.v1, installed through
the package store's new extensions family and enabled by extension-settings.
bws leaves the binary, as do the Yaegi engine loader and its examples.
2026-10-04 00:40:23 +10:00
sam 44695b1846 docs: services own contracts; failure stays local 2026-10-04 00:32:58 +10:00
sam 35e72d81ff chore: ignore archipelago marketplace symlink 2026-10-03 23:20:13 +10:00
sam 7e98ca254c chore: remove obsolete gitignore entries
The diff only trims three ignore rules (`.impeccable/`, `.serena/`, `/site/`) and their associated comment from `.gitignore`, so a single subject line captures the whole change.
2026-10-03 23:07:24 +10:00
sam 6078dc1565 docs: constitution review edits; state the wiring rule without naming a file 2026-10-03 22:38:44 +10:00
sam 75988204d5 docs: strip doc and issue references from config, deployments and examples 2026-10-03 22:27:08 +10:00
sam 1a3fbe042e docs: remove verbose comments from Dockerfiles 2026-10-03 22:19:49 +10:00
sam cb6b8618c2 refactor: cut remaining long comments down to what the code does 2026-10-03 22:06:57 +10:00
sam 0cbb65c684 refactor(setup,messaging,container,agentworker,discovery,memory,eventbus): cut comments down to what the code does 2026-10-03 22:02:57 +10:00
sam e10980dc33 refactor(postgres,mcp,archieui,task,prreview,playbook): cut comments down to what the code does 2026-10-03 22:01:54 +10:00
sam 3360cddb5a refactor(staterpc,releaseupdate,agentexec,storecontract,worktree): cut comments down to what the code does 2026-10-03 22:00:43 +10:00
sam c30844180b refactor(controlplane,messaging,logging): cut comments down to what the code does 2026-10-03 21:59:35 +10:00
sam 4ebde6b315 refactor(configuration,builtin): cut comments down to what the code does 2026-10-03 21:58:23 +10:00
sam 58150a920d refactor(daemon): cut comments down to what the code does 2026-10-03 21:57:24 +10:00
sam 5719cd51cb refactor(config): cut comments down to what the code does 2026-10-03 21:56:41 +10:00
sam d0fd78e6a9 fix(archied): restore contextcheck directives and drop unused adapter 2026-10-03 21:55:48 +10:00
sam c167358118 refactor(telegram): cut comments down to what the code does 2026-10-03 21:55:00 +10:00
sam 7cf0db7e9a refactor(webui): cut comments down to what the code does 2026-10-03 21:54:14 +10:00
sam 4d00884ea5 refactor(gateway): cut comments down to what the code does 2026-10-03 21:53:24 +10:00
sam 239cde9c2b refactor(workflow): cut comments down to what the code does 2026-10-03 21:52:21 +10:00
sam 030b4ed176 refactor: strip doc and issue narration from code comments
Remove PRD/doc paths, bead IDs, phase notes and deleted-test references
from comments; drop test-only hooks left by the test deletion. Includes
in-progress archied bootstrap, gateway and query changes.
2026-10-03 21:47:46 +10:00
sam a8a118c1b8 chore: cut agent governance to a single constitution
Replace CLAUDE.md with a short decision-rule constitution; move PRDs,
architecture, development and design docs and repo skills out of the tree;
delete the docs tooling (docsgen, prdlint, docdrift, docsite, contractaudit,
reachaudit) and its gate steps; stop install.sh copying repo skills into
runtime skills.
2026-10-03 21:47:46 +10:00
sam 780bc44d82 refactor: testing from the beginning. a journey in 150k lines of tests to none 2026-10-03 21:16:25 +10:00
sam f0fe550a35 fix(build): restore the go fix fixpoint, and give the formatter one owner
A "reduce Taskfile bloat" refactor (0d35e753) removed the fixpoint loop from
task fmt and deleted the guard test that proved it, putting the tree back to a
single go fix pass with nothing left to notice. One pass is not a fixpoint:
stditerators rewrites `for i := range t.NumFields()` into a field iterator that
copies its loop variable, and forvar only deletes that copy on the following
pass, leaving a tree copyloopvar rejects. archie-core-wwho regressed silently.

Restore the loop and the guard. The deploy workflow has always inlined its own
single `go fix ./...`, which is how the same hazard reached CI as a spurious
git-diff failure rather than a lint error (archie-core-6kda); it now calls task
fmt, the one owner of the formatter sequence, and its guard rejects an inline
copy so the split cannot come back.
2026-10-03 02:28:33 +10:00
sam 152c8b85a2 fix(tools): resolve docdrift citations against the tracked tree
The gate resolved a citation with a filesystem stat, so a directory left behind
by a checkout that removed its files -- internal/gate and internal/gate/gateeval
among them -- resolved on the developer's machine and did not exist in CI. The
baseline was generated that way, so it passed locally and failed CI on the same
commit, which is the state a gate must never be in.

Read the tracked tree from git ls-files and resolve against that: a tracked
file, a directory containing tracked files, or a file-shape template matched
against tracked siblings. Failing to read git is fatal rather than a fallback to
the filesystem, because the fallback is the bug being fixed.

Regenerate the baseline, which now records the citations the filesystem check
was masking. Verified by running the tool in a clean worktree at HEAD: identical
counts to the working tree, exit 0.
2026-10-03 02:24:01 +10:00
sam 0d3ec4f127 fix(controlplane): an absent MCP server field inherits the file value
The layering rebuilds cfg.Tools from the control plane's projection wholesale,
and ParallelToolCalls was a plain bool. A tool-settings resource seeded before
the field existed therefore carried no key for it, the zero value replaced the
operator's file-level parallel_tool_calls = true, and the setting was inert --
on exactly the stores that cannot be re-seeded, which is the case a new field
has to reach.

Make it a *bool: the shape schedulingPolicy.Label documents, and the shape the
mcp headers in this same function already use. Absent now means "leave the
file's value in force", an explicit stored value still outranks the file, and a
server with no file entry has nothing to inherit and keeps the zero value.
2026-10-03 02:20:06 +10:00
sam 703692ca7a feat(workflow): add the command.run step type
archie-core-ndm8 accepted the command-step trust decision, so a stored
workflow definition may run operator argv. The workflow engine has exactly one
call site -- agentworker, which is what the container agent serves -- so the
step runs on the container path by construction. A non-zero exit parks the run;
level: warn makes it advisory.

Settings mirror the repository gate's command shape (name, argv,
expect_failure) so a command means the same thing in both places. The settings
type is local rather than agentexec.Command because that struct carries JSON
wire tags only, and YAML decoding silently dropped expect_failure -- a command
declared to fail would have been reported as passing. A reflection test holds
the two shapes together.
2026-10-03 02:07:45 +10:00
sam 8f8e732b3a fix(configuration): make bot_user required, defaulted, and named
bot_user names the agent that chat turns and the session curator attribute memory
to. The loader requires it of a single-identity deployment, but nothing covered
the two paths between that requirement and the consumers.

local-ollama-standalone.toml set no bot_user and defined no [[identities]], so a
profile AGENTS.md lists as supported could not load at all (archie-core-cx0d).
Give the profile the field, and make the regression guard enumerate
deployments/*.toml through the production loader instead of naming two files, so
a profile added later is covered the moment it is committed. dev.toml is
excluded because it is a development overlay layered over an installed config
rather than a standalone profile, and the exclusion is itself checked so a
renamed overlay is noticed instead of silently widening the rule.

The root BotUser was validated only when no [[identities]] block was present, so
a config with exactly one identity left it empty: the curator then skipped every
session with "no agent id" while the chat turn path ran with the same empty agent
(archie-core-4slp). applyIdentityDefaults now adopts a sole identity as the root
single-identity values -- which is what those fields mean -- and leaves the root
alone when two or more identities leave no single answer. The skip reason now
names bot_user, so the remaining case reads as configuration rather than as a
data problem.

Both regressions were red-first: the enumerated profile test failed on
local-ollama-standalone.toml before the profile was fixed, and the sole-identity
test failed before applyIdentityDefaults adopted it.
2026-10-03 01:48:28 +10:00
sam 61ecc14327 fix(webhookguard): verify uppercase-hex HMAC signatures
VerifyHMAC compared the supplied signature against the computed digest as
case-sensitive hex text, so a sender that emits an uppercase digest failed
verification -- and the failure is indistinguishable from a wrong secret. The
helper is shared by all three inbound surfaces (forge intake, the chat webhook
gateway, capture intake), so one such sender breaks whichever surface it
targets.

Decode both sides to raw bytes and compare those. hex.DecodeString accepts
either case, and comparing digests rather than their text keeps the comparison
constant-time -- strings.EqualFold over the encoded text would not be. A
signature that is not valid hex is rejected outright, and a digest of the
wrong length simply does not match.

archie-core-rl04
2026-10-03 01:44:17 +10:00
sam 66167571cb feat(tools): fail the gate when docs cite a path that no longer exists
docs/architecture is declared authoritative for settled design, so a page that
cites code which has moved actively misleads every session and every subagent
brief that reads it. Nothing in the gate compared a prose citation against the
tree: docsgen checks the contract schema against Go types, docsite checks
generated artifacts against their Markdown sources, prdlint checks PRD writing
style. All three verify internal consistency, so a page can describe a package
deleted months ago and every check stays green -- which is how a page describing
a removed system survives behind a hand-written "removed" banner.

Add tools/docdrift. It resolves every internal/... citation under docs/ against
the tree and fails on one that dangles, handling the shapes prose actually uses:
a package with a symbol (internal/config.Config), a test with its package
(internal/app/archieui/TestFoo), a file-shape template
(internal/webui/api_<concern>.go), and a Go package pattern (internal/...).
Generated artifacts are skipped so embedded page bodies are not double-counted.

The baseline is a burn-down list of the 48 citations already broken -- packages
that moved (internal/store, internal/memory, internal/nats) and ones never built
(internal/policy, the image and research capability docs). It is not a licence:
the check also fails when an allowlisted citation starts resolving again, so an
exemption cannot outlive its reason. Regenerate with `docdrift list`.

Wire it into `task check` as docs:drift.

Also correct AGENTS.md, which listed `policy` among the cross-cutting packages
sitting under internal/. No such package has ever existed in this tree; the
design is approved and unbuilt (docs/architecture/policy.md). That is exactly
the class of stale claim this check now catches.
2026-10-03 00:31:06 +10:00
sam aacec67c24 docs: delete the superseded adversarial review document family
The adversarial self-review system was removed in 625ead95, but four pages
describing it survived: the architecture page, its design-decision PRD, and the
two superseded calibration/operator PRDs. The architecture page carried a
hand-written "removed, not shipped" banner and was kept only because live PRDs
linked to it, so every reader paid for a system the tree no longer has.

Delete all four and repoint the live referrers at the authority that replaced
them (docs/prds/pr-review-agent.md): inline-review.md's Builds-on line,
pr-review-remediation.md's isolation-contract citation, pr-review-agent.md's
supersede clause, CLAUDE.md's contributor rule, and three Go comments that cited
the deleted paths. Regenerate docs/data/generated/dev-docs.json.

History stays in git; the tree stops describing a system it does not have.
2026-10-03 00:01:42 +10:00
sam 0adc165c4c fix(webui): navigate the Events chain once, not twice
The page drew the same three panels twice: a numbered Capture/Map/Bind
strip and, directly under it, a tab list naming Inspector/Mappings/
Bindings. Both drove the same `?tab=` through the same handler, so the
page read as one wizard drawn twice and named the same three panels with
two different vocabularies in a single view.

The strip survives. It names each step for what the operator does to it
rather than for what the panel holds, and it is the one that reads as a
chain. The step words move to tab-selection.ts as stepsFor(), beside the
rules they belong to; the URL keeps its ids.

Making the strip the only navigation also fixes a latent fault. It
listed all three steps unconditionally, so a composition the server
refuses `mappings` still drew a Map step with no panel behind it, and
clicking it fell back to the first available tab, which did nothing.
stepsFor() returns exactly the tabs this composition can back, and the
page renders an empty state when that is none of them.

ui/dist rebuilt in the same commit: the Go build embeds it.
2026-10-02 23:08:41 +10:00
sam 483f50d030 fix(storepkg): mask the tar mode to the permission bits before narrowing
The conversion is now exact rather than a truncation: the low nine bits are the permission bits whatever the tar header's width.
2026-10-02 22:45:07 +10:00
sam 27d9d7b397 fix(forge): refuse a review line number that does not fit an int
Gitea reports a review comment position as a uint64. Past the int range the conversion wrapped negative and would reach a reviewer as a line that cannot exist. Refused instead, with a test that fails when the guard is made inert.
2026-10-02 22:45:06 +10:00
sam eb624e53c6 fix(webhook): set a ReadHeaderTimeout on the forge webhook receivers
Both listen on the network without a header-read bound, the slowloris surface. Matches the timeout the other daemon servers already carry.
2026-10-02 22:45:02 +10:00
sam 9d7a7df496 fix(app): assign the temp-file close result on the error path
Each atomic-write helper returned the write error while silently dropping the close result. The success path already checks it.
2026-10-02 22:45:02 +10:00
sam c4b2bf5db7 chore(skills): give the diagnostics scripts their own build constraints
Both are standalone programs run by name from one directory, so the package could never build as a unit. The diagnostics skill invokes each file explicitly.
2026-10-02 22:45:01 +10:00
sam 0fe3caa175 chore(release): v1.46.0 2026-10-02 13:03:00 +10:00
sam 83d57ec6a2 fix(daemon): drop the import and assignment left by the composition cleanup
l45's refactor removed the assigned-but-unread daemon handles and l44 had
already moved the guardrail wiring out of the daemon, so the rebase union
left internal/daemon/daemon.go importing internal/tools with no use and
internal/app/archied/bootstrap.go assigning a Guardrails field that no
longer exists. main did not build.

Caught by building the merged tree rather than trusting the merge; the
merge train merged on a failed gate instead of chaining on it, which is
the mistake this commit repairs.
2026-10-02 13:00:56 +10:00
sam e762f15844 docs(agent-system): failure classification lives on the persisted record
The hazards list still claimed failure classification and retryability are
not represented explicitly. The persisted execution record has carried the
park class the parking code records since the typed-park work landed, so
the hazard now points at that record and the taskstate vocabulary instead
of restating a field list.

Regenerated the committed development-docs artifact for the edited page.
2026-10-02 12:57:53 +10:00
sam 1539fdc560 fix(daemon): classify workflow-pin parks by cause, not a blanket transient
pinTaskProfile parked every pinWorkflowDefinition failure as
taskstate.ParkTransient. That class documents that a requeue can succeed,
but the dominant pin failures are durable: a stored definition whose YAML
does not hash to the digest beside it, a definition that does not parse,
and a workflow or playbook binding resolving to an undefined workflow all
recur on every requeue until an operator repairs the row or the
configuration. A future retry pass reading transient as its input would
loop on them forever.

pinFailure now carries the class its cause needs, decided where the cause
is known, and pinParkClass reads it at the park site. A durable pin defect
parks operator-actionable; only a State Store read or persist failure --
the genuinely environmental case -- stays transient. The safe default for
an unclassified cause is ParkNeedsHuman, never a requeue that will fix it.

Red-first: TestDurablePinDefectIsNotParkedTransient failed at its
assertion before the fix (parked "transient"); TestTransientPinFailureStaysTransient
keeps the environmental case transient so the rule is per-cause, not a
blanket flip.
2026-10-02 12:57:53 +10:00
sam 0e37a0f536 refactor(daemon): drop assigned-but-unread composition handles
Three exported Daemon fields were wired by the composition root and read
nowhere: CapabilityHost (*plugin.Host), Curators (*curator.Registry) and
ToolRegistry (*tools.Registry). No field access exists anywhere in the
repo, and git history shows no read ever existed.

Each handle has a live owner outside the daemon: the curator
registry/runtime is boot-owned (the curator isolation invariant keeps it
off the agent loop), the capability host is lifecycle-owned by the
composition root and consumed by the control plane, and the tool registry
is consumed by chat, curator and MCP wiring. Keeping the daemon copies was
decorative wiring, so the fields, their composition assignments and the
now-unused plugin/curator imports go together.

The daemon architecture test now refuses the three names, and the plugin
host contract test refuses a CapabilityHost: handle on the daemon alongside
the PluginRegistry: one it already refused.
2026-10-02 12:57:53 +10:00
sam de32542c00 fix(agentworker): supply the guardrail engine to every task run
TaskContext.Guardrails was never assigned: the engine was built in
archied's composition root and held on Daemon.Guardrails, which no code
read after workflow execution moved to the full-task worker handoff.
archie-agent is a separate process, so a live engine cannot cross that
handoff. Build the engine at the agentworker composition root (the
process that runs agent stages), thread it through the task dependencies,
and set it on TaskContext; drop the now-dead archied-side construction.

Refs: archie-core-jd5v
2026-10-02 12:37:35 +10:00
sam c1673e43fb fix(config): carry max_retries into the worker TaskConfig snapshot
The remediate round cap runs inside archie-agent and reads
TaskContext.Cfg.MaxRetries, but TaskConfig did not carry the global
Config.MaxRetries: ForTask and ToConfig both dropped it, so a default
configuration reached the cap as 0 and a remediation never parked. Carry
the value (a repo-level override still wins via EffectiveMaxRetries) and
pin it with a red-first cap test traced through ForTask/ToConfig.

Refs: archie-core-ad3p
2026-10-02 12:37:35 +10:00
sam a9233755c3 fix(workflow): bind the remediate worktree before the builder runs
Commit 4e5b91d7 moved the remediate resume into daemon worktree
preparation and deleted StageResumeWorktree together with the Dir/Resume
pair it called, but nothing in the workflow replaced the binding it did:
TaskContext.Dir and Branch stayed empty for a whole run, so
remediate-build ran the builder with no workspace and
remediate-commit-push called CommitAll/Push with an empty dir and branch.

Extend the workflow-side Trees seam with the prepare target, mirroring
the daemon's mode-aware worktree.Manager.Prepare: PrepareFresh lands on
base, a non-empty target is the branch a resume continues. Remediate now
stages StagePrepareWorktreeOnBranch before any agent stage, binding the
same directory the daemon prepared and the task's PR branch, and failing
closed when the task has no branch rather than preparing base. The
container adapter returns the requested resume target verbatim.

Refs archie-core-h4tk
2026-10-02 12:29:57 +10:00
sam 7ca81dc85a feat(agentworker): answer MCP sampling from the task's model
A task hosts the same configured MCP servers as a chat turn, but the
worker's provider builder passed no sampling handler, so a task-scoped
server's sampling/createMessage request got a JSON-RPC method-not-found
while the identical request succeeded on the chat path. The worker runs
its own model runtime, so it can answer.

Thread a sampling handler built from the task's builder model into the
worker's MCP provider builder, beside the chat path's handler. Build the
task's model runtime once and share it with the stage runners instead of
creating a second client for sampling.

Move the sampling message mapping and max-token bound to agentexec, next
to the runtime both paths call models through, so a server gets the same
bound on either path. Carry the catalog's reasoning flag in
ModelLimits: a reasoning-class builder model must omit the max-token
bound its provider rejects, exactly as the chat path does.
2026-10-02 12:20:31 +10:00
sam 457da2e97d refactor(agent): drop the SOUL upgrade branch with no shipped template
ShippedSoul returned an empty SoulDocument.Legacy, so SoulSuperseded,
replaceSoul and SoulUpgraded had no production producer: the only body the
build ships is its current default, which classifies as SoulCurrent, and only
tests constructed a Legacy document. No earlier SOUL ever shipped (the file was
introduced with the starter in cc83c9ae), so the upgrade path has nothing to
consume.

Remove the speculative machinery and keep the behaviour that is real: seed the
starter when no file exists, recognise the shipped default as current, and
preserve every other body, including a template-shaped edit. A build that
supersedes the starter reintroduces the upgrade together with the old body it
consumes.
2026-10-02 11:59:54 +10:00
sam 656d21520f fix(webui): pin the dashboard validators to the control plane's
ui/src/settings/validation.ts hand-mirrors three control-plane validators with
no shared source, and the model-role rule had already diverged: the dashboard
required a stricter regex while the server only asks for a slash, so it refused
values the server accepts.

Add a shared fixture (internal/app/controlplane/testdata/dashboard-validators.json)
that both sides run through their real implementations: a Go test over the
server validators and ui/test/control-plane-validator-parity.test.ts over the
dashboard ones. Either side changing a rule alone now fails the other's test.

Fix the diverged rule to mirror the server's predicate exactly (non-blank role,
model containing a slash), so an empty or whitespace-padded model is judged the
same way the control plane judges it. Regenerate ui/dist and the dev-docs
artifact.
2026-10-02 11:59:17 +10:00
sam 92eabbed17 feat(telegram): carry clarify and picker through the text fallback
Telegram had no generic question or choice widget in the agent-turn path,
so the interactive contract could not be carried by the only channel that
ships. telegramInteractor implements ClarifyRequester and PickerRequester
on the shared TextFallback and reports both capabilities honestly: the
capability is about carrying the interaction, not the widget, and the cost
is a typed answer. A reply typed while a prompt is pending is consumed by
the blocked interaction rather than dispatched as a new turn; a command is
never consumed, so /stop still cancels the turn.

The carrier is set on the turn context in the Messaging process. It does
not cross the gRPC boundary into the Gateway process, so in the extracted
messaging deployment the gateway turn has no interactive adapter and
ask_user is not offered -- the same gap that already makes
WithApprovalRequester unreachable there. That transport is a product
decision recorded on the lane, not silently worked around; the in-process
path, the capability report and the tests land here.

Red-first: TestInteractivePickUsesTextFallback and
TestInteractiveClarifyReturnsTypedAnswer (plus the command guard) failed at
the assertion before the interactor was implemented.
2026-10-02 11:52:07 +10:00
sam 28acf2a8db feat(gateway): offer ask_user when the turn's channel can carry a question
prepareTurn now registers an ask_user tool only when the turn context
carries an interactive adapter (WithInteractive), so a contract with no
caller has a real one and a channel that cannot ask registers no tool
rather than one that always fails. A channel reporting Picker gets the
native single-choice request; one reporting only Clarify still carries a
choice, rendered as numbered text and matched from the typed reply through
the domain's FormatPickerText/ParsePickerReply rather than erroring.

Red-first: InteractiveTools returned nothing and
TestInteractiveToolsRegisteredWithCarrier / TestAskUserUsesPickerWhenChannelCanPick
/ TestAskUserFallsBackToTextWhenChannelCannotPick failed at the assertion
before the tool was implemented. TestTurnRegistersAskUserOnlyWithCarrier
proves reachability from a real TurnRunner turn.
2026-10-02 11:52:07 +10:00
sam c02852d87f feat(messaging): add a per-turn interactive carrier for clarify and picker
The contract could carry a question but nothing carried the ability to ask
one. Add Interactive, resolved from a channel adapter's own capability
report through InteractiveOf, with WithInteractive / InteractiveFromContext
as the per-turn carrier -- the same shape WithApprovalRequester already uses
for consent. The capability still wins over the method set, so a
mis-reporting adapter contributes nothing instead of being called.

Tests: TestInteractiveOfTrustsCapabilityReport and
TestInteractiveCarrierRoundTrip pin the resolution and the round trip.
2026-10-02 11:52:06 +10:00
sam ab86442156 feat(tools): reconcile MCP servers and tool settings live
Flip tool-settings to ApplyMode live (archie-core-zfb0.3): the daemon now
watches the kind, diffs the stored MCP server set against the running
providers -- connecting added servers, disconnecting removed ones and
reconnecting changed ones while an unchanged server keeps running -- and
rebuilds the web_fetch and minimax entries, whose config is captured at
construction. A changed server whose replacement fails to start is rolled
back to the one running, and the refusal is reported through apply status.

toolprovider.Registry grows running-state Add/Remove/Replace beside
Register, Start and Stop, isolating a provider's failure the way the plugin
host's Add/Replace do. The chat turn model resolves its tool-output policy
per turn instead of capturing it at construction, and the boot registration
reads the running holder so a stored update that lands during boot is not
lost.
2026-10-02 11:46:37 +10:00
sam bfb909a93a docs(prreview): the approval path keeps the task's workflow, it does not force implement
The PRD still described both approval surfaces requeueing under a hardcoded
implement workflow. The shipped path passes an empty workflow, which Requeue
reads as keep-the-task's, so the feasibility handoff has to name implement on
the task before the wait rather than relying on the handler.
2026-10-02 11:45:46 +10:00
sam 894fffc63b test(messaging): widen the config-read gate past explicit config.Config types
The gate that keeps a PRD-forbidden [models]/[providers] read out of the
Messaging Service only blamed identifiers whose parameter or var type spelled
config.Config. A value reached through an inferred declaration
("cfg := doc.Config") or held in a struct field therefore left the read
intact while the rule saw no holder -- the same class of miss that let voice
transcription ship behind a green link gate.

Widen the holder detection to track the config type through inferred short
variable declarations and vars, struct fields and receivers, type-preserving
expressions, and range variables over a slice or map of config, then assert
each previously-inert shape red first.
2026-10-02 11:44:51 +10:00
sam c94be59952 feat(container): apply container-runtime-policies live
The container runtime policies kind was restart-required because the pool
captured image, pull policy, network, max uptime and max concurrency at
construction and the dispatcher fixed its slot count at the start of a drain
pass. Both consumers now re-read the published config:

- the pool's settings come from a live source read per acquire, with the
  boot-resolved registry credential and Docker construction values preserved;
  a live default-image change is pulled rather than assumed present;
- the daemon owns one long-lived dispatcher that accepts a new limit: running
  tasks keep their slots, a raise admits queued work immediately, and a lower
  limit is applied as tasks finish;
- the control-plane descriptor is live, the kind joins runtimeResourceKinds,
  and the apply/reload paths resize the dispatcher after publishing. The
  ContainerConfig fields whose consumers now re-read are added to the reload
  allowlist; registry_auth stays restart-required.

Regenerate the docs artifacts. contracts.json also carries the voice
media-type description a prior commit left stale.
2026-10-02 11:39:46 +10:00
sam 04d0495f12 revert(tools): drop the checkpoint writer with no restore caller
The pre-mutation file checkpoint added in e10d862f wrote a full copy of
every write/edit target into .git/archie-checkpoints, but nothing could
restore it: CheckpointStore.RestoreLatest (and its latest/restore
helpers) had no production caller, no rollback surface reaches the
workspace, and the store was never pruned, so it grew without bound in
every workspace.

A writer whose only reader is unreachable is dead weight and an
unbounded disk cost, so the write half goes with the read half: write
and edit no longer snapshot, and CheckpointStore is deleted. The
regression test pins the decision by asserting a write and an edit
leave no .git/archie-checkpoints behind.
2026-10-02 11:36:10 +10:00
sam 9ccb6e2418 feat(messaging): restart only the channel whose settings changed
archie-core-zfb0.4. Channel settings were restart-required as a whole: a
change to one channel needed a process restart that restarted every channel.

The Messaging Service now reconciles the stored channel-settings resource on
the apply-status restamp interval (docs/prds/plugin-settings-live.md), re-layers
it over the file document exactly as boot does, and restarts only the channel
whose transport settings changed. Every other channel keeps serving.

A restart is stop-and-start, not an in-place reload: each channel gets its own
supervisor and a rebuild factory, so email and webhook -- which have no reload
seam -- are restarted too. Telegram's Start still calls dropPendingUpdates
before it long-polls, so the rule holds on the reconcile path as on /restart. A
replacement is built before the running channel is touched, so a configuration
this build cannot run leaves the running channel serving.

The composed set and the bound listen addresses are process bindings: enabling
or disabling a channel, or changing chat.webhook_addr / chat.email.listen_addr,
is refused and reported for a restart rather than applied. A channel rebuild
that fails is not recorded as applied, so it is retried on the next tick. The
applied version reaches apply status, and ChannelSettingsKind flips to live.

Files: internal/app/archiemessaging/{compose,reconcile,supervise,run}.go,
controlplane ApplyMode, archied runtime watch, configuration.md, the config
skill matrix and the regenerated dev-docs artifact.

Verified: go test ./internal/app/archiemessaging/... (race clean); go test
./cmd/archie-messaging/... ./internal/app/controlplane/... ./internal/app/archied/...
./internal/config/...; go vet and golangci-lint run on those packages (0 issues);
go fix ./... and golangci-lint fmt produced no diff; task docs:artifact:check.
2026-10-02 11:31:05 +10:00
sam cd878f3c4d fix(messaging): gate the boundary on config reads, not only package links
The deletion gate checked which packages the messaging binary links, so a
process that reads a decoded [models]/[providers] value passed while
building an LLM client in-process. Go imports are atomic, but a config
read leaves no import to measure.

- add the model-provider capability packages (transcription, embedding)
  to the banned-link table and classify links through a testable
  bannedLink rule.
- scan internal/app/archiemessaging's production sources for a read of a
  top-level config section the PRD forbids, so the projection that built
  the transcriber cannot come back.
- unit-test both rules, including a synthetic copy of the old wiring, so
  the live gate cannot rot into a no-op and still pass.

Red first: TestMessagingReadsNoBannedConfigSection failed on cfg.Models
and cfg.Providers before the capability moved, and the link gate failed on
internal/infrastructure/transcription.
2026-10-02 11:12:59 +10:00
sam b650a8c156 fix(messaging): transcribe voice notes on the model-owning side of the boundary
The Messaging Service built the voice-transcription client in-process
from [models].transcription and [providers.*], which the messaging
boundary PRD reserves to the process that owns the model runtime and its
provider credentials. The deletion gate only measured linked packages,
so the PRD violation shipped green: config reads are not imports.

Move the capability across the boundary:

- archiemessaging no longer reads [models] or [providers], builds no
  transcription client, and drops the ResolvedConfig.Transcriber field.
- telegram classifies a voice note as messaging.MediaTypeVoice and stops
  transcribing; it carries the attachment bytes and its note to the turn,
  which is all a frontend without the credential can do.
- archied builds the transcriber beside the chat runtime from its own
  model-role configuration (setupTranscriber) and gives it to every
  gateway TurnRunner.
- the turn runner transcribes a speech attachment before recording the
  inbound message, so stored history and the model context carry the
  transcript; a nil/failed/empty transcription keeps the frontend note.
- messaging.TranscribedMessageText renders the transcript into the text a
  frontend built from its media note, preserving the sender's caption.

Red first: TestTurnRunnerTranscribesSpeechOnTheModelOwningSide failed at
'Transcribe calls = 0, want 1' with the transcription call disabled.
2026-10-02 11:12:59 +10:00
sam 4241429620 feat(controlplane): add the writable review-settings resource
review.precision_gate and review.approve_before_post were file-only, so the
dashboard had no way to write them: no control-plane resource carried them.
Add the review-settings kind (docs/prds/review-settings-resource.md), seed it
from the file's [review] section, layer it field-by-field into cfg.Review,
watch it live, and publish it through ConfigView.Review. The dashboard gets a
Review settings page bound to the kind through PAGE_RESOURCES, showing each
dial beside the value in force.
2026-10-02 11:08:44 +10:00
sam cc83c9aea2 feat(agent): seed a starter SOUL and upgrade only untouched templates 2026-10-02 11:06:40 +10:00
sam 1f0cb9f318 docs(prds): name the registered step type and hold the vocabulary PRD to the provider set
docs/prds/workflow-step-vocabulary.md named the repository-rules step type
`workflow.diff-rules` while the vocabulary a deployment resolves carries
`gate.diff-rules` (workflow.DiffRulesStepName), so a definition written to
the document's word is refused at save and at run. The same decision's
sibling, docs/prds/runtime-control-plane.md, still claimed "Plugins can add
step types", which this document's closed-set rule contradicts: an
interpreted plugin contributes none, and a step type arrives as a provider
in the compiled-in set.

Correct both documents, and hold the vocabulary PRD to the provider set with
a guard test: every step-type-shaped name the document identifies must
resolve in workflowsteps.Providers(). The test fails on the pre-fix document
("workflow.diff-rules" is contributed by no provider) and passes after.

Refs: archie-core-vwqc, split from archie-core-gcoj (closed as invalidated by
re-verification: the provider set exists and cross-side agreement is already
pinned).
2026-10-02 11:05:08 +10:00
sam 19520a63e5 feat(webui): let the operator choose the retry worktree mode
A retry now carries the operator's worktree choice (refresh onto the base
branch or continue the work already pushed on the task branch) from the
dashboard through the task action to the daemon dispatch, and persists it
on the task row so it survives a reload. The daemon resolves the mode from
the task, never from the workflow; BeginRemediation records continue
explicitly so a remediation still resumes its pull request branch.
2026-10-02 10:53:21 +10:00
sam ef203ce30a fix(control-plane): unify validation for the domain-managed kinds
The control-plane catalog advertises identities, capture-events,
capture-mappings and capture-bindings as domain-managed: the domain API
validates their writes, not the generic resource store. Two of those
paths did not hold.

Identities: the file loader judged an identity name with its own
`name == ""` test, while the store derives the same string through
identity.New, whose rule rejects an empty-after-trim name. A
whitespace-only name passed the file and then failed State Store boot
(or was silently skipped by BootstrapIdentities). The loader now calls
identity.ValidDisplayName, the feature's own rule, and
BootstrapIdentities derives legacy names through
identity.FromLegacyName rather than dropping one it cannot build.

Capture mappings and bindings: mapping.Validate and binding.Validate
ran only in the archie-ui handlers, so any other client of the RPCs the
catalog names could store a mapping or binding the feature refuses.
The staterpc write handlers now apply the feature's rule before the
store, per runtime-control-plane.md ("the server validates the change,
then writes it"). The rule stays in the domain package; the handlers
only translate its refusal.

Capture-events has no file-side copy and no feature rule for a captured
event's content, so there is nothing to unify there.

Tests: identity_agreement_test.go ties the file loader's name rule to
the store constructor; domain_validation_test.go proves the mapping and
binding RPCs refuse an invalid value before it reaches the store.
2026-10-02 10:50:52 +10:00
sam ff3f80e4c1 fix(logging): file a task log record under its own event time
A remotely-shipped task log entry was re-emitted through the sink with
slog.Logger.LogAttrs, which stamps time.Now(): the entry's own event time
was discarded and replaced with the daemon's receipt time. Because a
container's records arrive in bursts, a multi-minute run collapsed onto a
few milliseconds of receipt timestamps and its timing became
unrecoverable -- which stage ran when, how long an iteration took, whether
a stage stalled.

Write now builds the record from entry.Time (falling back to receipt time
only for an entry that carries none) and dispatches it through the same
handler, preserving the sink's level gate. Receipt time stays available
separately in the record's received_at field, so event time and arrival
time cannot be confused. The agent-side producer already carried the
record's own time; a test now pins that half too.
2026-10-02 10:33:24 +10:00
sam 3da407e410 fix(archied): omit the max-token bound on reasoning-class models
The OpenAI chat-completions provider in the pinned ai-sdk serialises a
non-zero output-token bound as `max_tokens`, which reasoning-class models
reject with HTTP 400 ("Use 'max_completion_tokens' instead"). Send no bound
at all for a model the catalog marks reasoning; classic models keep their
bound. Covers the chat turn path and MCP sampling, the two call sites that
set one today.

The reasoning flag rides TurnPrepareContext from the catalog details the
gateway already resolves, so archie-core keeps one notion of "reasoning
model": messaging.ModelDetails.Reasoning. A max_completion_tokens path in
ai-sdk is still needed to ever bound these models; that is filed separately.
2026-10-02 10:25:39 +10:00
sam 4e5b91d791 fix(daemon): resume a retry whose worktree is gone
prepareWorkspace chose between Manager.Prepare (refresh onto base) and a
separate Manager.Resume, and Manager.Resume only opened an
already-prepared clone. A remediation whose local worktree the terminal
cleanup removed, an expired volume dropped, or a different host never had
could therefore never be resumed, and the retry path had no way to select
the mode that continues pushed work.

Unify the two matched methods into Prepare(..., Target): Fresh resets onto
origin/<base>, a non-empty Target resets onto origin/<that branch>, and
either target clones a missing worktree. The daemon's retry path selects
the target from the task row and passes the persisted branch, so a resume
lands on the branch the open PR lives on and fails closed when it is not
on the remote.

Delete the container-mode no-op resume (hybridTrees.Resume and the
resumableTrees capability) now that the daemon owns it. The remediate
workflow no longer stages a resume, and the retired remediate.resume step
word stays resolvable as an inert stage: a stored definition is validated
as a whole collection, so a removed word would fail every workflow to
decode, not just its own.
2026-10-02 10:24:52 +10:00
sam 12b59a046d fix(messaging): carry an inbound attachment's bytes to the gateway turn
A Telegram photo or document was dropped between the process that receives
it and the one that runs the turn. Telegram runs in archie-messaging, which
downloads the attachment; the turn runs in archie-gateway/archied, which
never holds the bot token. gatewayrpc stripped MediaAttachment.Data on the
inbound request, so by the time the Gateway's model seam ran, the
attachment had no bytes and no URL, and mediaParts dropped it -- the model
read only the "[photo]" placeholder.

- proto/gateway/v1: Media gains a `data` field, populated only on the
  inbound request. Stored-history and outbound-event directions keep it
  empty: a persisted record still strips the bytes, and a streamed media
  event still carries metadata only.
- gatewayrpc: the inbound conversion maps Data; the stored and outbound
  conversions deliberately do not.
- archied: the Gateway server raises its gRPC receive limit from the 4 MB
  default to the messaging contract's inbound attachment ceiling plus
  framing headroom, so a maximal (20 MB) attachment is accepted rather than
  failing the RPC.
- messaging: MaxInboundAttachmentBytes is the single ceiling the Telegram
  download gate and the Gateway receive limit both derive from.

Red first: a new TestInboundMediaBytesReachTheTurn asserted the bytes crossed
the wire and failed at that assertion before the mapping changed; it was then
consolidated into TestInboundMediaRoundTrip, which now pins metadata plus bytes.
2026-10-02 10:18:01 +10:00
sam af1b9855ab fix(messaging): report the daemon version this process was built from
The Telegram update-report relay verified every pending report against a
nil running-version map, so a successful update always ended with "I still
can't confirm which version is actually running" and read as a failure.

The 2026-09-19 extraction decision left RunningVersions nil because the
Messaging Service could obtain only another binary's stamp. 70ea9b2a
(archie-core-k94o) then gave every host binary, archie-messaging included,
a buildinfo.Version self-report stamped with the archied release tag, so
the process now has a truthful source for its own running version: report
daemon = buildinfo.Version and leave the agent Unverified, since every
archie-agent process is task-scoped and observed only through
daemon.AgentStatus. A relaying process that the update did not replace
still reports its old build, which Verify reads as drift.
2026-10-02 10:16:22 +10:00
sam 3e878464f9 fix(workflow): deliver the feasibility PRD to the forge issue
The deliver stage's notify() returned early when [notify].webhook was
unset, so a parked feasibility PRD left the process nowhere while both
its doc comments promised an issue comment that was never posted. A
default deployment sets no webhook: the PRD reached only the operator
who went looking.

notify now posts a one-way delivery notice on the task's forge issue
before the webhook, for a forge-backed task. The issue is the channel a
default deployment always has; the webhook remains an additional push.
Neither is a reply channel -- the decision surfaces stay chat and the
Web UI, so the notice carries the PRD and names where to decide rather
than inviting a reply, and no reply cursor is recorded (WatchCommentID
stays 0).

Both stale doc comments now describe what the code does.
2026-10-02 10:10:04 +10:00
sam 216be98652 feat(plugins): load plugin and secret-engine files without a restart
docs/prds/plugin-settings-live.md: a `plugin-settings` change now applies
live for plugin_dir, module_dir and secret_engine_dir, and a file dropped
into any of those directories loads on the reconciliation tick.

- PluginSettingsKind moves to ApplyMode "live" and joins
  runtimeResourceKinds, so a stored directory change re-layers immediately.
- A reconciler re-runs the directory loads and the layering on the
  apply-status restamp interval. Files are content-hashed, so only new and
  changed files load.
- plugin.Host grows Add and Replace for the running state (Register keeps
  its pre-Start rule), and plugin.LoadFile / secret.Registry.LoadFile are
  the single-file load paths the boot loader and the reconciler share.
- Yaegi cannot unload, so a removed file keeps running and the removal is
  reported through apply status against the live version until restart; a
  clean pass clears it.
- A plugin-settings document that changes skills_dir is refused before the
  layering, since skills_dir has no live consumer.
- applystatus.Reporter.AppliedVersion lets the reconciliation report an
  outcome without resetting the version to zero.
2026-10-02 10:01:35 +10:00
sam f77baecb00 feat(gateway): gate admin slash commands by sender policy
Add SlashAccessPolicy, a deny-by-default role policy (admin allowlist plus
per-user delegated commands), and enforce it in Router.route before any
local command dispatches. A refusal executes none of the handler, is
visible to the sender, logged, and recorded through an optional
SlashDenials sink.

No config field yet: the gatewayrpc wire drops Message.SenderID (only the
display Sender crosses), so a per-sender allowlist cannot match a Telegram
sender at the daemon Router until the layered auth mixin carries identity
(archie-core-263). Nil policy preserves today's behaviour.
2026-10-02 10:00:37 +10:00
sam 394c76b4cc feat(messaging): adapter-facing clarify, picker and approval contract
The optional-capability pattern had media and delete but no interactive
UX: a channel could ask a human to approve an action through
ApprovalRequester, but there was no domain contract for posing a
clarifying question or presenting a single-choice picker, and no
capability flag a caller could read before attempting one.

Add ClarifyRequester and PickerRequester to internal/domain/messaging
alongside ApprovalRequester, with Clarify/Picker/Approval flags on
AdapterCapabilities and ClarifierOf/PickerOf/ApproverOf lookups that
treat the capability as the contract rather than the method set, so a
mis-reporting adapter degrades instead of panicking.

TextFallback is the shared text degrade: a channel with no native
question or selection UI still carries the interaction (numbered
prompt, parsed reply) instead of failing or silently dropping it.
FormatClarifyText/FormatPickerText/ParsePickerReply hold the rendering
and matching logic once.

The approval half reuses the existing decision model: Telegram's
telegramApprover already renders a native prompt, so it now reports the
Approval capability and deliberately does not claim Clarify/Picker it
has no native UI for. Gateway re-exports the contract.

Red-first: internal/domain/messaging/interactive_test.go drives the
test double adapters (native, degrade, mis-reporting, over-claiming)
and the text rendering/parsing; telegram/approval_test.go pins the
honest capability report.
2026-10-02 09:57:44 +10:00
sam b6defc5f31 fix(workflow): park environment gate failures without dispatching a builder
The baseline stage treated every red gate as a pre-existing code defect and
dispatched a TDD repair agent. A failure the environment caused -- no Docker
daemon for the test harness, or a gate command that is not installed -- cannot
be fixed from the worktree, so the run spent a full agent budget and then
parked. A provider error during that repair run (observed: HTTP 402) replaced
the gate cause in the park reason entirely.

Classify at the producer: gateEnvironmentCause names a failure whose command
could not start (*exec.Error) or whose output names unavailable host
infrastructure (the Docker shapes from archie-core-71mq). That failure parks
with the cause and the gate output and starts no builder. A real code failure
still dispatches exactly one repair run, and every post-dispatch failure now
carries the gate output alongside the agent/provider error instead of masking
it.

Refs archie-core-rwy6.
2026-10-02 09:57:15 +10:00
sam 5e1623f82f feat(webui): the harness settings page and its setup terminal
A Settings > Runtime page lists every credential binding with the capture
state of its OAuth token set (expiry, scopes, time; never the tokens), and
offers the setup terminal for the Kit profiles the daemon advertises. The
terminal is xterm.js over the WebSocket the harness route upgrades, lazy
loaded so xterm stays out of the shell bundle. The page reports the
terminal as unavailable when the process cannot open one, rather than
offering a control that fails (archie-core-egkf.7).

Wire shapes and URL building live in ui/src/harness/harness.ts and are
covered by ui/test/harness.test.ts; ui/dist is regenerated.
2026-10-02 09:42:26 +10:00
sam 0544fa58fc feat(gateway): list the harness page in the dashboard page registry
internal/gateway/dashboard_tools.go mirrors the dashboard's route table so
the agent can navigate to every page. The new /settings/harness route needs
its entry or page_index would not offer it (archie-core-egkf.7).
2026-10-02 09:38:09 +10:00
sam 057a4a8614 feat(webui): the dashboard reads harness bindings and opens the setup terminal
The harness page lists each credential binding with its captured OAuth
state (expiry, scopes, capture time; never the tokens), and the setup
terminal route upgrades to a WebSocket and bridges it to a harness
session. The session is a narrow webui-owned HarnessTerminal seam: the
container, sandbox network and egress path belong to the daemon, so the
dashboard process cannot implement it and answers 503 until a transport
is wired (archie-core-egkf.7). Opening the terminal authorizes as the
update action on the secret, per the PRD.
2026-10-02 09:38:09 +10:00
sam 2a1ed36a26 feat(webui): a live-apply setting reads as applied, never as a restart
The per-process apply rows labelled every older applied version "Restart
pending", including a live-apply kind that needs no restart at all: the lag is
in reporting. The wording now follows the resource's apply mode. A live kind
reads "Applied" at the stored version and "Behind" on an older one, neutrally
rather than as a warning, while a restart-required kind keeps "Restart
pending".

The restart banner's condition is lifted out of the component into a plain
module so it can be tested: only a restart-required resource with a process on
an older version earns the banner, and a live-apply kind never does. The
per-process rows are wired onto the Plugins page, where a live kind's lag is
meant to show.
2026-10-02 09:37:44 +10:00
sam 605988e0a9 fix(egress): take a run's credential kind from its binding, not the Kit
The sandbox kit spec lets one credential@1 declare apiKey and oauth
together, meaning "whichever the host has bound": the published
docker/claude-code-kit does exactly that for anthropic, and codex for
openai. archie decided the kind from the Kit's declaration instead
(egress.IsOAuthManaged), so a dual-declared service always came out
OAuth-bound however the org had bound it:

  - kitrun.resolveCredentials granted an API-key binding's service the
    empty string, so the proxy had no key to inject and every request to
    a domain the Kit named carried an empty credential. The reference
    Claude Code Kit could not authenticate with an API key at all.
  - an API-key-only service whose binding named no secret resolved to ""
    through the zero SecretRef, presenting an empty credential rather than
    staying unbound.
  - the proxy fired an apiKey inject rule for an OAuth-bound service,
    putting "Bearer " on the wire, and intercepted the token endpoint of
    an API-key-bound one, whose only outcomes were a 502 on the missing
    token set, a capture the org never bound, or -- for a required
    dual-declared credential -- a refused launch when no token store was
    configured.
  - the container's SBX_CRED_*_MODE said "apikey" for an OAuth-bound
    dual-declared service, and kitrun demanded a captured OAuth token for
    an API-key-bound one whose Kit renders a credential file.

One root cause, fixed once: the org's binding decides the kind. It is
now a first-class fact (egress.CredentialKind: apikey or oauth, absent
meaning unbound), computed from the binding in resolveCredentials and
carried to every consumer of it -- the resolver grant, the container's
credential state (mode variable and credential file), and the proxy
session, whose rule sets are built from it so a rule can only fire for a
service the run carries as that same kind. A service the run does not
carry at all keeps both rule sets, so resolving it still refuses a
required credential and skips an optional one.

Declared and bound stay two independent facts, as the reported
declared-and-granted intersection requires: neither widens the other.
No secret value crosses into kit (Bound carries kinds only) and none is
logged or written to a task row.
2026-10-02 09:37:20 +10:00
sam 06e0a87a62 feat(messaging): transcribe Telegram voice notes
A Telegram voice note was stored as the placeholder "[voice message]" and
nothing turned its audio into text, so the agent could not read it. Add a
channel-neutral Transcriber capability to the messaging media layer
(internal/domain/messaging), an ai-sdk Whisper implementation behind it
(internal/infrastructure/transcription), and wire it for Telegram.

The capability is config-driven like the other model roles:
models.transcription names a provider/model, the matching [providers.*]
entry carries the credential (api_key_env or an api_key secret ref), and
a missing role, provider, class or credential degrades to today's
behaviour with a log -- never an error that fails the turn.

A transcribed note replaces its placeholder with "[voice transcription]"
followed by the transcript, preserving any caption, so stored history
shows the agent it is reading a machine transcript.
2026-10-02 09:36:48 +10:00
sam 1d2fcec69e feat(messaging): retract ephemeral replies after their TTL
An EphemeralReply is a status notice a channel delivers and then removes
once its TTL elapses, so a transient placeholder does not linger in the
chat history after it is superseded. The TTL lives on the reply, the
Delete capability joins AdapterCapabilities alongside Media, and
channels.EphemeralSender does the send-then-retract with an injected
clock. A sender that cannot delete still delivers the reply and logs the
missed retraction instead of failing the turn.

Telegram implements MessageDeleter through deleteMessage and honours the
mechanism for the "Archie reloaded." status notice; the pre-restart
"Reloading…" message remains the durable acknowledgement.
2026-10-02 09:36:16 +10:00
sam f5fbec6371 feat(container): send registry auth on image pull
ImagePull was called with empty options, so a private registry answered 401
on every pull regardless of containers.pull_policy. docker login did not help
either: it writes ~/.docker/config.json, which only the CLI reads.

Add containers.registry_auth, a SecretRef reusing the credential shape the
rest of the file uses, whose resolved value is a Docker registry.AuthConfig
JSON document. archied resolves it at boot and the pool base64url-encodes it
into the X-Registry-Auth header ImagePullOptions carries.

A missing or unresolvable credential degrades to the anonymous pull that
existed before the field (with a warning), so a deployment with no private
registry is unaffected; a half-named reference is refused by
configuration.Validate. The field is file-owned and json:"-", so the
container-runtime-policies layering has to preserve it explicitly, the way it
preserves Profiles.
2026-10-02 09:35:28 +10:00
sam a9f441042e style(mcp): apply go fix to the sampling transport 2026-10-02 09:35:21 +10:00
sam a8a04929af feat(mcp): answer server-initiated sampling from the chat model
MCP servers could not ask the client for a completion: the transports
routed only responses by id and dropped every server-initiated request,
so a server calling sampling/createMessage hung waiting for a reply.

Route server->client requests through the transport readers to a handler
on the client. The client answers sampling/createMessage from a
configured SamplingHandler and maps a missing handler, malformed params
and handler failure to JSON-RPC errors for that request alone -- never a
silent drop or a failed session. stdio and SSE implement the routing;
the stateless HTTP transport cannot receive the request at all and says
so in its doc.

The daemon wires the handler to its own chat runtime and active model
role, so a sample is answered by the model a chat turn uses, capped by
the request's maxTokens and the model's output ceiling, and recorded on
/status like every other model call. No model configured is a refused
request with a clear error.
2026-10-02 09:33:32 +10:00
sam 1e1f51af55 feat(archied): refresh the model catalog at runtime
modelcatalog.Load ran once at boot, so a provider whose credential became
resolvable later, or a model models.dev published since, needed a restart.
The daemon now re-reads the catalog on an interval and republishes everything
derived from it, without a restart.

- `refreshModelCatalog` re-reads through the same options boot used, layers
  the result with the process's own runtimeConfig, and publishes. A failed
  read keeps the catalog already running: the model list must not go blank
  because the catalog service had a bad minute.
- Boot now publishes the merged config into `config.Holder`. applyModelCatalog
  only ever wrote into the boot struct, so the catalog's model limits and
  discovered providers never reached the running config -- and therefore never
  reached `config.ForTask`, which is what a workflow stage resolves model
  limits from. The first live update was the first snapshot to carry them.
- The chat model manager's catalog is a contribution that is replaced, not
  merged. A model the catalog no longer publishes stops being offered and
  described instead of lingering from an earlier snapshot.
- The catalog snapshot and the refs it contributes live behind one lock: the
  refresh goroutine replaces them while the config paths read them.

The daemon owns the published configuration, so the loop is the daemon's; the
standalone Gateway reads the catalog once at boot, as it does for the other
live-applied settings it does not watch.

The interval is deliberately not an operator setting: the catalog is derived
state rather than a stored resource, and a knob with no second consumer would
be a setting that parses and does nothing.

A key exported into the shell after the process started stays invisible to
every refresh, and cannot be otherwise: the process environment is fixed at
exec. A credential a secret engine starts resolving is visible, because the
catalog's credential lookup is the secrets registry.

Refs archie-core-zfb0.6
2026-10-02 09:24:32 +10:00
sam 3c2b1f6654 fix(storepkg): validate every declared authority grant at the package descriptor
Descriptor.Validate duplicated only the forge-permission half of
Authority.Validate, so a descriptor could declare a blank credential
service, egress host, trigger or tool and be installed: the acceptance
record refused the same blank, leaving the descriptor the operator is
shown disagreeing with the record the package is bounded by. Delegate to
Authority.Validate, the one validation of a grant list, and cover it with
the blank cases the descriptor now has to refuse.
2026-10-02 09:20:49 +10:00
sam e10d862f6a feat(tools): checkpoint files before mutating write and edit
The built-in workspace write and edit tools replaced file content with
no recoverable pre-state. Each now snapshots its target immediately
before the write and refuses the mutation when the snapshot cannot be
taken, so a checkpoint is never silently skipped.

Checkpoints land in .git/archie-checkpoints inside the workspace, the
same per-task state directory that already holds the task brief and the
prepared sentinel: nothing under .git can be swept onto the task branch
by go-git's Add{All:true}. A checkpoint records either the file's bytes
or its absence, so creating a file restores by removing it;
RestoreLatest returns the most recent pre-state for a path.

Shell, Go-script, MCP and plugin tools are deliberately not covered:
the set of files they can touch is not enumerable from the call.
2026-10-02 09:18:47 +10:00
sam 721968eeff fix(workflow): derive a declared output's captures need for profile selection
A declared output is written through a capture tool, but the dispatch-time
harness check read only the workflow's needs.captures. A workflow that
declared outputs without also writing needs: {captures: true} could name a
Kit profile whose adapter serves no capture tools; a required output then
parked with "output %q is required" instead of the profile being refused.

WorkflowInterface.Needs now reports captures for a non-empty Outputs beside
the declared needs, and the profile check and Kit launcher read it. The
needs: block keeps its meaning for a workflow that captures without
declaring outputs.

- internal/domain/workflow/task: Needs() derives captures; DeclaredNeeds
  carries only the declared block.
- internal/daemon: pinTaskProfile and runKitTask read Needs().
- tests: parse-time derivation, and pinTaskProfile refusing an
  outputs-declaring workflow against a Kit adapter with no capture MCP.
2026-10-02 03:19:07 +10:00
sam 446d94681b feat(webui): block invalid settings and show a field's former value
The Settings save flow tracked dirty fields but did not consult validity:
each page validated in a local computed the save bar could not see, so an
invalid draft could be saved and the server refused it a round-trip later.
The rules now live once in ui/src/settings/validation.ts, the store derives
invalidFields from the same draft diff as dirtyKinds, and the save bar lists
the invalid fields and refuses Save. The route-leave guard still reads the
one dirty model, so the two can never disagree.

Every edited field also shows its former value inline ("was 1m0s") from the
same per-kind diff, via a new DraftHint component.

The per-kind diff is now a cached computed, so the hint, the save bar and
the guard share one computation per change instead of one per consumer.
2026-10-02 03:14:46 +10:00
sam 04dedde52c feat(daemon): resolve the producing identity's org before publishing work
The poller, the forge webhook intake and the review scan built envelopes
without an Org, so every task and reaction keyed on the default org no
matter which org its identity served. Resolve the org through the State
Store's PrincipalSource (the existing org RPC over the staterpc client)
on the single publish paths:

- PublishTask stamps the envelope's identity org before encoding, so the
  idempotency key is org/identity/owner/repo/number; a resolve failure
  stops the publish instead of keying under a guess.
- PublishReaction is the one reaction write path, stamping the root org
  when the webhook producer could not; the poll scan stamps its task's
  already-resolved org, so both deliveries of one review key the same.
- The webhook receiver's inline publish closure moves onto the daemon
  method, removing the second reaction write path.
2026-10-02 03:12:42 +10:00
sam a4abafe0ad docs(prds): decide the plugin live-reload open questions
Review of the plugin-settings reconcile PRD (F1-F8) returned REVISE: the doc
stated outcomes without making the decisions behind them. This revision makes
each one, so the PRD can carry the plugin live-reload work:

- ApplyMode is set to live and the gateway's version lag moves from the
  restart banner to the per-process applied-version rows.
- The skills_dir refusal gets a check site (a pre-layer comparison on the live
  path, not the value-agnostic validator), keeping #1143's validates-nothing
  intact.
- Records the four-directory coupling and why a whole-document refusal is
  acceptable.
- Justifies stop-then-start as a module's only check, and adds the refused
  dependent-replace outcome to the apply-status taxonomy.
- States that a reconcile tick re-runs layering and provider resolution, and
  what archie-gateway actually boots.
- Adds the Verification section.

Cited package paths re-checked against the tree; the control-plane
definitions now cite internal/app/controlplane/.
2026-10-02 03:10:18 +10:00
sam 6bf24d73db test(agentexec): make seeded git repos independent of host signing config
The temp-repo fixtures in agentexec, domain/workflow and agentworker seeded
a repository and committed without disabling gpg signing, so a host with
commit.gpgsign=true and an agent-only SSH signing key failed those tests at
the fixture's own git call ("Couldn't get agent socket?").

Each producer now writes commit.gpgsign=false into the temporary repository's
own config, which also covers commits made inside the seeded repo by a
subprocess (the fake harness). A regression test per package pins the
fixture's hermeticity under a hostile global git config.
2026-10-02 03:06:48 +10:00
sam 20b4595a95 style(postgres): apply the formatter to the rebased review-gate row mapping 2026-10-02 02:30:16 +10:00
sam 2341c6df36 style(taskactions): apply go fix to the gate response test
The modernizer promotes the embedded fakeStore's fields into the literal;
task fmt runs go fix, so the lane gate flags the pre-fix form.
2026-10-02 02:27:59 +10:00
sam eaabc254be feat(webui): the dashboard answers the review gate, including a re-review's instructions
The server offers re-review for a waiting task, and it refuses one
without instructions, so the control needs a dialog of its own rather
than the plain confirm: it collects the operator's focus and posts
api.taskAction(id, "rereview", {instructions}). taskAction now takes the
review-gate payload (instructions and the finding keys approve posts, an
absent selection meaning all), and the freeze-dried catalog gains
Re-review so the first render matches the served catalog. The rereview
event kinds join the live-update topic list.

ui/dist is regenerated and committed; task test:ui and the typecheck pass.
2026-10-02 02:27:59 +10:00
sam 68a17aed91 feat(taskactions): one approval path answers the review gate from every surface
Decision 1 of docs/prds/pr-review-operator-response.md: the dashboard's
POST /api/tasks/{id}/action is the authoritative surface, chat's /approve
is a shortcut that posts every offered finding, and both reach the same
Service.Apply so one operator intent cannot be recorded as two decisions.

The action body now carries instructions (required by rereview) and the
finding keys an approve posts. taskactions.Service answers an offer
through the guarded RespondReviewGate write: approve records the
selection on the offer, rereview records the instructions, increments the
round and clears the offer, and a rereview with no instructions, with no
offer, or at the cap is refused as a conflict with nothing written. Chat
reaches the same service: chatTaskControllerAdapter.ApproveChatTask
delegates to b.taskActions() instead of its own requeue, which is what
removed the handler's hardcoded implement handoff -- feasibility's deliver
stage now names implement on the task before it waits, the invariant the
handler needs.

The payload crosses every hop it must: the NATS action request, the
gateway.v1 gRPC contract (regenerated), the LocalChatAdapter, and the
webui handler, which answers 400 for a rereview without instructions and
409 for the cap. A rereview event kind names its actor the way the
approval and rejection trios do.

taskactions.Task gains review_gate and rereview_rounds, and the two
surfaces' tests assert they agree.
2026-10-02 02:27:59 +10:00
sam 4f01b1604d feat(prreview): the gate records the review it holds and posts the operator's answer
The gate now writes its offer to the task's review_gate document before it
waits -- the scored findings, the head SHA, the pull request's identity
and the resuming workflow -- because the engine cannot resume a run
partway, so a resumed pipeline recomputes its findings and only the
recorded document is the review the operator saw
(docs/prds/pr-review-operator-response.md, "The review the operator
answers").

The document lives with the task column it encodes (internal/domain/
workflow/task), the way EncodeInputs does, and carries each finding as
opaque JSON beside the key an operator's selection names. That is what
lets the dashboard render and answer a gate without linking the workflow
engine -- cmd/archie-ui/architecture_test.go measures the linked binary,
and an operator-domain service importing the finding's own type linked
prreview into archie-ui. prreview owns the key derivation and the
finding's encoding, and the MaxRereviewRounds constant lives in the task
vocabulary beside the action names it answers with.

Intake restores the document into the run: a re-review's instructions
ride one labelled block in runLens's and runReviewer's missions only, and
an approve's recorded review is posted by phase 9 filtered by the
operator's selection, with the recomputed findings kept out of the output.
The gate does not wait again on an answered approve.

taskstate gains the rereview action the vocabulary needs -- offered for
waiting_human beside approve and reject, routed to queued -- whose
surfaces follow in the response channel.
2026-10-02 02:27:59 +10:00
sam bea1c69210 feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
The operator-approval gate needs its conversation with the operator
persisted before it waits and its answer threaded back
(docs/prds/pr-review-operator-response.md, Decision 2). review_gate is a
text column beside review_payload, encoded by the package that owns the
type; rereview_rounds is a bigint counted only by the new guarded write.

RespondReviewGate is the one write beside RetryTask/BeginRemediation: a
transition-table guard, one from-status check, an optional round
increment, and a requeue in one transaction. The re-review cap is
enforced in the row under the guard's lock, and a refusal leaves the
task waiting and the row untouched, surfaced as ErrRereviewCapReached
(added to the wire error table and the conformance battery). The column
joins the column-listing ListTaskSummaries projection and UpdateTask, so
the dashboard reads the offer and the store round-trips the count.
2026-10-02 02:27:59 +10:00
sam 7f51f1c39e feat(prreview): the operator-approval gate is PRReview's own stage-list entry
prReviewDecisionStages loses the withOperatorApproval flag: the shared
list the implement workflow splices (archie-core-afbk.7) never carries
the gate, and the standalone pipeline inserts it itself, immediately
before its merge gate (docs/prds/pr-review-operator-response.md, "The
gate is not reachable from archie's own PRs"). A structural test pins
both directions so a future edit cannot re-share the gate.
2026-10-02 02:27:30 +10:00
sam 3c32b63066 feat(workflow): declared workflow outputs for wait:true callers
A workflow declares named, typed outputs beside its inputs
(task.WorkflowInterface.Outputs). A run writes each one once through a
capture tool named after the output, or from a deterministic Go stage via
TaskContext.WriteOutput; the finish write persists them on tasks.outputs
before the outcome transition. A wait:true caller receives its successful
callee's outputs through WorkflowCallStatus and publishes one as its own
through a call step's outputs assignment.

Build authority: docs/prds/workflow-call-outputs.md.

- save time: WorkflowInterface.Validate checks output names and types;
  checkCallOutputs checks a call's assignment against both declarations
  and refuses outputs over a wait:false call.
- run time: undeclared, mistyped and required-but-missing values park the
  run; published callee values are re-checked against the caller's type.
- storage/wire: tasks.outputs (goose 0024), reset by each claim so the set
  is attempt-scoped; an encoded set past the structured-payload bound is
  refused, not clipped. Task.outputs_json and
  WorkflowCallStatusResponse.outputs_json carry it; task.Caller keeps its
  two methods.
- examples: firewall-contain calls firewall-investigate and publishes its
  summary as its own output.
2026-10-02 02:09:03 +10:00
sam 829fc44cbc chore(release): v1.45.0 2026-09-30 11:44:01 +10:00
sam 6b4049c9f5 Merge branch 'pi-subagents/ht-writer-Repo-work-apps-archie-core.-You-are-the-ONE-writer-for-ui-in-an-isolated-work-fa09caee-88c919c-8f2c-s0-t0' 2026-09-30 11:42:28 +10:00
sam 934ba16c72 Merge branch 'crew/pi-1154' 2026-09-30 11:41:51 +10:00
sam 9f1dc44673 feat(webui): events counts, YAML reading, log rows and dashboard filters
Four findings from the ui-redesign verification pass, each with the module that
owns the rule and the test that pins it.

- events: the three-step strip's and the tab chips' counts move out of the SFC
  into events/counts.ts -- one read per step, an unreadable count stays blank
  rather than reading as zero (events-counts.test.ts).
- workflows: workflows/workflow-yaml.ts reads the editor's YAML with a real
  parser (the yaml package, not a line scanner) to drive the read-only Steps
  preview and a live validity indicator; the editor gains a line-number gutter
  and light syntax colouring behind the textarea. Step types and their settings
  are not served to the dashboard, so those remain the server's to check on
  save, and a save it refuses still reports its own reason.
- tasks: an ERROR log row is a block rather than only red text (lib/log.ts), the
  log pane ends with "End of attempt N - M lines", and the task head offers
  Archive when the server's own action list offers it (task-actions.ts, and
  TaskRowActions' new `only` narrows the list without inventing a control).
- dashboard: the live activity feed gains the All/Tasks/System filter
  (activity-filter.ts) and every quality-gate row gains a pass bar
  (pass-bar.ts) that is red when the gate is failing.

ui/dist regenerated; ui/package.json carries yaml ^2.9.1.
2026-09-30 11:41:33 +10:00
sam 24258e215f docs(prds): plugin settings reconcile live without a restart
Direction for GH #1154 (epic #998): reconcile the plugin, module and
secret-engine directories into the running registries, load new and
changed files, and surface only the removals through apply status.
Draft pending maintainer approval - not settled design, so no diff.
2026-09-30 11:41:11 +10:00
sam 793eec6e51 Merge branch 'pi-subagents/webui-1152-142b744-4aae-s0-t0' 2026-09-30 11:39:42 +10:00
sam 6785750729 Merge branch 'pi-subagents/gate-1160-8a4f132-d61b-s0-t0' 2026-09-30 11:39:42 +10:00
sam 72fa043f47 docs(development): task check writes no module file on a consistent tree
The index page warned that task check adds linter-tool lines to go.sum
(bead 1e37) and told contributors to restore the file before committing.
Measured at HEAD 275d3370 on a copy of go.sum, with the originals restored
after every step, that is not what the gate does: go fix ./..., golangci-lint
fmt, go vet ./..., golangci-lint run ./... (root and tools), go build ./cmd/...,
go test -short ./..., the docsgen and docsite checks and
go -C tools test -mod=readonly ./... left go.mod, go.sum, tools/go.mod and
tools/go.sum byte-identical, with GOFLAGS unset and again with
GOFLAGS=-mod=mod. golangci-lint cannot write its own lines into go.sum either:
it is in no require or tool directive, go mod tidy -diff is empty, and the
committed go.sum carries none of its dependencies.

What the page should say is the rule the measurements show. A stale go.mod or
go.sum fails the gate (missing go.sum entry, updates to go.mod needed) instead
of being repaired, because every Go step runs under the toolchain's readonly
default and the tools steps pass -mod=readonly. Only a global
GOFLAGS=-mod=mod in go env re-enables the repair, which is why the flag is
spelled out on the go -C tools steps; when go.sum does go dirty, go mod tidy
and its own commit are the fix.

The regenerated docs/data/generated/dev-docs.json rides along, as the page
requires: docsite check failed on the edited page first (stale dev-docs.json)
and passes after task docs:artifact.
2026-09-30 11:38:57 +10:00
sam cc7397787b fix(webui): drop the config schema's editability advert
No process writes configuration through the dashboard: the write
handlers, their UpdateConfig/ResetConfig/UpdateRepoField seams and
ConfigView.Editable were deleted with the runtime config overlay
(295f8d69), and database-backed settings are written through the control
plane. That left producer-side residue behind:

- ConfigField.Editable and the descriptor literals setting it, which
  emitted editable=true for fields no process can change, and which
  ui/src/settings/types.ts's ConfigField deliberately omits from the
  reader side of the wire shape
- ErrConfigUpdateUnavailable/ErrConfigUpdateInvalid, with neither a
  producer nor a consumer since handleConfigUpdate was deleted
- comments pointing at handleConfigUpdate/UpdateConfig,
  ConfigView.Editable, the overlay's overridden markers and a deleted
  test name

The two Editable-only descriptor tests go with the field; the deleted
write path is what they pinned.
2026-09-30 11:38:44 +10:00
sam cef476aca3 docs(controlplane): record the plugin-settings dirs as deliberately free-form
Closes the decision #1143 asked for. plugin_dir, module_dir, secret_engine_dir
and skills_dir keep their no-op validator, and the comment at that validator
now says so on purpose, with the two rules considered and refused:

- "must exist": all four consumers read a missing directory as an empty one by
  design (plugin.LoadDir and secret.Registry.LoadDir return no entries and no
  error on os.IsNotExist, loadModules skips an absent kind file, playbook.Load
  returns an empty store, and internal/secret's TestLoadDirNonexistent pins the
  no-error half), so the rule would turn deliberate emptiness into a failed
  startup.
- "must be absolute" / "skills_dir under plugin_dir": no directory setting in
  the repository is validated for shape, so a rule for these four alone is
  arbitrary, and a boot-path validator over a stored document fails closed on
  values the store already holds.

Deliberately no code change to either layer: configuration.validateDatabaseOwned
still has no say over the four, and the resource validator stays the single
no-op function with one obvious home for a rule.

Refs #1143
2026-09-30 11:37:19 +10:00
sam f50444594f fix(config): expand plugin, module and skills dirs like every other operator path
applyGeneralDefaults home-expanded secret_engine_dir, work_dir, state_dir and
chat.workspace but not plugin_dir, module_dir or skills_dir, while
config.example.toml tells operators to write all four as
~/.local/share/archie/<dir>. A literal "~" is not a directory: plugin.LoadDir
returns an empty set for it, loadModules finds no kind file, and skill
discovery falls back to the built-ins, all without an error naming the
mistake. Expand the three in the same place as the rest, so a value the
example advertises resolves to the directory the operator meant.

Test first: TestLoadExpandsConfiguredHomePaths gains the three fields (and
pins HOME to a temp dir instead of the runner's real one); it failed on the
three new assertions before this change.

No validator is added alongside: see the plugin-settings decision record for
why these four directories stay free-form.

Refs #1143
2026-09-30 11:37:00 +10:00
sam 275d337032 refactor(archied): move the sd_notify client to internal/sdnotify
The sd_notify(3) client lived in internal/app/archied, so archie-messaging --
a process that must not import archied's composition -- could never announce
itself to systemd, and could therefore never be a Type=notify unit
(archie-core-g5g8).

The protocol client and the heartbeat sampler move to internal/sdnotify, a
cross-cutting leaf that imports nothing of ours. What stays in archied is
what is the daemon's own: which marker counts as progress (daemon.LastPollAt)
and how long the run loop may go between poll passes. The three entry points
that already announced keep announcing, unchanged.

The Messaging Service announces READY=1 at the point it declares itself
serving, the way the daemon, the Gateway and the State Store already do. No
unit is switched to Type=notify here: that is a separate decision, and
archie-messaging.service is still Type=simple.
2026-09-30 11:23:33 +10:00
sam b314470281 docs(fleet): a docs page change needs the dev-docs artifact regenerated
The skill already told a lane that a wire-type change needs `task docs:generate`;
this names the other trigger for the same generated artifact. Adding or editing a
page under docs/ gains or drops a page in docs/data/generated/dev-docs.json, and
skipping the regeneration fails docs:artifact:check on main rather than in the
lane that caused it.
2026-09-30 09:04:20 +10:00
sam eb3add5b89 chore(docs): regenerate the dev-docs artifact for the SOUL PRD page
fcc6a797 added docs/prds/soul.md but did not regenerate
docs/data/generated/dev-docs.json, which is generated from the docs tree and
gained a 95th page (/dev/prds/soul/). main therefore fails the gate's
docs:artifact:check. Regenerated with the command the check itself names.
2026-09-30 08:59:44 +10:00
sam c126d5a24a refactor(gateway): delete the dead RouteStream entry point 2026-09-30 08:57:32 +10:00
sam 1a3e79502d docs(fleet): carry peer-session, gate-order and codegraph facts in the fleet skill
The fleet skill is normative for archie facts and the fleet can read it, so
three facts earned this session move here from one operator's private memory:

- Peer sessions over intercom: name the reporting channel in the brief, because
  a compaction erases an agent's transport convention while keeping its task
  state, so a peer can revert to addressing its operator. Peer silence is not
  evidence of death; ask for an ack. Also: match task shape to window size, and
  checkpoint at ~70% rather than compacting mid-task.
- Gate the merge candidate before main moves, and have the lane brief demand
  scoped lint beside scoped tests.
- codegraph: read interface_dispatch and inferred tests alongside test_count,
  treat the index as a derived cache, stagger name-based queries, and report
  problems as one JSON object per line.
2026-09-30 08:50:54 +10:00
sam fcc6a7974e docs(prds): draft SOUL, the per-identity chat personality 2026-09-30 08:37:48 +10:00
sam f4ed542b00 refactor(gateway): extract the streamed-turn prelude and pump from stream 2026-09-30 08:34:30 +10:00
sam d06be5ca32 feat(gateway): coalesce rapid-fire text events into one turn 2026-09-30 08:26:27 +10:00
sam 8d48a08b13 merge: project installed package workflow contributions live, both ways (em7s.9) 2026-09-30 08:06:43 +10:00
sam f6ee43bf55 feat(store): project installed package contributions into org resources
An install that stayed in installed_packages left every contribution
unprojected: nothing made a package's workflow a usable org resource, and
nothing stopped it on removal. This lands projection for the workflow family,
the one kind whose org resource, validation and live read path all exist:

- storepkg.Service gains Projections (family -> projector): install resolves
  each projected family's contributed names against the fetched
  layer (FilesFromLayer), applies them, and on failure withdraws and removes
  the half installation; remove withdraws before the record goes, so a failed
  withdrawal keeps the package installed and usable.
- controlplane.WorkflowProjector merges the package's entries into the org's
  workflow-definitions document — the same document the daemon's
  WorkflowDefinitions client reads per dispatch, so a projected workflow is
  usable at the next dispatch and a withdrawn one stops dispatching, without
  restarts. A contributed id displacing an operator's own workflow is refused
  (storepkg.ErrContributionCollision), never silently replaced.
- installed_package_contributions (migration 0023) records the entries a
  package projected, so removal takes exactly its own contributions out.
- stateStoreDeps wires the projector set on the State Store's pool; the
  composition is pinned by the live round-trip test over a real gRPC
  connection.

Prompts, skills, MCP server definitions and default settings remain
unprojected: their contribution formats are not settled by docs/prds/store.md
and are left for their own slices rather than half-wired here.
2026-09-30 08:05:22 +10:00
sam 268f99051a merge: render the OAuth scopes and omit an uncaptured primary key (egkf.14) 2026-09-30 08:00:08 +10:00
sam 60a09e7def feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
{{.Scopes}} now substitutes the captured set as an ARRAY in the target
encoding, so a one-element set stays a one-element array rather than
collapsing to a bare string. An empty set REFUSES by name with an
actionable "re-run the setup terminal" message: the spec declares an
omission case for {{.PrimaryApiKey}} but none for {{.Scopes}}, and an empty
array would silently change the CLI's capability decisions.

{{.PrimaryApiKey}} now implements the spec's omit case: its enclosing key is
dropped from the structure, never emptied. archie resolves a service key
only to fill the egress grant and the container holds egress.Sentinel, so
there is never a key to render.

The renderer's input becomes OAuthFacts{Scopes, ExpiresAt} -- still the only
thing it receives about a stored token set, so a real access or refresh
token cannot reach the file and an unsourceable placeholder still refuses by
name (docs/prds/external-agent-harness.md, Verification).
2026-09-30 07:59:05 +10:00
sam bf1dc2e33e docs(prds): the step-type vocabulary PRD awaits the maintainer's approval 2026-09-30 07:56:52 +10:00
sam f34714ea07 merge: decide the workflow step-type vocabulary (m7oc, ze7y) 2026-09-30 07:56:10 +10:00
sam c2cfba1129 docs(prds): decide how step types are named, agreed, and refused 2026-09-30 07:55:34 +10:00
sam cea8bfee98 merge: state the resource idempotency key and the approval gate's scope (ut6b) 2026-09-30 07:55:25 +10:00
sam 2f8107d5ca style(gateway): adopt the formatter's output for the dedup tests 2026-09-30 07:55:25 +10:00
sam a67a142139 docs(prds): state the resource idempotency key and the approval gate's scope 2026-09-30 07:54:05 +10:00
sam 48416af5bc merge: capture the OAuth scope set and carry it to the harness secret (egkf.15) 2026-09-30 07:53:18 +10:00
sam cca80ac2e8 feat(egress): capture the OAuth scope set and carry it to the harness secret
A Kit's credentialFile cannot render {{.Scopes}} because nothing records the
granted scopes: the token response's `scope` field (RFC 6749 section 5.1,
space-delimited) was never read, and the token set had nowhere to hold it.

capture now parses `scope` into []string and keeps the previous set when the
field is absent or empty -- the same rule the refresh token follows, so a
refresh that does not repeat the scopes preserves what the login captured.

The set is carried end to end: Scopes on harnesssecret.Secret, in
harnessSecretPayload (JSON inside the existing encrypted envelope, so no
migration), on message HarnessSecret as `repeated string scopes = 8`, and
both ways through staterpc values.go. The proto field is load-bearing: the
daemon reads the token set over gRPC, so a local-struct-only field is
silently lost in production -- TestHarnessSecretConformance proves the round
trip in both its local and grpc modes.
2026-09-30 07:52:13 +10:00
sam 52d267683b merge: decide the dashboard test harness (7svn) 2026-09-30 07:51:44 +10:00
sam 0b00682fac merge: a TTL-bounded dedup gate for repeated inbound messages (104) 2026-09-30 07:49:59 +10:00
sam d1b8bff5ce docs(development): decide the dashboard test harness 2026-09-30 07:49:56 +10:00
sam ae8f0d42ef feat(gateway): a TTL-bounded dedup gate for redelivered platform messages 2026-09-30 07:48:56 +10:00
sam 39b61a0340 merge: record the operator's accepted package authority against the digest (em7s.3) 2026-09-30 07:43:23 +10:00
sam 06334ca3f9 merge: the own-PR flow no longer parks on the operator-approval gate (7nst) 2026-09-30 07:41:24 +10:00
sam f9e97b561f fix(workflow): the own-PR flow no longer parks on the operator-approval gate 2026-09-30 07:40:26 +10:00
sam d7f6f502a8 merge: decide the declared-outputs model for workflow.call (t2db.43) 2026-09-30 07:40:17 +10:00
sam 54e36ff8b7 merge: decide the operator-approval response channel and re-review cap (afbk.11) 2026-09-30 07:40:16 +10:00
sam a1c69c5b28 merge: one empty-state treatment from the installed primitive (micl.5) 2026-09-30 07:40:16 +10:00
sam bf68866dca feat(store): record accepted package authority against the pin
An archie package declares its authority; nothing in the tree recorded the
operator's acceptance of it. This lands the acceptance-record slice of
docs/prds/store.md ("Authority"):

- storepkg.Authority gains Covers (the upper-bound predicate: equal or
  narrower applies, wider does not) and Validate (forge-permission
  vocabulary, no blank grants).
- Installed carries AcceptedAuthority (nil until accepted); install leaves it
  unset, so an unaccepted package has no authority.
- AcceptPackageAuthority on the storepkg Manager records the acceptance
  against the pinned digest and refuses grants the package does not declare
  (storepkg.ErrAuthorityNotDeclared), carried over the wire.
- staterpc gains the admin-only AcceptPackageAuthority RPC;
  InstalledPackage carries accepted_authority.
2026-09-30 07:40:06 +10:00
sam 87d52938b5 refactor(webui): one empty-state treatment from the installed empty primitive 2026-09-30 07:39:10 +10:00
sam 90a4189db4 merge: render the Kit OAuth credential file with sentinels (egkf.13) 2026-09-30 07:38:58 +10:00
sam 013fcd0919 docs(prds): decide the declared-outputs model for workflow.call 2026-09-30 07:38:50 +10:00
sam 00209ebe87 docs(prds): decide the operator-approval response channel and re-review cap 2026-09-30 07:38:03 +10:00
sam 96e54e963f merge: cover the duration and byte-size control conversion logic (micl.4) 2026-09-30 07:37:33 +10:00
sam 2f05ed81b1 test(webui): cover the duration and byte-size controls' conversion behaviour 2026-09-30 07:37:05 +10:00
sam 822f8b63d4 feat(kitrun): render the OAuth credential file with sentinels
A Kit's credential@1 oauth.credentialFile was never rendered: Assemble set
SBX_CRED_<SVC>_MODE=oauth but no file was written, so the harness CLI started
logged out and never reached the token endpoint the egress proxy intercepts.

Render it at launch, for each bound OAuth-managed service that declares one:
the Kit's structure with its access/refresh sentinels, and the stored token
set's expiry for {{.ExpiresAt}}. The renderer's only input about a token set
is that expiry -- the tokens never cross into kit, so a real token cannot be
written (docs/prds/external-agent-harness.md, Verification).

Expiry renders as epoch milliseconds, the unit both in-spec OAuth credential
files use (Claude Code's expiresAt, OpenCode's expires). A placeholder archie
does not render, or a token placeholder with no declared sentinel, refuses the
launch rather than leaving a literal or an empty value in the file.

kitrun reads the store only for a service the run credential carries, and
fails closed when a rendered credential file has no captured token set.
2026-09-30 07:36:57 +10:00
sam e0ec9b87e6 merge: the dashboard workflow handlers act in the caller's org (t2db.45) 2026-09-30 07:35:12 +10:00
sam 27bad9f1fa merge: decide where per-workflow review settings live (0ry6) 2026-09-30 07:33:38 +10:00
sam 403ace1cef fix(webui): the workflow handlers act in the caller's org
The definitions query was built by hand, so it carried no org and the server
resolved the default one, while the enablement document read beside it and the
enablement write went to the default org outright. A caller in a non-default
org therefore read one org's definitions beside another org's enablement, and
toggled that other org's workflows.

workflowCollection now builds its query with controlplanerpc.QueryRequest, and
the three enablement reads and the write use org.OrgFromContext, so every one of
them names the org the principal put on the request context.
2026-09-30 07:33:16 +10:00
sam 761a1271a4 docs(prds): decide where per-workflow review settings live 2026-09-30 07:32:25 +10:00
sam c5a8942976 merge: carry the caller org from the request principal (t2db.45) 2026-09-30 07:25:48 +10:00
sam fb0424b729 fix(test): a table case holds the org, not a context
containedctx rejects a struct field of type context.Context, and both new
table tests stored one. Each case now carries what the caller put on the
context -- a builder in the org test, the org id in the client test -- and
builds the context inside the subtest.
2026-09-30 07:24:09 +10:00
sam 52b8b6dcca merge: name a workflow's declared inputs on the work-request form (06nq)
# Conflicts:
#	ui/dist/assets/index.js
2026-09-30 07:23:07 +10:00
sam d7178250ae feat(controlplane): carry the caller org from the request principal
The storage and wire contract already key resources by (org, kind), but no
caller sent an org, so every request acted in the default org. The org now
travels on the request context: webui's authorize middleware attaches the
verified principal's org, and one request-constructor per wire shape
(controlplanerpc's Query/History/Watch/CommandRequest) stamps it back, so a
call site cannot send the wrong org and a new one cannot forget it.

No behaviour change today: the shared token's principal is the default org's
owner, no production path creates another org, and a context with no principal
yields DefaultOrgID (what the server already derived from an empty org_id).
2026-09-30 04:01:52 +10:00
sam 9b282177e0 feat(webui): name a workflow's declared inputs on the work-request form
The dashboard could not name a workflow's declared inputs, so POST
/api/work-requests admitted a pr-review task with no pr_number, which then
failed at the workflow's intake stage (archie-core-06nq). The handler now takes
`inputs`, checks it against the workflow's declared interface before admitting
the task, and carries it through SpawnRequest.Inputs -> EnqueueChatTaskRequest;
the form renders one field per declared input, sends a declared number as a
number, and keeps Start disabled while a required input is empty.

Item 2 of the lane brief -- archie-core-afbk.12, review.precision_gate /
review.approve_before_post in the dashboard Config tab -- is deliberately NOT in
this commit. The surface it describes no longer exists in this tree; the
supervisor's decision was to stop it and re-scope it as its own lane, and the
facts it must start from belong in the branch's record:

* The Config-tab components were deleted by b5c98a0c (2026-09-25, "the legacy
  config catalog stops advertising fields the control plane owns"): ConfigSections.vue,
  ConfigRow.vue, ConfigControl.vue, ConfigList.vue, ConfigNotices.vue,
  ConfigUnavailable.vue, config-field.ts and sections.ts all went, because no
  page used them. Descriptor entries in internal/webui/config_schema.go would
  therefore change nothing a person can see: the only consumer of GET /api/config
  is SystemModelsPage reading `catalog`; the per-field `schema` has no renderer.
* The config write seams went earlier, in 295f8d69 (2026-09-21, "delete the
  runtime config overlay"): UpdateConfig, ResetConfig and UpdateRepoField are
  gone and internal/webui/server.go serves only GET /api/config. Configuration
  is written through the control plane.
* No control-plane resource carries review settings. executionSettingsDocument
  (internal/app/controlplane/workflow_settings.go) and workflow.ExecutionSettings
  carry only the four budget fields, and runtimeConfigFrom never layers
  cfg.Review. That is exactly why the budget descriptors survive in the catalog
  and review.* cannot: budgets are saved through workflow-execution-settings,
  edited on the Task-execution page, so those entries match a real write path.
* The brief's precedent name is wrong: TestToolSettingsProjectionCarriesEveryMCPServerField
  does not exist. The precedent is TestToolSettingsProjectionCarriesEveryMirroredField
  (internal/app/controlplane/runtime_config_test.go:349).

Making review.* genuinely editable needs a carrying control-plane resource
(extend workflow-execution-settings or add a review-settings kind), a layering
step in internal/app/archied/control_plane.go, and the round-trip test that
precedent sets -- an unsettled design decision spanning packages this lane does
not own.
2026-09-30 04:00:31 +10:00
sam 59273c9544 merge: attachment metadata in the session transcript (jaba) 2026-09-30 04:00:16 +10:00
sam 86e706dff7 merge: resume the PR branch before container acquisition (8li9.7) 2026-09-30 04:00:16 +10:00
sam ad5caf88a6 docs: the adversarial self-review record is removed, not shipped
docs/architecture/adversarial-review.md opened by describing the stage as
shipped and documented workflow.Reviewer, ReviewRequest, ReviewReport and
StageReview -- all of which 625ead95 deleted with the adversarial self-review
system. Three PRDs link to the page, so deleting it would break those links.

It gets a banner instead: the removal commit, the authority that supersedes it
(docs/prds/pr-review-agent.md says so in its own header), and the one section
that is stale in an older way -- the synchronous review_pr, which
archie-core-afbk.14 replaced with a queued pr-review task.

Regenerates docs/data/generated/dev-docs.json, which is built from these
sources.
2026-09-30 03:59:54 +10:00
sam a7efb9bb00 feat(webui): show attachment metadata in the session transcript
A message's attachments persist as metadata (messaging.Message.Media) and
cross the gateway wire, but the dashboard transcript rendered text only, so
a photo was invisible to the operator while the model had seen it.

The transcript view now carries the persisted metadata, and the browser
labels each attachment in the placeholder vocabulary the channels already
write into a message's text ('[photo]', '[document: report.pdf]'), with the
surviving metadata (mime, name, size, dimensions, duration) in the chip's
tooltip.

Bytes are never rendered: they are turn-scoped and stripped before a record
is stored, so there is nothing to fetch and no broken image or 404 link. The
platform file id is deliberately not served either -- it is a download
handle, not an address -- so the chip links out only when the attachment
itself carried a URL. A message with no attachments omits the media key, so
transcripts written before this change keep the payload they had.
2026-09-30 03:57:39 +10:00
sam 34f47a4bd0 fix(daemon): resume the task branch before container acquisition
prepareWorkspace always called worktree.Manager.Prepare, whose refresh
resets an existing clone onto origin/<base>. A remediation task -- one
continuing an archie-owned PR branch -- therefore lost that branch's
commits before its container started: StageResumeWorktree runs inside the
container against a tree already reset to base, and hybridTrees.Resume is
a no-op, so nothing restored origin/<branch>.

Route a task whose row names the remediate workflow through
Manager.Resume on the persisted Task.Branch, before Acquire. The branch is
read from the task row, never recomputed from the title or labels, and a
missing branch fails closed with a park rather than falling back to base.

Regression tests use a real bare remote: the prepared worktree's HEAD must
be the PR branch tip, a missing branch must park without touching the
worktree, and a non-remediation task must still start from base.
2026-09-30 03:56:04 +10:00
sam d60fcad18f fix(store): refuse resource keys the audit key cannot disambiguate
An empty org or kind, or either containing the '/' that joins them in the
audit record key, fails on read and write instead of colliding or reading as
an absent resource.
2026-09-30 03:43:23 +10:00
sam 8124c5af54 Merge pull request #1238 from samcharles93/security/prsource-zipslip
fix(prsource): guard archive extraction with a CodeQL-recognised containment check
2026-09-30 03:38:22 +10:00
sam bfc8d4b1b7 feat(store): key control-plane resources by (org, kind)
resources and resource_history are one document per org and kind, with
per-org advisory locks, request-ID idempotency and audit keys. The
control-plane Query/History/Command/Watch requests carry org_id; a request
naming none acts in the default org until the caller's org is derived
server-side.
2026-09-30 03:34:02 +10:00
sam 0b8e9ae7f1 fix(prsource): use a CodeQL-recognised containment guard when extracting archives
The tar.gz extraction already refused ".." escapes, but it did so with
filepath.Rel and checked the resulting relative path. CodeQL's go/zipslip
query models a sanitizer only as strings.HasPrefix applied to the value that
reaches the file-system sink, so the derived relative-path check was invisible
to it and it flagged os.MkdirAll/os.WriteFile on the joined target
(alert 17: internal/infrastructure/prsource/archive.go).

Resolve destDir to an absolute path once, reject an absolute entry name
outright, then test the joined target against the destination root with
strings.HasPrefix -- the PrefixCheck guard the query recognises. Behaviour is
unchanged: a ".." entry is still refused, and a wrapper directory is still
stripped. Adds an absolute-entry rejection test and a test proving an escaping
entry writes nothing outside destDir.
2026-09-30 03:15:21 +10:00
sam 662a5ee336 feat(telegram): carry inbound media through the chat turn
Telegram dropped every incoming photo, document, video and audio
message: the default handler required message text, and nothing on the
turn path knew media existed. The receiving path now closes the gap
end to end.

- telegram: extract the attachment from the update (largest photo, plus
  document, video, video-note, audio and voice kinds), download its
  bytes on the turn lane through getFile + the Bot API file link with a
  20 MB gate, submit the turn with the attachment, and answer
  unsupported content kinds (sticker, location, contact, poll) with a
  clear notice instead of silence
- messaging: Inbound carries turn-scoped transport media and
  MediaAttachment a Data field for in-process bytes; Message gains
  Media attachment metadata which stores persist (Postgres jsonb via
 migration 0020, memory store) with Data stripped at the persist
  boundary, and pb.Message carries the metadata on the gateway wire
- gateway: TurnModelRequest threads the turn's media to the model seam
- archied: the chat turn model merges the attachments into the final
  user message as ai-sdk image/file part entries, so vision-capable
  models see the file for the turn it arrived in; stored history keeps
  the placeholder note plus caption

Session log: messages carry what was sent as data (the attachment
metadata), not just prose. Transcript rendering of attachments and a
re-look capability are tracked as archie-core-jaba.
2026-09-30 03:07:54 +10:00
sam 8cbbdb20b5 feat(eda): per-org workflow enable/disable gating bindings
A workflow-enablement control-plane resource lists, per org, the workflows
that org has disabled. A binding targeting a disabled workflow is skipped at
dispatch like an unarmed one, is refused on save, and is flagged on the
binding list; the workflows page toggles it. Bindings now carry the org_id
column they already had in storage, over the State Store wire too.

Org-owned workflow definitions are deferred to a follow-up bead: they need
the caller's org, which the access chain resolves.
2026-09-30 02:59:23 +10:00
sam cadbc6d1ca Merge origin/main (v1.44.1) into local main 2026-09-30 02:39:21 +10:00
sam 64128645c2 fix(eda): reject a result map missing a field or needing a conversion
DecodeResult accepted any value reflect could convert, so a number for a
string field silently became the rune string (42 became "*"), and a declared
field absent from the map read as its zero value. Both are now reported: a
value is accepted only at the field's declared type, and every declared field
must be present.

That is the boundary the typed CEL environment promises, and it is live now
that the action runner decodes every result into actions.<id>.result before a
later expression reads it. D5 in docs/prds/multi-action-playbooks.md records
the rule.
2026-09-30 02:38:20 +10:00
sam 8155cc915a docs(eda): ratify args evaluation-failure semantics (J6)
An args value that cannot be evaluated aborts its playbook run: the action and
every later action in that playbook do not run, other playbooks matching the
event still run, and the task is unaffected. J3's skip-and-continue rule stays
specific to `when`, because a predicate has a meaningful false and data does
not.

Ratified now that the action runner is the production consumer, and locked by a
call-site test that fails if the rule is weakened to a skip. Drop the stale
"unbuilt decisions" header line, since J1, J2 and the Result schema
declarations have shipped.
2026-09-30 02:31:21 +10:00
sam 150dde5a7d test(state-store): parallelize real-process smoke tests 2026-09-30 02:14:29 +10:00
sam a65f558d35 chore(release): v1.44.1 2026-09-29 15:41:53 +10:00
sam 0dff130682 Merge pull request #1237 from samcharles93/fix/1233-refresh-stale-seeded-workflow-definitions
fix(controlplane): refresh a stale seeded resource and re-seed a removed one
2026-09-29 15:12:45 +10:00
sam 2d1d4ed632 Merge pull request #1236 from samcharles93/fix/1235-repin-workflow-when-requeue-changes-it
fix(daemon): re-pin a task's workflow definition when a requeue names another
2026-09-29 15:12:01 +10:00
sam 67c5447ebc fix(controlplane): refresh a stale seeded resource and re-seed a removed one
A seed was consulted only for a resource kind the store did not hold, so a
document that changed in the build never reached a database an earlier
release had seeded. For workflow-definitions that is not a stale setting but
a total outage: the collection validates as one document, so a stored step
type this build no longer has fails every task's pin, whatever workflow the
task names. The seed's request ID was stable per kind and the store answers a
known request ID from resource_history, which outlives the resource, so the
documented recovery -- remove the resource and restart -- wrote nothing
either.

Seeds now carry one identity the reader can name, and a kind the store holds
is refreshed only when the seed itself wrote the newest revision: a
file-derived value stays the store's, and an operator's replacement is never
undone. The request ID is derived from the value, so an idempotent replay is
still one revision without making a second, changed document impossible. A
replay whose resource is gone re-creates it from the ledger's revision.

The shipped-vs-file-derived distinction is the seed's to make, so it is a
property of the definition (Defaults is set exactly for the kinds that ship a
document) rather than a check at each consumer.
2026-09-29 14:27:57 +10:00
sam db6e8d321e fix(daemon): re-pin a task's workflow definition when a requeue names another
Approving a waiting_human task requeues it under implement, but the requeue
only writes status, workflow and park_reason: the previous run's definition
stays pinned. pinWorkflowDefinition then returned early on any non-empty
stored definition, having checked only that the YAML matched its own recorded
digest -- a property of the write, never of the task -- so the dispatch went
out carrying a definition naming feasibility over a row naming implement.

That is the pair the worker's compile refuses
(agentworker.CompilePinnedWorkflow: "pinned workflow definition does not match
task identity"), so the task parked again immediately, identically on every
further approval, leaving decline the only working operator action.

A pin's identity is part of what makes it valid, not an assumption. The
producer now reads the id the stored definition declares (workflow.DefinitionID
answers that from YAML alone, without the step vocabulary) and re-pins from the
active collection whenever it disagrees with the task's workflow column. A pin
that is present, digest-valid and id-consistent is still a strict no-op, so an
operator's active definition override survives a dispatch unchanged, and a pin
whose YAML does not match its recorded digest is still refused rather than
silently overwritten.

Closes #1235
2026-09-29 13:34:10 +10:00
sam cbeab6afd2 chore(release): v1.44.0 2026-09-29 02:04:40 +10:00
sam ed698fced1 feat(pr-review): benchmark live pipeline through generic workflow spawn 2026-09-29 00:35:34 +10:00
sam 081ee4a8ba docs(daemon): enqueue-time fields belong in the insert; review_pr names the approval gate 2026-09-28 22:42:19 +10:00
sam 5de07fac0e feat(pr-review): operator/chat trigger queues a pr-review task
review_pr self-omitted since 625ead95 deleted the synchronous reviewer it
called. It is rebuilt on the task enqueue path everything else uses: the
tool resolves the identity's configured repo, then queues a pr-review task
naming the pull request through the workflow's declared pr_number input,
which is the same generic input mechanism a watched-repos binding uses.

That input has to reach the store with the task, so
EnqueueChatTaskRequest gains inputs_json and the tasks insert writes the
inputs column directly. StampTaskBinding no longer writes it: the insert is
now the column's only writer, and a chat task must not acquire binding
provenance just to carry an input.

ChatPRReviewer, its result shape and the reviewer wiring are deleted with
the path they served.
2026-09-28 18:24:36 +10:00
sam 03335f49c1 fix(workflow): don't require a PR number for archie's own PRs
stagePRIntake's new missing-PR-number error (d0d759d2) fired even when
this stage runs embedded inside StagePRReviewAndOpenPR (archie's own
PRs, Task.Workflow == "implement"), where no PR exists yet and
localPRSource deliberately ignores the number. Scope the error to the
standalone pr-review workflow, which always needs a real, externally-
fetchable pull request.

Caught before this reached main: the existing StagePRReviewAndOpenPR
tests substitute a fake decision-stage list (by design, so they don't
have to script all nine phases' agent calls), so they never exercised
the real stagePRIntake and would not have caught this. Added a test
that calls stagePRIntake directly with Workflow: "implement" and no
PR number, which does.
2026-09-28 17:02:18 +10:00
sam d0d759d216 feat(workflow): watched-repos triggers pr-review via the generic binding system
Watched-repos needs no bespoke webhook-parsing code: the existing
generic capture+binding system (internal/infrastructure/captureintake,
internal/domain/binding.Binding) already turns any inbound webhook into
a task on any workflow, via a dashboard-editable matcher, CEL filter
and payload-to-input mapping. pr-review just needed to become a
binding-targetable workflow.

- Workflow gains an Interface field (task.WorkflowInterface) so a
  Go-literal builtin can declare inputs the same way a YAML-defined one
  does; ShippedDefinitions emits an inputs: block only when non-empty,
  so every other builtin's generated YAML is byte-identical to before.
- PRReview() declares pr_number as a required number input.
- Task gains EffectivePRNumber(): PRNumber when a producer set it
  directly (archie's own PRs), else the pr_number input a binding
  assigned generically through Task.Inputs. Handles json.Number (the
  store's round-trip encoding), float64 and int.
- The daemon resolves it once in acquireTaskContainer, before the task
  brief is written and before the pr-review prefetch runs, so
  everything downstream agrees. stagePRIntake falls back to the same
  resolution for any dispatch path that bypasses container acquisition,
  and fails loudly if neither PRNumber nor the input is set.

An operator wires up watched-repos entirely through the dashboard: a
Binding matching the webhook's source, a CEL filter for pull_request
events, workflow: pr-review, and an Inputs mapping pr_number from the
payload. No code change needed for a new repo or a new source.

Operator/chat trigger remains open, left as a precise continuation:
EnqueueChatTask is part of the State Store's protobuf-generated gRPC
contract (proto/state/v1/state.proto), not just a Go interface --
extending it for a generic inputs parameter needs a proto field
addition + regen, a new SQL query (StampTaskBinding cannot be reused,
since it unconditionally stamps binding_id/version, which a plain chat
task must never carry), and updates across staterpc's client/server and
~20 call sites. Real plumbing, not a quick tool rewrite -- scoped
correctly as its own pass rather than rushed here.
2026-09-28 16:59:32 +10:00
sam 67ead19dd9 feat(pr-review): daemon prefetches PR data so no forge credential enters the container
Adds the mechanism pr-review's watched-repos and operator triggers need:
before acquiring a pr-review task's container, the daemon fetches the pull
request's metadata, diff and head snapshot over its own credentialed forge
client (prefetchPRReview, using the already-built HTTP-based prsource.Source
from f7c64616) and writes the result under workDir/.archie-pr-review -- the
same host directory Docker bind-mounts into the container. The container-side
pipeline reads it back with prsource.MountSource, a local filesystem read, no
network call and no credential.

This follows the existing convention exactly (docs/development/agent.md,
"Giving the agent something new": "the daemon's own administrative token
never enters a container") and the same pattern WriteTaskJSON already uses
for the task brief -- prepare on the host before the container starts,
because the container binds the directory. No RPC service, no environment
variable, no exception to the stated rule.
2026-09-28 15:19:39 +10:00
sam f7c646163b feat(prsource): rebuild PRSource over the forge's HTTP API, no git checkout
The pipeline's Stage.Run bodies execute inside the sandboxed archie-agent
process, which holds neither a forge credential nor a git-level one --
confirmed the egress/CredentialCapability mechanism (grants.go,
credentials.go) only wires into the Kit/harness launch path
(kitrun.Launcher), not the built-in runner pr-review actually uses, so
routing through it as previously planned isn't viable without a much
bigger structural change. The git-shell Trees dependency needed a local
clone and a git-level credential the sandbox likely doesn't have even with
a bare API token.

Adds two narrow forge capabilities (PullRequestDiffReader,
RepoArchiveReader) implemented on both backends:
- GitHub: PullRequests.GetRaw for the diff, Repositories.GetArchiveLink
  plus a manual unauthenticated fetch of the resolved (pre-signed,
  non-API) blob URL for the archive.
- Gitea: GetPullRequestDiff and GetArchiveReader directly (no separate
  fetch needed).

PRSource.Snapshot fetches the archive and extracts it with a new
extractTarGz, which strips the wrapper directory both forges add (whether
represented as a bare-name path prefix or an explicit tar directory
header), refuses any entry that would escape destDir, and drops .git
entries per the Isolation contract.

Real bug caught before commit: the wrapper-stripping heuristic initially
treated a lone top-level file the same as a top-level directory header,
silently discarding the file entirely when no wrapper existed. Caught by
TestExtractTarGzWithNoWrapperDirectory before it shipped.

Not wired into any trigger yet -- watched-repositories and the operator
trigger still need this Source constructed and handed to the pr-review
task's TaskContext, which is where an execution-model decision (daemon-side
vs sandboxed) has to land first. Left as a precise continuation on
archie-core-afbk.7, not guessed past.
2026-09-28 14:46:09 +10:00
sam 8d05f99526 feat(workflow): wire pr-review into archie's own PRs before opening
StagePRReviewAndOpenPR runs the pr-review pipeline's decision phases
(1-8) against the task's own uncommitted change, using a new
localPRSource that reads Diff/Snapshot straight from Trees instead of
fetching an external PR -- there is no PR number yet to fetch one by,
which is why this trigger needed its own PRSource rather than the
forge-backed one afbk.7 already built for external PRs.

An unchallenged blocking finding parks the task with the findings
instead of opening a PR; a pipeline stage failure parks it the same
way any stage failure does. Once the PR opens, advisory findings post
against it -- best-effort, matching the deleted StagePostReviewComments'
convention: a posting failure is logged, not reverted into the outcome
the PR's existence already earned.

Implement() now uses this in place of the plain StageOpenPR. Bootstrap
and TDD are untouched -- the PRD names "the implement workflow"
specifically; extending to the others is a separate call.

Resolves this bead's first blocker (confirmed via read: CompilePinnedWorkflow
returns the same workflow.Workflow type and runs through the same
workflow.Run either compilation path, so a stage setting Outcome ends
the run identically regardless -- stagePROutput's posting logic had to
move inside StageOpenPR's own Run body, not follow it as a separate
Stage, which OpenPR's own doc comment already anticipated).

Still open on this bead: watched-repositories and operator triggers,
both blocked on the credential path for PRSource's real forge-backed
implementation reaching the sandboxed archie-agent process -- see the
bead comment for the concrete design (egress credential-capability
grant, narrow forge diff/archive HTTP methods) not yet built.
2026-09-28 13:06:42 +10:00
sam 625ead95b3 feat(workflow): remove the superseded adversarial-self-review system
docs/prds/pr-review-agent.md's own header already declared this
superseded (docs/architecture/adversarial-review.md, docs/prds/
operator-pr-review.md, docs/prds/review-calibration.md); this executes
that removal per the maintainer's explicit decision, so no reference
to the old path remains:

- internal/domain/workflow/review.go, review_findings.go,
  review_report_md.go and their tests: Reviewer, ReviewRequest,
  StageReview, StagePostReviewComments, ReviewReport/ReviewFinding and
  friends. ReviewComment relocated into workflow.go (still used by
  Forger.CreateReviewComments and the new pr-review pipeline).
- internal/app/agentworker/review.go: the ai-sdk-backed subagentReviewer.
- internal/app/archied/pr_review.go: the synchronous operator-review
  path (prReviewer, gateway.ChatPRReviewer wiring). The review_pr chat
  tool now self-omits (nil reviewer) until the operator trigger is
  rebuilt to enqueue an async pr-review task instead of reviewing
  synchronously in the chat turn.
- config.Repo.ReviewEnabled and its dashboard exposure.
- Two composition-order tests and one dashboard test that existed only
  to pin the deleted path.

Also splits PRReview()'s Stage list into prReviewDecisionStages()
(phases 1-8) and stagePROutput() (phase 9), so a future caller can
splice the decision phases before a PR exists and defer posting until
after -- needed for the "archie's own PRs" trigger, not wired here: it
needs the same stage-loop-around-StageOpenPR semantics this pass
couldn't fully verify in the time available (does an Outcome-setting
stage like StageOpenPR end the compiled-workflow-definition engine the
same way it ends workflow.Run's literal loop?). Carries ScoredFinding.
Adversary through synthesis so that trigger's blocking-finding check
doesn't need to cross-reference back into the pre-synthesis slice.

Not built in this pass, left as a precise continuation (see the bead
comment): the watched-repositories and operator triggers, both blocked
on the same real question -- how a forge-reading credential reaches
PRSource's real implementation when the pr-review pipeline's Stage.Run
bodies execute inside the sandboxed archie-agent process, which holds
none today.
2026-09-28 12:55:05 +10:00
sam 0acc922d9a feat(prsource): real forge-backed PRSource for the pr-review pipeline
Metadata/Diff/Snapshot implemented against a narrow Forge (GetPullRequest)
and Trees (CheckoutPR/Diff/Snapshot) contract, satisfying
workflow.PRSource -- the counterpart to the task's own Trees, which never
reaches an arbitrary external PR. worktree.Manager already satisfies the
narrow Trees interface structurally; forge.PullRequestReader needs a
small field-mapping adapter at the composition root (not yet wired --
see the afbk.7 continuation note).

Deliberately not wired into production task execution this pass: doing
so surfaced a real credential-boundary problem (see bead comment) that
needs resolving first, not papering over.
2026-09-28 12:32:08 +10:00
sam 595956cc75 feat(workflow): pr-review precision dial and operator-approval gate
Add review.precision_gate and review.approve_before_post to config,
threaded through TaskConfig/ForTask/ToConfig so the pr-review workflow
reads them under archie-agent too, not just in-process.

stagePRPrecisionGate runs between review and verification, filtering
findings down to concrete, evidenced defects when the dial is on;
stagePROperatorApproval ends the run in waiting_human right after
synthesis, before the merge gate, when approval is required and
findings exist. Both are off by default and fail open on a broken
agent call, matching the pipeline's existing recall-first fallbacks.

Filed follow-ups: afbk.11 for the actual operator-response resume
mechanics (post/reject/re-review with instructions, the 2-round cap --
genuinely needs either a small Task schema addition or a documented
Notes-encoding decision, a call for whoever wires afbk.7's triggers)
and afbk.12 for exposing the two flags in the dashboard Config tab.
2026-09-28 12:20:10 +10:00
sam 929784667b feat(workflow): merge gate, budget shares and skipped-phase reporting for pr-review
Phase 8 (merge gate) runs one classification call per finding, deciding
blocking vs advisory per the PRD's narrow criteria; a failed or malformed
call leaves the finding advisory. Added between synthesis and output.

A run-level token/wall-clock budget, split into cumulative per-phase
shares (prreview.Budget.PhaseExhausted), gates the expensive agent-call
work in lenses, review, verification, coverage-consistency, merge-gate,
and the anatomy narrative / output polish sub-calls -- deterministic
bookkeeping (snapshot, blast radius, clustering, scoring) always runs
regardless. A skipped phase is recorded and named in the posted review's
outcome, alongside the REQUEST_CHANGES/COMMENT event ReviewEventFor
already decided.

Known gaps left for a follow-up: workflow.Forger.CreateReviewComments
always posts a COMMENT-state review (GitHub's implementation submits
per-comment calls, not a review object, so REQUEST_CHANGES needs a
Forger/forge change), and there is no PR-body fallback list for
whole-file findings (docs/prds/inline-review.md).
2026-09-28 11:26:20 +10:00
sam d4e254b349 feat(workflow): wire pr-review's verification and coverage/consistency stages
Adds phases 5 and 6 of docs/prds/pr-review-agent.md between the existing
review and synthesis stages: an evidence verifier that drops unsupported
high-priority findings, an adversary that confirms/challenges findings and
may report new ones (more sceptical for a likely machine-written PR), a
per-cluster compound-defect check, a coverage gate that runs gap reviewers
for uncovered clusters and high-exposure blast-radius files (capped at 2
rounds), and consistency verification for cross-location obligations. The
coverage gate and consistency verification run in parallel per the PRD,
guarded by prReviewState.findingsMu.

Phases 5/6 are afbk.4's scope; the merge gate (phase 8) remains afbk.5's.
2026-09-28 11:04:44 +10:00
sam 89c5f8e2ad feat(workflow): add coverage-gap and exposure helpers to pr-review's deterministic core
Extends the afbk.1 deterministic core for afbk.4's coverage gate and
compound-defect check: exposure fan-in counts and high-exposure filtering
(blast.go), cluster/finding coverage matching and grouping (coverage.go),
and a high-priority severity predicate the evidence verifier gates on
(scoring.go).
2026-09-28 11:04:25 +10:00
sam 2ffe924a44 feat(workflow): wire the pr-review pipeline's Stage graph (afbk.3)
Adds PRSource (metadata/diff/snapshot, mirroring Trees for an external PR
rather than the task's own worktree) and the pr-review workflow: intake,
anatomy, lenses, review, synthesis and output as Stages recording
StepExecution children, built on the deterministic core from afbk.1/.2.

Phase 4's reviewer fan-out records a distinct StepFailed for a reviewer
that exhausted its turn cap or deadline before its terminal tool call,
separate from StepSucceeded for one that completed and found nothing
(the just-landed PRD refinement); phases 3, 4 and 9 fan out through a
bounded semaphore since tc.RunAgentChild already supports concurrent
StepExecution recording from inside one stage body.

Phases 5, 6 and 8 (verification, coverage/consistency, merge gate) are
out of scope -- afbk.4 and afbk.5. Output posts every line-anchored
finding as advisory forge review comments; the blocking/advisory split
needs the merge gate first.
2026-09-28 09:40:56 +10:00
sam c9f677f35b feat(workflow): pr-review intake depth and dimension merge
First slice of archie-core-afbk.3's pr-review pipeline (phases 1 and 3's
deterministic logic): depth classification from changed-line count with the
operator-override rule, the depth-to-dimension-cap table, cross-lens
dimension merge/dedup/cap, and the hallucination-check dimension added for a
likely-machine-written PR.

Table-driven tests cover the classification boundaries, the override rule,
duplicate-name merging, priority-ordered capping and the AI-generated
threshold. Stage wiring (agent calls, StepExecution recording, the fan-out
concurrency phases 3/4/9 need, and a PR diff/snapshot source) is still open;
see the bead for what remains.
2026-09-28 03:00:59 +10:00
sam d60f024e74 docs(prds): route intake's AI-score into lenses, split reviewer timeout from zero-findings, bound phase 9
Landing three PRD refinements found while studying prior reviewer art before
starting archie-core-afbk.3: dimension selection now sees intake's
machine-written score directly and adds a hallucination-check dimension for
it; a reviewer that exhausts its turn cap or deadline records a distinct
StepExecution status from one that completed and found nothing; phase 9
polish runs in a bounded pool of 8, matching phase 4.
2026-09-28 03:00:51 +10:00
sam 1fa3acdbe9 fix(security): bound harness IDs to int and drop a summed map size hint
Clears the five open CodeQL alerts. harnessCredential parsed uid and gid
as 32-bit and os.Chown converted them to int, which wraps on a 32-bit
build; they are now parsed to 31 bits, so an out-of-range id is refused
where it is read. mergeMapping sized its map by len(base)+len(override);
it now hints len(base) and lets the map grow.
2026-09-28 02:20:25 +10:00
sam d10b070a2e chore(release): v1.43.0 2026-09-28 02:13:34 +10:00
sam b93909c5aa feat(kit): materialize the agent-context profile beside the workspace
agent-context@1 was listed as supported, but a Kit's contributed guidance
never reached the agent. At container create archie now writes the
workload's profile file (CLAUDE.md, AGENTS.md, ...) beside the workspace
with a Kits index: a staged body is pointed at where the image holds it,
an inline one gets its own file the index points at. The profile never
inlines a Kit's text. The files are written as root, so a run can read
but not change them, and are rewritten on every create.

The workspace moves to /archie/workspace so the profile sits in a real
parent directory rather than /, which some CLIs stop short of when they
look upward for instruction files.

Part of archie-core-egkf.6.
2026-09-28 02:12:29 +10:00
sam 42a4e2465d feat(kitrun): mount the operator's skills store for agent-skills@1
A Kit's agent-skills@1 path now gets the shared skills store
(skills_dir/.agents/skills) bind-mounted read-only, whatever mode the Kit
asks for; with no skills_dir the host withholds the mount. skills_dir is
read live on every launch. skill.StoreDir exposes the store path so the
launcher does not copy the package's directory constant.

Part of archie-core-egkf.6.
2026-09-28 02:12:29 +10:00
sam 608403c1f9 feat(kit)!: a Kit profile names one Kit image, a workload or a published set
kitrun ran the first Kit of a profile's list as the container image, so
every mixin's layers (its tools, skills and staged context) were dropped
without a refusal. A profile's `kit` is now one digest-pinned reference:
a workload Kit, or a published Kit set, which the Kit spec's frontend
merges from a workload and its mixins into one image. archie composes no
Kits itself, and a bare mixin is refused with a pointer to publishing a
set. kit.Compose had no production caller left and is removed.

BREAKING CHANGE: `[containers.profiles.X] kit` and the agent-profiles
document's `kit` are a string, not a list. A stored list fails to decode
and must be rewritten as the one workload or set reference.

Part of archie-core-egkf.6.
2026-09-28 02:04:04 +10:00
sam e9e52c1f1f Merge crew/claude-997: OAuth token-endpoint interception and access-token injection in the egress proxy 2026-09-28 01:53:35 +10:00
sam fc5d24c9f7 feat(egress): intercept OAuth token endpoints and inject stored access tokens
The egress proxy now holds a Kit's OAuth tokens on the host. A refresh
carrying the sentinel refresh token goes upstream with the org's stored
one; a successful response is written to the State Store and returned to
the container with sentinels only. Requests to the Kit's resource hosts
carrying the sentinel access token get the stored one.

The org's token set is read or written only for a run whose credential
carries the service, so a Kit declaring a service never reaches the org
secret by itself. The launcher grants a bound OAuth service without a
config secret, and Register refuses a required OAuth credential when no
harness secret store is wired. A provider that does not rotate refresh
tokens keeps the stored one.

Part of archie-core-egkf.7 (#1208). Credential-file rendering and
per-binding concurrency remain.
2026-09-28 01:52:07 +10:00
sam 0b82f1c9a5 chore: cleanup old docs 2026-09-28 01:48:20 +10:00
sam cdc3e83740 chore(agentexec): strip the recording session's personal tool list from claude fixtures 2026-09-27 18:35:28 +10:00
sam 807d1dfc15 chore(license): license archie-core under Apache 2.0 2026-09-27 18:22:46 +10:00
sam dbaa7284a3 feat(taskactions): archive reaps the task's worktree; cleanup test models a completed run
A worktree terminal cleanup keeps (uncaptured or unreadable work) now has a
reap path: archiving calls Daemon.RemoveWorktree for the owning identity's
trees, and the keep logs name archive as the way out. The no-change cleanup
test reports completed through one direct transition instead of reaching
merged via a faked pr_open hop.
2026-09-27 13:38:12 +10:00
sam 5734e194c9 fix(taskstate): tie operator actions to the transition table; keep unreadable terminal worktrees
qdbo.8 follow-ups: ActionTarget names each action's destination status, the
taskactions service records through it, and a test proves every offered action
is a legal transition. worktreeHoldsUncapturedWork now keeps a worktree on any
stat error other than not-exist. The dashboard action test covers completed, and
agent-system.md drops the no-state-machine hazard qdbo.5 resolved.
2026-09-27 13:29:55 +10:00
sam e16ba86b30 feat(harness): ingest OAuth storage and recover workflow write handling
Recover the OAuth storage slice from f6079e9d and the missing workflow persistence error handling from f07c314e, adapted to the current step contract. Require encryption for OAuth token storage and verify RPC round trips and task-grant denial.
2026-09-27 13:09:41 +10:00
sam a2650eb5e9 Merge crew/pi-dashboard-sweep: agent-call children, call steps, and the waited-on callee sweep
# Conflicts:
#	internal/domain/workflow/workflow.go
#	internal/infrastructure/postgres/queries/steps.sql
2026-09-27 07:16:35 +10:00
sam 1686fba12b feat(workflow): agent-call children, call steps, and the waited-on callee sweep
Plan item 4 of docs/prds/execution-tree-state-machine.md (archie-core-1216),
plus the callee half of CancelExecution that plan item 5 deferred until the
tree could decide it.

Every agent call a stage makes records itself: AgentStage's bridge, the
baseline-fix auto-fix run, the adversarial reviewer and a workflow.call each
start a child StepExecution of kind agent or call under the stage's own step
-- TaskContext.StepID, which the engine sets before the stage body starts and
clears when it returns -- and finish it with the call's own outcome and the
tokens it accounted. A child's recording write failure parks the execution
the same way a stage's does: an agent call that ran unrecorded is the
invisibility the step table exists to end. A stage invoked outside the
engine's recorded run -- the stage unit tests -- records no child and runs
unchanged.

The call step is what makes the callee half of the PRD's Cancellation section
decidable, and this lands it: a call step closes when its callee ends, so an
open call step is a callee the caller waits on (wait:true) and a closed one
is a wait:false callee that runs on. CancelExecution reads the open call
steps before its sweep closes them and cancels each named callee through its
own CancelExecution in the caller's write's aftermath -- the callee's own
steps, its own events, its own move to the same destination, and the callee's
own wait:true callees beyond it, the depth the enqueue enforces bounding the
recursion. A callee that cannot be cancelled is reported and the caller's own
record stands.

StartStep refuses a call step whose callee is not this run's own (the
callee's call_parent_task_id must name the recording execution): a
compromised container could otherwise record a step naming a foreign
execution and cancel it. StartStepRequest gains called_execution_id (field 6;
non-breaking, the column and its named consumer already exist) and
StepStart carries it.

PRD decisions recorded here:
- The reviewer records as one agent child named "review": the Reviewer
  contract runs one subagent per review, the PRD model's review:1/review:2
  are illustrative of depth-1 children. A completed report closes it
  succeeded, a not-run review failed with the skip reason; the contract
  carries no usage, so tokens are 0.
- A failed-callee call step closes as failed with the callee's detail when
  the wait ends otherwise; the single open case is the caller itself being
  cancelled, whose CancelExecution already swept this step -- a late write
  must not pretend the wait is still the caller's business.
- A call step's callee is cancelled to the same destination the caller's
  action named (parked stays parked, closed_wont_do ends the whole chain),
  and a callee that cannot be cancelled is reported while the caller's own
  record stands either way.
- The agent child's detail is the result summary on success and the error's
  text on failure, with the call's own TokensUsed -- the PRD's only usage
  field, untracked per call for the reviewer contract.
2026-09-27 07:14:15 +10:00
sam 519604405a Merge crew/claude-997: dashboard run detail reads ListSteps; tasks.stage removed 2026-09-27 07:05:08 +10:00
sam 2aea3ce0dc fix(webui): drop dead Task.stage readers, split stateStoreDeps for cyclop
The task-list table and NeedsYouCard read a task.stage field the API
stopped emitting once tasks.stage dropped; remove the column and the
fallback rather than let it render an empty cell forever.

stateStoreDeps grew a fourth optional-capability branch (StepReader,
alongside Pi's ExecutionCanceller and the RecoverStale rebase) and
tripped golangci-lint's cyclop gate; split the execution-tree surfaces
into executionDeps, mirroring the existing accessDeps split.
2026-09-27 07:02:05 +10:00
sam e7b21b9e5d feat(state-store): ListSteps, dashboard run detail reads it; drop tasks.stage
docs/prds/execution-tree-state-machine.md: step_executions (0017) is now the
durable per-step record; the dashboard's run detail (GET /api/tasks/{id}/
attempts) still folded stage_start/stage_finish events into a rail by hand,
and tasks.stage duplicated what StartStep/FinishStep already record properly.

Added the missing read:
- ListSteps(execution_id, attempt) -- attempt 0 lists every attempt of the
  execution, oldest first, so the rail renders every attempt from one call.
  New storecontract.StepReader (separate from StepRecorder: this is a
  dashboard/API/dispatch action per the PRD's wire contract, never
  task-scoped-grant callable), postgresdb.ListStepExecutions, staterpc
  client/server/values.go plumbing, wired through state_store.go's Deps and
  archieui/compose.go's Server.Steps the same optional-capability pattern
  every other dashboard read uses.
- internal/webui/api_tasks_attempts.go: stageViewsFromSteps replaces
  foldStages/finishStage/stageOutcome. Attempt bounds, event_count and which
  attempt numbers exist stay sourced from events (an attempt can carry
  events -- agent calls -- with no step), only the stage list itself moves.
  The wire JSON contract is unchanged, so no frontend change was needed;
  `task ui` confirms ui/dist still matches a fresh build.
- A running step past the task's own current attempt reads interrupted, not
  running: RecoverStale (archie-core, still open per #1214) is what corrects
  a crashed run's stale "running" row, and until it does this is the honest
  read rather than trusting a row that may be stale.

Dropped tasks.stage and every reader, no fallback:
- Migration 0018 drops the column; tasks.sql's INSERT/UPDATE/RETURNING lists
  and the sqlc-generated code no longer carry it.
- workflow.Task.Stage is gone; workflow.Run's in-flight "which stage is this"
  bookkeeping moves to TaskContext.Stage (execution-time only, never
  persisted -- park/finish's event tagging is its only reader).
- pb.Task.stage (wire field 10) is `[deprecated = true]`, not deleted (never
  reuse a field number); staterpc's taskProto/taskValue no longer map it.
- taskactions.Task.Stage and the retry event's "previous_stage" data field
  are gone: the operator-action package had no reader for the column beyond
  echoing it.
- The chat /tasks command's per-task "workflow/stage" display drops to
  workflow-only (ChatTaskSummary.Stage removed, workflowStage() deleted):
  it was a genuine reader with no replacement in scope for this change.

Read the archie-web-ui skill and the state-store/daemon docs/development
pages first, per instruction. Stayed out of cancel/stop code throughout
(Pi's concurrent CancelExecution work); the only shared files touched
(workflow.go, daemon-adjacent SQL) got the smallest possible diff.
2026-09-27 06:57:47 +10:00
sam e992d4256e Merge crew/pi-dashboard-sweep: RecoverStale interrupts the steps a crash left running 2026-09-27 06:51:07 +10:00
sam 41823ab336 feat(statestore): RecoverStale interrupts the steps a crash left running
Plan item 6 of docs/prds/execution-tree-state-machine.md (archie-core-1214),
the crash-recovery sweep the step table made decidable. RecoverStale used to be
one bare UPDATE of tasks running -> queued; the steps an interrupted execution
left running stayed running forever, so the next attempt started under steps
that were never closed.

Recovery is now one transaction: the running executions are locked, every step
each one's current attempt left running moves to the step transition table's
interrupted outcome with one stage_finish event row carrying the
interruption marker -- the same document stageOutcome reads, so the attempt
view renders the interruption the way the pre-step-table producer wrote it --
each execution's audit row lands in the same write, and the existing
running->queued requeue query runs last inside it. Both edges are pinned in
SQL and pinned to their tables (the execution pair beside claim and
BeginRemediation, the step pair in its own test, because the two tables are
different tables), so a query edit cannot move a write off a table.

Deliberately running-only, per the PRD's letter: pending rows never persist
outside StartStep's own transaction, so a crashed attempt leaves only running
rows, and a finished step is never rewritten. The interrupted steps' events
render as the PRD's interrupted -- distinct from cancelled, which an operator
or parent asked for, and from failed, which the step reported.

The wait:true-callee and agent-child sweeps ride #1216's tree, and the
dashboard's ListSteps read is plan item 7; both untouched here, and the
RecoverStale signature and RPC are unchanged.
2026-09-27 06:47:29 +10:00
sam fe2a3a7565 Merge crew/pi-dashboard-sweep: CancelExecution as the single cancel path for daemon stop and operator actions 2026-09-27 06:37:10 +10:00
sam 36981c2024 feat(statestore): CancelExecution, and one cancel path for daemon stop and operator actions
Plan item 5 of docs/prds/execution-tree-state-machine.md (archie-core-1217).
Until now a stop was a context cancel plus a caller-side transition, and the
step rows a worker still held running could never be told: the execution moved
while the work carried on, and the old interrupt-first ordering existed only
because the record could not defend itself. The step table can: the PRD's
ordering -- the store is the record, the context cancel is the delivery --
became safe the moment a worker's next step write fails ErrStaleTransition
against a cancelled step.

- storecontract.ExecutionCanceller and the CancelExecution RPC: one
  transaction moves every non-terminal StepExecution of the execution's
  current attempt to cancelled (one event row each, in the same
  transaction), and the execution itself to the status the operator action
  names, under the shared transition table with its audit row. Staleness is
  decided before legality, the way guardTransition decides it. Earlier
  attempts are never rewritten. Deliberately administrative: the
  deny-by-default grant rule covers it, pinned by a test.
- taskactions.Service routes stop, cancel, abandon and reject through it and
  the old Transition/CancelTask combinations are deleted; the daemon's
  in-memory cancel is demoted to the delivery hook the PRD names, called
  after the store record.
- The gateway's chat controller records first and delivers second, the same
  order, and records even when no runtime is wired here (a standalone
  gateway cannot reach the daemon's goroutines): the record is what unsticks
  a lost-cancel task, and the delivery is best effort. StopRunning and
  TaskRuntime.CancelRunningTasks are deleted outright -- no production
  caller remained once the task_action tool owned stopping, and the daemon's
  CancelRunningTasks/runningTasks.stopAll go with them.
- The gateway's chat adapter writes through CancelExecution instead of a
  bare Transition, so chat /cancel and the dashboard's action service land
  on the same path.

PRD decisions recorded here:
- Each cancelled step's event row is stage_finish with {cancelled: true} and
  the reason as its detail -- the exact-one-event-per-step-transition rule
  covers the pending -> cancelled transition too, even for a step that never
  ran.
- A parked cancel carries the needs_human class, matching the Transition
  path this replaces; the transient class stays with parkRunningTask's
  unwind parks, which now meet ErrStaleTransition for cancelled runs and are
  ignored there.
- Cancelling a wait:true callee is deferred to #1216's agent-call children:
  the callee's own tree and the wait flag are what make
  "cancelling a caller cancels each callee it waits on" decidable, and the
  callee writes it cannot fake are this issue's half of the contract.
- RecoverStale's interrupted sweep is plan item 6, untouched here.
2026-09-27 06:34:01 +10:00
sam 2bcfc19837 Merge crew/claude-997: egress credential resolver backed by declared-and-granted run credentials 2026-09-27 06:19:07 +10:00
sam 416df69b00 feat(egress): credential resolver backed by declared-and-granted run credentials
docs/prds/external-agent-harness.md (Credentials) and orgs-and-access.md:
egress.Resolver had no production implementation, and no run carried a
credential naming the org secrets its identity is granted, so a Kit's
required credential@1 was refused at the proxy and no harness run
authenticated (archie-core-egkf.11).

Two things, as scoped (this does not attempt #1026's full run-credential
consolidation replacing WorktreeGrantIssuer/StateStoreGrantIssuer -- that
PRD item is real, separate, and still open; this is deliberately narrower):

1. A run credential naming granted secrets: config.CredentialBinding maps a
   Kit credential@1 service to a secret; config.Config/IdentityConfig gain
   Org and GrantedCredentials (a per-identity allowlist of service names,
   reusing the existing per-identity config-override pattern DiffCapLines
   already uses, not a new Cedar/Authorizer integration -- KindSecret policy
   objects exist in internal/domain/access but assembling a full Principal
   is #1026's job, not a two-line addition here). config.ContainerConfig.
   BoundCredentials computes the declared (Kit) ∩ granted (identity) ∩
   org-matched intersection Sam's own rule requires: neither side widens
   the other, proven by a mutation-checked test flipping each of the three
   independently.

2. egress.GrantResolver: the production Resolver, holding only what a
   caller explicitly Grant-ed one run, replaced wholesale (not merged) on
   a repeated Grant, gone entirely on RevokeGrant. kitrun.Launcher.Launch
   computes the intersection per launch and resolves real values through
   the existing secret registry (SecretResolver), Grants it before the
   proxy session opens, and Release/error-path rollback (a new shared
   Launcher.release) always revokes it.

Course-corrected mid-implementation (flagged by Sam): credential bindings
first landed as a boot-time config.ContainerConfig.Credentials field
captured once into Launcher.Bindings -- exactly the "parses but is not a
resource" trap CLAUDE.md warns about, and inconsistent with agent-profiles
(#1207) making a Kit profile apply without a restart. Rebuilt as its own
live control-plane resource, CredentialBindingsKind ("credential-bindings"),
following the agent-profiles/container-runtime-policies split precisely:
config.ContainerConfig.Credentials is json:"-", [containers].credentials
is only its seed, and kitrun.Launcher now holds *config.Holder (not a
captured slice) and reads Containers.Credentials fresh on every Launch.
Org/GrantedCredentials were already read fresh per dispatch (d.configFor
inside runKitTask, never cached), so no equivalent fix was needed there.

Deliberately not built: identities and grants as their own State Store
resource (orgs-and-access.md's "Org owns ... identities and their grants").
Identities are entirely config.toml-defined today with no control-plane
resource at all; moving GrantedCredentials alone into one would put half
an identity in two places. That migration is identities' own scope, not
credential bindings'.
2026-09-27 06:14:22 +10:00
sam 6c405333b7 Merge crew/pi-dashboard-sweep: step_executions table, StartStep/FinishStep under the run credential 2026-09-27 06:07:08 +10:00
sam 3f0071e27b feat(statestore): step_executions, StartStep/FinishStep under the run credential
Plan item 3 of docs/prds/execution-tree-state-machine.md (archie-core-1220), on
top of the transition tables and ErrIllegalTransition enforcement (1214/1215,
archie-core-qdbo.5):

- Migration 0017 adds step_executions -- id, org_id, workspace_id, execution_id,
  attempt, parent_id, depth, kind, name, called_execution_id, status, detail,
  tokens_used, started_at, finished_at, indexed on (execution_id, attempt, id).
  Ownership fields are stamped from the execution's row; depth is derived from
  the parent, never supplied by a caller. Existing rows gain no backfilled
  steps.
- task.Store (the workflow engine's mid-run facade) gains StartStep/FinishStep
  (5 methods, within the 8 cap), with storecontract.StepRecorder fronting them
  on the server; deadlineStore wraps both with its per-call timeout.
- The store enforces each write as one transaction: the guarded row write
  under the shared step transition table plus the transition's own
  stage_start/stage_finish event row. Staleness is decided before legality,
  the way guardTransition decides it, and the store returns the persisted
  event for the caller's post-commit publish -- the EmitDurable convention
  (the daemon's event sink skips already-persisted rows by assigned ID), which
  is why workflow.Run stops emitting stage events beside the store and no
  longer discards step-write errors: a failed start or finish parks the
  execution, and the stage does not run unrecorded. An interrupted stage
  records interrupted rather than failed; a recording failure on that
  shutdown path is logged and left to RecoverStale, which owns the
  interrupted-execution sweep in plan item 6.
- The run credential of docs/prds/orgs-and-access.md authorises StartStep and
  FinishStep on its own execution only: both requests carry the execution ID
  the grant check verifies (FinishStep carries it because the interceptor
  never reads the database), and FinishStep verifies handler-side that the
  step really is that execution's. authorizesTaskScopedCall's sanctioned
  widenings are now held as a lookup table so the next one stops growing a
  switch.
- The PRD's wire contract is StartStep(execution, attempt, parent, kind, name)
  -> step id; the responses also carry the persisted event (needed for the
  post-commit publish) and FinishStep's request carries execution_id (needed
  for the grant check) -- both noted here as deliberate additions to the PRD's
  shorthand. called_execution_id exists in the table but not yet on the wire:
  its named consumer is the workflow-call recording of plan item 4 (#1216).

Conformance drives both adapters; grant tests pin the own-execution scoping;
the wire sentinel set gains ErrInvalidStep (InvalidArgument, "step execution
invalid") for a step kind no consumer names.
2026-09-27 05:42:32 +10:00
sam c07c04e45a Merge crew/claude-997: 429 for rate-limited webhooks, agent profiles as a live resource, per-stage profile via workflow.call, harness needs enforced at dispatch 2026-09-27 05:27:09 +10:00
sam a6ab4ef538 feat(harness): declare and enforce a workflow's harness needs at dispatch
docs/prds/external-agent-harness.md ("Contract"): workflow definition
validation must reject a stage whose needs the selected harness cannot
meet -- capture tools without an adapter, or a gate retry without a
resume verb. The step vocabulary had no static way to declare either.

Added task.WorkflowInterface.Needs{Captures, GateRetries}, parsed and
validated (GateRetries >= 0) the same way Inputs/Repository already are.
Only a Kit profile is checked against it: an image profile's built-in
agent loop always supports both, so Needs constrains only the harness path.

Two enforcement points, chosen for where each fact is actually known
without a network fetch at save time:
- Captures vs adapter is knowable from config alone (profile.Adapter, the
  agentexec.harnessAdapters table), so daemon.pinTaskProfile checks it
  right where it already resolves the profile (validateProfileMeetsNeeds),
  parking the task the same way an unconfigured profile already does.
- GateRetries vs the Kit's actual agent-sessions resume verb is only known
  once the Kit composition is fetched, which kitrun.Launcher.Launch
  already does -- so kit.ValidateNeeds runs there (new kitrun.Request.
  GateRetries field, threaded from the workflow's parsed Needs in
  daemon.runKitTask) rather than inventing an image-fetching workflow-save
  validator.

Deliberately NOT built: "a Kit profile named by no workflow is a
validation error" (external-agent-harness.md "Selection"). Read literally
("a Kit profile [that is] named by no workflow"), this is a
cross-resource check -- an agent-profiles entry unreferenced by anything
in workflow-definitions -- and no control-plane Definition validator can
see another resource today (Definition.Validate is a pure []byte->error
function by design, matching every existing resource kind). Building
that crossing is a real, separate piece of infrastructure with its own
ordering questions (does defining a Kit profile before its workflow now
fail?), not a two-line addition, so it is left for a follow-on rather
than bolted on here.

Also fixes a test bug caught by rerunning with a short -timeout per
instruction: TestRunKitTaskThreadsGateRetriesToTheLauncher's fake NATS
subscriber never responded, so runKitTask's call into runViaAgent blocked
forever waiting for a reply bounded by a zero (unconfigured) wall-clock
budget. Fixed by responding, matching the sibling test's pattern.
2026-09-27 05:25:39 +10:00
sam 2604cd4cf4 docs(harness): pin per-stage profile override as workflow.call, not a mid-container switch
docs/prds/external-agent-harness.md's "Selection" says a stage may name a
different profile than its workflow's. Investigated before writing new
runtime code, per instruction not to build container-switching machinery:
a Kit task runs in one container provisioned for one profile (Container
layout), so a stage needing a different profile cannot be a mid-container
runner swap without inventing per-stage re-provisioning the PRD does not
ask for and Container layout argues against ("cost scales with the run,
not with how many agents it fans out to").

The requirement is already met by workflow.call plus per-task profile
resolution, both pre-existing: postgres.Store.StartCall stores the
callee's OWN Workflow name (not the caller's), and daemon.pinTaskProfile
resolves a task's profile purely from its own WorkflowDefinitionYAML.
Chaining these means a stage wanting a different profile is its own
callee workflow, started via workflow.call, exactly the way
event-automation.md already describes ("the callee runs as its own run
with its own agent profile").

No new production code, only a PRD clarification (dev-docs regenerated)
plus TestWorkflowCallGivesACalleeItsOwnProfile (daemon_test.go), which
closes the gap between two already-tested facts that nothing previously
stated together: TestWorkflowCallerConformance (staterpc) proves a
callee's Workflow field is independent of its caller's; this proves that
independence is what makes Kit-vs-image runner selection independent too,
composing a caller pinned to an image profile with a real StartCall-
created callee pinned to a Kit profile.
2026-09-27 05:25:39 +10:00
sam cc6d606de4 feat(controlplane): agent profiles as their own live control-plane resource
docs/prds/external-agent-harness.md ("Selection"): a Kit profile is an org
resource that applies without a restart. Profiles were bundled inside
container-runtime-policies (ApplyMode: restart-required), which is correct
for Image/MaxConcurrency/Network but not for Profiles, which nothing
startup-builds: daemon.configFor reads config.Holder fresh per dispatch
(pinTaskProfile -> Containers.Profile).

Split Profiles into its own resource, AgentProfileKind ("agent-profiles"),
ApplyMode: live, seeded from [containers.profiles] and validated with the
same rules the file document uses (config.ValidateAgentProfiles, factored
out of ContainerConfig.ValidateProfiles so the two cannot disagree).
config.ContainerConfig.Profiles is now json:"-" so container-runtime-policies
never carries it (one authoritative resource per field, not two), and
runtime_config.go layers the new resource in by wholesale map replacement
(matching ModelRoleAssignmentsKind's precedent) rather than merging into the
file's map. Added Profiles to reload.go's Containers reloadable-subfield set
to match this.

Deliberately NOT built here: true per-org multi-tenant storage for this
resource (docs/prds/orgs-and-access.md places agent profiles under org
ownership, granted to workspaces). No existing control-plane resource kind
in this registry does real per-org storage yet either -- schedules,
workflow settings, etc. are all single instance-wide documents -- so
agent-profiles follows that same established, tested pattern rather than
inventing org-scoped storage unilaterally for this one resource. Org/
workspace grants over agent-profiles are a follow-on, not a redo: nothing
about this resource's shape needs to change to add that scoping later.
2026-09-27 05:25:38 +10:00
sam de47bf2398 fix(webhook): reject rate-limited deliveries with 429 instead of chat prose or a false 202
Router.Route returned the chat-facing rate-limit prose with a nil error, so
the webhook handler had no way to tell a genuine dispatch outcome from a
rejection: DeliverTo "origin" echoed the prose as a 200 reply, and any
other route got a 202 for an event that was actually dropped before
reaching the LLM, so the source never retries it.

ChatReply now carries RateLimited, set by a new Router.RouteResult (Route
is now a thin wrapper over it) so chat channels that render Text to a
human are unaffected. The webhook handler checks it and answers 429,
matching the precedent internal/webhookguard.RateLimiter's other callers
already set.
2026-09-27 05:20:30 +10:00
sam b8f5d0fc3d fix(archied): republish the config snapshot when live settings apply
applyWorkflowExecutionSettings swapped the running config with cfgHolder.Set,
so the dashboard's published projection kept the previous budgets until the
next reload. Route it through publishConfig like every other config change.

Fixes #1148
2026-09-27 05:09:24 +10:00
sam 64cc0a5e29 Merge crew/pi-dashboard-sweep: container document shape, systemd READY, capture route constant, contract tests 2026-09-27 05:04:57 +10:00
sam d6f33ddd11 Merge crew/codex-1184: provider secret resolution test, watch outage reporting, projection parity guard 2026-09-27 05:04:43 +10:00
sam 1e669b4a9f test(controlplane): guard mirrored settings projections 2026-09-26 21:02:16 +10:00
sam c3175c6939 fix(webui): mount the capture intake route from the receiver's constant
The bypass mux mounted captureintake's route from a local literal that
duplicated captureintake.Path, with a comment acknowledging the drift risk:
the kind of duplication that silently stops matching after a rename
(archie-core-1175). Reference the constant instead, so the receiver owns the
one spelling of the route and a rename there cannot unmount here.

The existing routing tests are the drift coverage: TestCaptureIntakeMountedOnBypassMux
drives Handler() with a POST to the real path, so a rename on either side that
stopped matching would fail it; no new test is needed. This gives internal/webui
its first infrastructure import -- the deleted literal existed so webui could
mount an http.Handler without depending on the receiver's concrete package, but
mounting by the owner's constant is exactly the boundary the intake cutover
drew: webui mounts and reads, captureintake owns the write path.
2026-09-26 20:44:40 +10:00
sam 7a38d9b79f fix(deploy): announce systemd READY from archie-gateway and archie-state-store
2fcc32d8 gave archied sd_notify: one READY=1 when the run loop starts serving.
RunGateway and RunStateStore serve contracts and health surfaces of their own --
the State Store even takes -ready-addr for a readiness HTTP listener -- but told
systemd nothing, so run as Type=notify either would hang until TimeoutStartSec
and be killed in a restart loop while perfectly healthy (archie-core-1174).

Both now announce at the moment each declares itself serving, the same notion
archied's runLoop announces beside healthSurface.markServing -- no second
definition of started. The Gateway announces from its serving tail
(serveGatewayListener, extracted from RunGateway), after the listener is bound;
the State Store announces after its optional surfaces have started, because a
readiness surface that fails to bind fails the boot and READY must not precede
it, and before serveStateStore, which begins accepting the moment it is called.
No unit file changes Type=notify for them; the helper already lives in package
archied beside both entry points, so no move was needed.

Tests follow the notify pattern the daemon's announcement already has: the
Gateway test drives its serving tail over a bound loopback listener with a
stub contract and judges READY against a real Snapshot RPC on the same socket;
the State Store test drives the real RunStateStore boot over a pgtest database
and waits for the datagram. Both failed red before the announcement existed --
no datagram within the window -- and pass after.
2026-09-26 20:39:56 +10:00
sam b6357c8fd4 fix(archied): report workflow settings watch outages 2026-09-26 20:38:48 +10:00
sam 5f5494893c test(store): a resource request ID is idempotent per kind
The per-kind request-ID dedup was fixed in 9cd6a2aa for the SQLite store and
carried into the PostgreSQL rewrite (038b8035) from day one: ResourceByRequest
filters WHERE kind = $1 AND request_id = $2 and resource_history carries
UNIQUE(kind, request_id). What neither rewrite kept is the test that pins the
cross-kind half of the contract -- the deleted internal/store suite had one, and
the Postgres suite only covers same-kind replay.

Pin it, and prove the failure mode it guards against: with the kind filter
dropped from the query, a request ID reused across two kinds silently returns
the first kind's history row under the second kind's write -- wrong kind, wrong
value, no error (archie-core-1179's latent hazard). Restore the filter and both
kinds write their own revisions, with per-kind replay still idempotent.
2026-09-26 20:29:49 +10:00
sam 2c4d8af59e test(controlplane): refuse a resolved provider snapshot at the seed
archie-core-1000's failure mode was silent persistence: provider-settings seeded
from an already-resolved snapshot stored the process-local ARCHIE_PROVIDER_<hash>
env name with no api_key_ref, and once the resource outranked the file no later
boot had a reference left to resolve. The producer was fixed in ff77612b and the
stored shape is refused in 093e677a, but nothing pinned the seed path's own
refusal: ImportConfig over a resolved snapshot must skip the kind, store nothing,
and report why -- the State Store still starts and the file document stays in
force -- rather than wedging on it or storing it.

Pin that contract, and prove the refusal comes from the guard: with
rejectBootDerivedProviderEnv removed the test fails with 'provider-settings was
stored from a resolved snapshot'.
2026-09-26 20:25:05 +10:00
sam ce7478664a test(scheduling): pin the schedule interval's duration contract
scheduling.Duration landed in 5e95ee66 (archie-core-1169) with no test over the
JSON contract the schedules document and the jobs table both depend on: the
interval marshals the human string time.ParseDuration reads, unmarshals both
that string and the nanosecond count every schedule stored before the shape
existed carries, and refuses a non-duration string with ErrInvalidSpec. Pin it,
because a regression here fails silently in the worst direction -- the document
writes a count and an operator is back to typing 1800000000000 for one hour.
2026-09-26 20:18:41 +10:00
sam d1cba5c1ab fix(control-plane): give the container document its own shape
container-runtime-policies seeded and validated config.ContainerConfig directly,
the last resource in the registry whose document was the internal config struct
(archie-core-1171). encoding/json fell back to that struct's Go field names --
Image, MaxConcurrency, LegacyEnabled, Profiles -- the only Go-cased keys the Web
UI still rendered, and case-insensitive matching let a lowercase misspelling
("maxconcurrency") decode as the field while "max_concurrency" was read back
half-applied.

Define the document here instead: containerRuntimePolicies with explicit
snake_case tags and agentProfile at the profile nesting level, the same shape
267d21a2 gave the channel document. The two durations stay config.Duration,
which already writes the string the file accepts; this leak was the keys only.
The mapping to config.ContainerConfig is one function the validator and the
runtime layering share.

Reading a legacy document is deliberate, so it stays strict about everything
else: DecodeRenamingLegacyKeys renames the seven Go-cased keys an existing store
holds (and the four at the profile level), drops LegacyEnabled -- the removed
containers.enabled switch, which had no runtime consumer and no current
counterpart -- and keeps DisallowUnknownFields, because swallowing an unknown
key decodes as unset and an unset image is a broken worker. A misspelling is
refused.

normalizeContainerPolicies, through the Definition.Normalize hook the channel
document already uses, rewrites a legacy document into the current shape on
write, so a stored document converges the next time it is saved. The layering
keeps its profile semantics -- a document that omits profiles (one stored before
they existed) inherits the file's, one that carries them replaces the file's --
and now checks both spellings of the key.

docs/development/control-plane.md's 'adding a database-owned field' still
instructed the untagged practice this class of issue removes; it now names the
wire-shape rule, the legacy-key tolerance and the Normalize hook instead.
2026-09-26 20:18:38 +10:00
sam a83b9afdce test(config): cover stored provider secret resolution 2026-09-26 20:15:32 +10:00
sam 6f0e889bcf fix(archied): extract accessDeps to bring stateStoreDeps under the complexity limit
The equivalent fix was made in the crew/qc8p worktree but never committed there before the merge, so the merge silently carried the pre-fix version through despite a clean, no-conflict merge. Re-applied directly on main; task check clean.
2026-09-26 15:30:19 +10:00
sam 02328c1880 Merge crew/qc8p: archie-core-qc8p 2026-09-26 15:27:12 +10:00
sam ea39923248 test: loosen order- and count-pinned completeness checks, reference defaultContainerImage
Readiness probe test asserts each subsystem registers exactly once instead of
an ordered five-item list. Config descriptor test drops the exact-count check
and its stale settings.js rationale. Container defaults test references the
production constant.

Refs #1229 #1231 #1232
2026-09-26 15:25:02 +10:00
sam 9c5eeba281 chore(notice): attribute the cedar-go dependency (archie-core-qc8p) 2026-09-26 15:23:32 +10:00
sam 68e6dc0229 feat(access): archied access reset --org/--instance on the State Store host (archie-core-qc8p) 2026-09-26 15:23:32 +10:00
sam 9219252bd4 feat(access): the chain at the dashboard, API and dispatch; denial records and health surfacing (archie-core-qc8p) 2026-09-26 15:23:32 +10:00
sam 3de20cdf9e feat(access): the chain at the dashboard, API and dispatch, with denial records and health reporting (archie-core-qc8p) 2026-09-26 15:23:32 +10:00
sam e6a5a9d3d8 feat(access): policy, denial and principal persistence on the State Store contract (archie-core-qc8p) 2026-09-26 15:23:32 +10:00
sam e9fe50b364 feat(access): cedar-go engine for the policy chain, shipped roles and cross-org forbid (archie-core-qc8p) 2026-09-26 15:22:01 +10:00
sam 257a1fbf1f feat(access): policy schema, actions, request assembly and Authorizer contract (archie-core-qc8p) 2026-09-26 15:22:01 +10:00
sam e720d3dcd8 docs(claude): dev-docs pages are mandatory pre-reading, not colour, and carry into subagent prompts 2026-09-26 14:50:58 +10:00
sam ca3b53bccd docs(development): record today's two merge-surfaced bugs and the go-test-cache trap 2026-09-26 14:45:41 +10:00
sam 3b04ac1196 docs(claude): sharpen the test-quality bar against config/DB fixtures and shipped test helpers 2026-09-26 14:40:10 +10:00
sam 9c053def88 fix(workflow): sort the call-cycle walk's DFS roots for a deterministic report
refuseCallCycles iterated calls (a map) in range order to pick its DFS root, so the same a<->b cycle reported as 'a -> b -> a' on one run and 'b -> a -> b' on the next -- flaky in CI (TestValidateCollectionWorkflowCalls/indirect_cycle failed ~40% of local runs) and a genuinely unstable error message for an operator reading it twice. Sort the roots.
2026-09-26 14:05:39 +10:00
sam 4c3d4f94e4 fix(agentworker): give the workflow-call test its own NATS server instead of the ambient default
TestExecuteTaskRequestStartsWorkflowCallCallee built its transport with no URL, so it silently fell through to nats.DefaultURL (127.0.0.1:4222). It passed locally against a developer's own NATS server and failed in CI with no servers available for connection. Start an ephemeral server per the sibling test's pattern and dial it explicitly.
2026-09-26 13:56:16 +10:00
sam fd6b568fa4 Merge crew/t2db-41: archie-core-t2db.41 2026-09-26 13:39:51 +10:00
sam 49c44b4a03 fix(staterpc): drive the workflow-call conformance test's callee through running before completed 2026-09-26 13:39:25 +10:00
sam 3827561ab0 style(workflow): adopt gate formatting simplification in the workflow.call tests 2026-09-26 13:36:41 +10:00
sam 0a05a30df0 chore(docs): regenerate dev-docs index for workflow-calls 2026-09-26 13:36:41 +10:00
sam 4040e42d2b docs(prds): de-date the org-enablement sentence in workflow-calls 2026-09-26 13:36:41 +10:00
sam 2a03741929 test(agentworker): workflow.call callee start through the real State Store gRPC path (archie-core-t2db.41) 2026-09-26 13:36:41 +10:00
sam fb49ebd268 docs(prds): record the workflow-caller pair and grant widening in the State Store contract (archie-core-t2db.41) 2026-09-26 13:36:41 +10:00
sam 17465f240b feat(store): workflow.call contract — callee enqueue, parent-scoped status read, task-scoped grant widening (archie-core-t2db.41) 2026-09-26 13:36:41 +10:00
sam 78833a9c2c feat(workflow): workflow.call step with save-time input and cycle checks (archie-core-t2db.41) 2026-09-26 13:36:41 +10:00
sam 5ca398d0d9 docs(prds): decisive design for workflow.call runtime and save-time checks (archie-core-t2db.41) 2026-09-26 13:36:40 +10:00
sam d42731e5ae Merge crew/qdbo-5: archie-core-qdbo.5 2026-09-26 13:35:04 +10:00
sam 3186184964 feat(controlplane): re-layer model, repository, scheduling and provider settings live on a watch (archie-core-zfb0.1)
Flip provider-settings, model-role-assignments, repository-policies and
scheduling-policy to ApplyMode live, and give the daemon a watch per kind
(keepWatch's reconnection and backoff rules): on a new stored version the
watch re-runs boot.runtimeConfig over the published snapshot and republishes
through config.Holder, keeping last-known-good when the layered document
fails to validate and reporting through apply status.

The stored model-role assignments now own cfg.Models entirely (the map
merge would resurrect a role the store deleted on every re-layering), and a
provider or role update rebuilds the gateway chat runtime's provider set
(swapped runtime, read per turn) and the chat model manager's offered list.
2026-09-26 13:28:01 +10:00
sam 0c14c4b892 feat(statestore): enforce the execution transition table and map ErrIllegalTransition over the wire
Every caller-supplied status write (Transition, ParkTask, Requeue,
RetryTask, BeginRemediation) now checks the shared taskstate transition
table inside the write's transaction, after the from guard decides
staleness. An off-table pair returns the new storecontract.ErrIllegalTransition,
carried over gRPC through mapError/unmapError on (FailedPrecondition,
"illegal transition"). Claim, BeginRemediation and RecoverStale pin
their pairs in SQL; a test pins those pairs to the table so a query
edit cannot move a write off it. Requeue/RetryTask share one guarded
requeue body. (archie-core-qdbo.5)
2026-09-26 13:13:20 +10:00
sam 82dc7641fe fix(postgres): renumber org migrations past 0012, already taken by installed-packages 2026-09-26 11:44:21 +10:00
sam fcc9322237 feat(org): carry task org across the State Store gRPC contract (archie-core-e5fn) 2026-09-26 11:43:10 +10:00
sam 62e9e9cb28 feat(org): idempotency key org/identity/owner/repo/number in one place, task uniqueness to match (archie-core-e5fn) 2026-09-26 11:43:10 +10:00
sam d6e24e1f81 feat(org): run the resumable default org upgrade before the State Store serves (archie-core-e5fn) 2026-09-26 11:43:10 +10:00
sam 643d2ed665 feat(org): Postgres tenant tables, org-aware store and resumable default upgrade (archie-core-e5fn) 2026-09-26 11:43:10 +10:00
sam 9b581a1326 feat(org): tenant boundary domain package — orgs, workspaces, memberships, agent assignments (archie-core-e5fn) 2026-09-26 11:43:10 +10:00
sam 93e96b8de5 feat(storepkg): install digest-pinned packages 2026-09-26 10:48:23 +10:00
sam 4242d94676 chore(release): v1.42.0
deploy / dist-zip (push) Skipped
deploy / gate (push) Failing after 5m36s
deploy / build-and-push (push) Skipped
2026-09-26 10:32:39 +10:00
sam 1358c3d759 feat(prreview): benchmark harness scoring findings on the Martian problems
Scores a reviewer's findings on the 38 runnable Martian Code-Review-Bench
PRs: the deterministic core turns findings into posted comments, an
independent judge model matches them to the goldens, and the run reports
golden micro-recall and golden-only precision. The reviewer is a findings
fixture directory until the pr-review workflow lands.

Run with: task bench:prreview -- -findings DIR
2026-09-26 10:30:12 +10:00
sam 585df0f81e feat(agentexec): output adapters for Codex, Pi, OMP and Copilot CLI 2026-09-26 10:28:40 +10:00
sam a8c8dfbd7d feat(daemon): run a Kit profile's task in its Kit container on the egress path 2026-09-26 10:14:33 +10:00
sam bc215e8daa feat(config): Kit profiles pin a workload Kit and mixins by digest 2026-09-26 09:21:57 +10:00
sam 0d042b72d9 feat(agentexec): run a Kit task's stages on its harness through a named output adapter 2026-09-26 09:20:30 +10:00
sam 5507ded2d5 feat(storepkg): package descriptor with strict decoding and validation 2026-09-26 09:13:39 +10:00
sam 7a54db0cc6 fix(agentexec): count Claude cache tokens as prompt tokens, as the built-in loop does
Claude's input_tokens excludes cache reads and writes; the built-in
loop's Anthropic provider folds them into PromptTokens so budgets count
total prompt size. The harness adapter now does the same, so one budget
means the same on either runner.
2026-09-26 09:11:57 +10:00
sam 4067949ce8 feat(agentexec): parse Claude Code's stream-json output for the harness runner
Pairs tool_use and tool_result blocks by ID into tool-call reports, keeps
the latest session_id, takes the run's usage from the result event and
falls back to per-message usage, counted once per message ID, for a run
killed before its result. Tested on streams recorded from Claude Code
2.1.282 and scrubbed of host detail.
2026-09-26 09:11:57 +10:00
sam 92a9eca12c docs(architecture): state the shipped execution transition rules
The lifecycle block still showed `running -> merged` and never mentioned
`completed`. `running -> merged` is now illegal (taskstate transition table)
and `merged` is reachable only from `pr_open`; a workflow that opens no pull
request ends in the terminal `completed`.

Rewrite the block to the current rules and fold the crash-recovery requeue
into the `running` row it belongs to. Regenerate the committed docs artifact
carried by `task docs:artifact:check`.
2026-09-26 04:01:08 +10:00
sam 30211478c2 test(taskstate): seed fixture task states along the transition table
The execution transition table refuses most of the pairs shipped fixtures
wrote to build a finished task -- running -> merged, queued -> parked,
queued -> waiting_human, queued -> merged -- so those fixtures fail the
moment the store enforces it.

internal/taskstate/taskstatetest seeds a status by walking the table's
legal edges (shortest route, computed from taskstate.CanTransition), so a
fixture cannot write an illegal pair and fails loudly when no route
exists. The fixtures in internal/daemon, internal/app/archied,
internal/webui and internal/infrastructure/postgres go through it, and
the table's own test names running -> merged as refused.
2026-09-26 04:01:08 +10:00
sam 4e9b30d712 fix(daemon): keep a terminal worktree that holds uncommitted work
The cleanup added for no-change runs removed a `completed` task's
worktree whenever it had no PR. agent.run also ends its workflow
`StatusCompleted`, and it works in a real clone whose uncommitted edits
are the deliverable, so the status alone was enough to delete the work:
no commit, no push, no other copy of those edits anywhere.

Cleanup now reads the worktree first and skips a dirty one. A worktree
whose status cannot be read is kept too -- a wrong keep costs disk, a
wrong delete costs the work -- while one that is not on disk has nothing
to keep. The lifecycle fixtures prepare a real clone now, which is the
only shape the daemon ever cleans up, and the cancelled-context test
still cancels only the cleanup call.
2026-09-26 04:01:08 +10:00
sam f7bfd78d5f fix(ui): count completed runs as delivered on the workflows surfaces
The workflows page's per-workflow bar and its 'N of M' text, and the
workflow picker's percent on the new-task form, counted `merged` alone.
A workflow whose runs now end `completed` (a no-change build, a triage
that needed no code) therefore rendered zero delivery beside three
sibling surfaces that already counted both.

The count moves into ui/src/lib/delivered.ts, which GatePulseCard,
ThroughputTiles and TasksSummary now read too instead of keeping their
own copies of the arithmetic. The picker's label says delivered, not
merged: a run that ends completed is not merged.
2026-09-26 04:01:08 +10:00
sam 4f62ce5dfc chore(ui): rebuild the dashboard for the completed count 2026-09-26 04:01:08 +10:00
sam 845b192a89 feat(taskstate): count completed runs in the per-workflow stats
The transition table moved the no-change outcomes to StatusCompleted, so a
run that opens no pull request now ends in a status the per-workflow stats
did not count at all: it was not merged, not in review, not parked, and the
workflows page would have shown it as a run that went nowhere. The count
travels the whole State Store path, since every dashboard consumer reads it
through the gRPC client rather than the local store.

- WorkflowStats filters `completed` beside merged and pr_open; the SQL is
  the count, so a wrong filter reads as zero rather than failing, and
  TestWorkflowStatsCountsCompletedRuns holds it against a real store.
- storecontract.WorkflowStat gains Completed (json "completed"), the proto
  message gains field 9, and workflowStatProto/workflowStatValue carry it;
  TestWorkflowStatProtoCarriesEveryField round-trips every field by name.
- The gateway's chat task report names the status.
- The dashboard counts a completed run as delivered in GatePulseCard's
  totals and badge numerator, and the WorkflowStat/WorkflowStats/WorkflowRow
  interfaces carry the field.
- TestOutcomeSitesAreTransitionsFromRunning is the guard that keeps the
  producer and the table agreeing: it re-reads this package's tc.Outcome
  assignment sites from source and requires each status to be one
  internal/taskstate allows from running, so a new or moved site has to be
  adjudicated against the table instead of discovered on a live run.
2026-09-26 04:01:08 +10:00
sam 8ba0b90861 feat(taskstate): end no-change runs as completed and clean their worktrees 2026-09-26 04:01:08 +10:00
sam 7b86dd6cfe feat(taskstate): transition tables for executions and steps 2026-09-26 04:01:08 +10:00
sam 419334dfa2 fix(archied): resolve stored provider credentials at boot 2026-09-26 03:50:07 +10:00
sam 093e677ad8 fix(controlplane): reject stored boot-derived provider keys 2026-09-26 03:44:40 +10:00
sam 235b9c1a87 refactor(agentexec): own the capture file format in agentexec, not the app layer 2026-09-26 03:30:19 +10:00
sam 37d913c5fd feat(agentexec): serve capture tools to harnesses over MCP
archie-agent mcp is a stdio MCP server, on the official go-sdk, serving a
stage's capture tools and appending accepted calls to a captures file.
The harness runner writes the tool spec and a standard mcpServers config,
registers it through HarnessSpec.MCPConfig, and reads the captures back
into the stage result. The captures file is writable by the harness user,
so the worker validates every record again with the same acceptCapture
the built-in loop now shares, and forged, undeclared or over-cap records
are dropped. A stage with capture tools on a harness without MCP is
refused before it runs.
2026-09-26 03:28:58 +10:00
sam 8274ecbc53 fix(prreview): cluster duplicate findings and read every diff shape
The duplicate merge compared each finding against the ones already kept, so
overlap was transitive only through the survivors: a chain of findings 1-2,
2-3, 3-4 collapsed to one finding or to two depending on the order they were
handed in, and the two readings tied on score. It is a clustering now -- a
canonical sort, then a union of each run of overlapping ranges -- so the
surviving set is a property of the findings and not of the permutation they
arrived in, and a cluster's member is chosen by score and then by the
finding itself rather than by arrival order.

Two things the merge got wrong besides order. The PRD keys duplicates on
(file, overlapping lines, category), not on severity, so Finding carries a
Category and the merge reads it, while the severity now only decides which
duplicate speaks for the cluster. And a cluster is blocking when any member
is, so an advisory duplicate can no longer swallow the merge gate's verdict
and turn REQUEST_CHANGES into COMMENT.

diff.go read only the shape git writes. A plain unified diff -- sections
opened by a --- / +++ header pair with no "diff --git" line -- belonged to no
file and contributed no added lines, a silent narrowing of the diff-rules
gate's input; a file section opens from either now. git's C-quoted paths are
decoded from the diff --git line, the --- / +++ headers and the rename pair,
octal escapes to bytes, because a quoted path is not a path the snapshot has.
FileStatus is derived from every statement the section makes -- new file
mode, deleted file mode, old mode / new mode, rename from / rename to, and
the /dev/null side -- so a binary or empty file, whose patch has no headers
and no hunks, is reported as what it was rather than as a modification, and a
change of object type is the typechange the change capture already persists.
2026-09-26 03:24:40 +10:00
sam 2657b18be7 fix(prreview): order the confidence floor before dedup and merge overlapping findings
Score recorded a finding's duplicate identity before dropping it under its
severity's confidence floor, so a below-floor finding shadowed a later
above-floor duplicate of the same defect. The floor now runs first, and the
merge keeps the higher-scoring of two duplicates, so the result depends on
which findings were given and not on the order they were given in.

The duplicate rule was byte-identical line ranges. The PRD's rule is
overlapping lines: two same-file, same-severity findings whose ranges share a
line are now one finding.

FileStatus said "removed" for a deleted file, a second vocabulary for the
status the repository persists as "deleted". The value says "deleted" now.
2026-09-26 03:24:40 +10:00
sam 8c7ee60270 style(prreview): adopt go fix rewrites in diff stats and snapshot 2026-09-26 03:24:40 +10:00
sam 54ade9713a feat(prreview): deterministic core of the PR review pipeline
Every phase of docs/prds/pr-review-agent.md that can be computed is computed
here, in a package that imports the standard library only: diff parsing with
renames, deletions, multi-hunk files and no-newline markers; directory
clustering; per-language blast radius; evidence packages; scoring,
deduplication, line mapping to diff coordinates and the review event.

The review event is REQUEST_CHANGES when a finding is blocking and COMMENT
otherwise; there is no approving value, because archie does not own the merge
decision.

internal/domain/workflow/prreview is now the one diff parser in this
repository: the diff-rules step's addedDiffLines delegates to it and the
private hunk-header and path helpers it used to carry are deleted, so a
repository rule and a review comment cannot disagree about which line a change
introduced. diff_rules_test.go is unchanged.

Blast radius resolves Go imports through the module path in go.mod, Python
module names, and JavaScript/TypeScript relative specifiers, all against files
inside the snapshot; an import that resolves to nothing there contributes no
edge. Evidence extraction reads through an fs.FS rooted at the snapshot, so
both are tested against fstest.MapFS fixtures.

NOTICE records the derivation from PR-AF (Apache-2.0).
2026-09-26 03:24:40 +10:00
sam e307efe77d feat(container): end the install phase between install and startup hooks
StartKit calls InstallDone after the install hooks, before files and
startup hooks, so the caller moves the egress session to its runtime
policy exactly where the Kit spec ends the install phase.
2026-09-26 03:17:49 +10:00
sam 6143d17caf feat(container): start a Kit container with the worker and harness separated by user
StartKit creates the Kit container with archie's worker as its root
entrypoint and credentials, the Kit's volumes keyed by execution, then
runs install hooks as their users, writes the Kit's files as the harness
user, and runs startup hooks. A failing hook removes the container and
reports the hook's output. The Docker test proves on a real container
that the harness user cannot read the worker's environment, and fails if
the worker shares the harness uid.
2026-09-26 03:17:06 +10:00
sam b54aa00a24 feat(kit): assemble a Kit container's launch from its plan and image
Assemble turns an admitted Kit composition and the workload image's
config into the harness spec (the image's user, never root; the image
env plus the workspace, egress and credential sentinels; the launch
argv and agent-sessions verbs), lifecycle hooks with their declared users
and restricted environments (the image-derived baseline, egress settings,
and only the runtime variables each hook declares), the Kit's files, and
volume names stable per execution.
2026-09-26 03:14:55 +10:00
sam 08d5df9b11 feat(egress): relay forwards the proxy, NATS and the State Store
A Kit task's worker shares the sandbox network with its harness, so it
reaches NATS and the State Store through the relay like the harness
reaches the proxy. archie-agent relay takes repeated -forward
listen=target pairs, binds them all before serving so a port conflict
fails at start, and stops every forward when one fails. RelayArgs builds
the command from the fixed relay ports.
2026-09-26 03:10:11 +10:00
sam 5b6572bcea feat(agentexec): run harness invocations as the Kit's user with no inherited environment
A Kit task runs worker and harness in one container, separated by user:
the worker keeps its credentials as root, and every harness invocation
runs as the Kit's user with only its declared environment. A nil env
would inherit the worker's, so the runner always passes an explicit one;
root is refused as a harness user, and a root worker refuses to start a
harness with no user. The PRD's container layout now says one container
per run, with the relay forwarding the proxy, NATS and the State Store.
2026-09-26 03:08:34 +10:00
sam 606e87d11c docs(skills): lane gates miss the tools module and contract schema 2026-09-26 02:57:14 +10:00
sam 0b24dc8ff0 fix(build): carry the harness runner into the tools module and contract schema
The harness runner made internal/agentexec import go-git, which the tools
module reaches through docsgen, so tools/go.sum needed its entries; tidy
also dropped the stale modernc sqlite requirements. Request gained the
Harness field, so contracts.json is regenerated with the HarnessSpec
schema.
2026-09-26 02:56:56 +10:00
sam e7611903a8 feat(agentexec): harness runner driving a Kit's agent headlessly
A stage whose request carries a HarnessSpec runs the Kit's CLI as a
subprocess in its own process group, with the mission and archie's rules
as the prompt. After every invocation the runner compares HEAD, every ref
and the git configuration, and the worktree against a pre-run baseline:
any ref or config change, a protected-path edit, or a write in a
read-only stage parks the step whatever the CLI claimed. The runner runs
the gate itself and resumes the same session with the gate's output, up
to the gate's failure cap. The wall clock and cancellation kill the whole
process group, so the CLI's children cannot outlive the step.
2026-09-26 02:54:03 +10:00
sam 19e110e68c style(egress): adopt go fix's promoted-field literal 2026-09-26 02:47:15 +10:00
sam f747ff87d0 feat(egress): inject Kit API-key credentials at the proxy
A session carries its run and its Kit's credential@1 requests. The proxy
applies apiKey inject rules only in the credential's phase and only to
hosts its rule names, after the network policy has admitted the request,
so a key never reaches a host its Kit did not declare. The real value
comes from a Resolver that returns only secrets the run credential
carries: a required credential that is unbound or unresolvable stops the
request before anything is sent, and an optional one passes only when it
is genuinely unbound. Named keys appear in the sandbox as a sentinel;
inject-only keys have no presence.
2026-09-26 02:46:40 +10:00
sam 486d5574b3 docs(prds): fit harnesses, steps and the store inside the org boundary and profile model
A harness is an agent profile whose environment is a Kit composition, so
image profiles and existing workflows are unchanged and only Kit runs take
the egress path; the relay replaces the claim that containers reach the
proxy directly. Credentials, step records, store installs and reviews are
org-scoped under the run credential and the Authorizer, and workflow calls
are linked across executions rather than nested.
2026-09-26 02:41:02 +10:00
sam 71435c2bb6 style(egress): adopt go fix's WaitGroup.Go 2026-09-26 02:38:59 +10:00
sam 9b16c0fd64 feat(egress): sandbox networks that reach only the relay
Each sandbox gets an internal bridge on which the host holds no address,
so host services listening on every interface are unreachable; the relay
is attached under a fixed alias and is the one way out. ProxyEnv gives a
sandbox container its proxy URL and CA trust. The Docker integration test
proves allowed egress works and that the proxy listener, host services and
the internet are unreachable directly; it fails if the host-address
inhibition is removed.
2026-09-26 02:38:12 +10:00
sam 4fc06b5d7d feat(egress): relay forwarding a sandbox network to the egress proxy
archie-agent relay listens on the sandbox's isolated network and joins
every connection to one fixed target, the proxy. The relay holds no
secrets and can reach nothing else, so the host needs no address on a
sandbox network at all.
2026-09-26 02:33:41 +10:00
sam 78dd50d60b feat(egress): session-authenticated proxy terminating TLS under the Kit network policy
CONNECT tunnels and absolute-form http requests authenticate to a
per-container session, are checked against the session's phase policy,
and are forwarded with verified upstream TLS. A tunnel serves only its
admitted host: mismatched SNI and Host headers are refused. Upstream dials
refuse loopback, and refuse internal addresses unless the policy names the
exact IP, so an allowed name cannot resolve back into the host.
2026-09-26 02:31:00 +10:00
sam 77a479e99a feat(egress): persistent per-daemon CA issuing cached leaf certificates 2026-09-26 02:27:58 +10:00
sam 6bc7a85404 feat(egress): network-policy@1 matcher 2026-09-26 02:27:25 +10:00
sam a7edc0a5cd feat(kit): admit Kit v3 descriptors against archie's capability support
Decodes published descriptors from the manifest annotation, composes one
workload with its mixins through the Kit spec package, and applies the
runtime's support table: unsupported required capabilities refuse the
launch, optional ones are skipped and recorded, and forge or passthrough
credentials are refused. A composition must carry a headless prompt verb.
2026-09-26 02:23:11 +10:00
sam 1cf2742f54 docs(prds): approve PR review agent and store PRDs 2026-09-26 02:08:13 +10:00
sam 0f6cb5b8a6 docs(prds): store 2026-09-26 02:06:50 +10:00
sam fca30d6445 docs(prds): PR review agent 2026-09-26 02:05:52 +10:00
sam a98ca2c8e9 docs(prds): approve execution-tree and external-harness PRDs 2026-09-26 01:58:29 +10:00
sam 22d36fef75 docs(prds): harnesses run as Kit v3 images behind a credential-injecting egress proxy 2026-09-26 01:54:35 +10:00
sam f74827795d docs(prds): fold review findings into execution-tree and harness PRDs 2026-09-26 01:45:10 +10:00
sam ca8d189f96 docs(prds): agents reach a harness only through a workflow stage 2026-09-26 01:41:12 +10:00
sam 2ee7043daf docs(prds): external agent harnesses 2026-09-26 01:38:14 +10:00
sam bbc39897de docs(prds): execution tree and enforced state machine 2026-09-26 01:34:26 +10:00
sam 6ba43bbf21 Merge pull request #996 from samcharles93/feat/ui-graphite-theme
Feat/UI graphite theme
2026-09-26 01:26:04 +10:00
sam ff77612bfd fix(archied): the State Store seeds provider-settings from the operator's secret reference
configuredSecretRegistry resolved provider keys in place, and the State Store's
copy of the config shared the providers map with b.cfg, so ImportConfig seeded
the process-local ARCHIE_PROVIDER_<hash> env name. Provider resolution now
runs only in the daemon and gateway boot (openStores).
2026-09-25 22:37:27 +10:00
sam 4426c0e685 fix(webui): roles edit in place; embedding picks an embedding-capable provider
A role has one value, so its row is the control instead of an accordion
that reveals the same text. Embedding pairs a provider select, limited to
configured providers whose class the embed package implements (openai,
openai-compatible, gemini, ollama, cohere, mistral), with a model name; the
chat model list never held embedding models.
2026-09-25 20:13:04 +10:00
sam 9627bc411c feat(webui): Models picks from the provider catalog, and enables available providers
archied already finds usable providers (key set in the environment, or
configured) through the model catalog; the published config view now
carries that catalog, providers with their model ids. Settings > Models
offers role models only from configured providers, lists the catalog's
unconfigured providers as available, and adding one carries its class, key
variable and endpoint. Roles and providers are two accordions, each ending
in an add row.
2026-09-25 18:04:46 +10:00
sam 01c98088ae fix(webui): Models page reads as settings, not raw documents
The four roles the daemon reads always show and cannot be deleted;
clearing one unsets it, and custom workflow roles can still be added.
Provider class is a select of the SDK's classes, the provider name is a
heading rather than an input, and a key read from the environment shows
as one line with Set reference instead of an 'unset / unset' reference.
2026-09-25 17:54:18 +10:00
sam 86d4f62bfe fix(webui): drop the static 'Applies after restart' pill from settings headers
It read as an alert that something had changed. Restart needs show where
they apply: in the review drawer for the changes being saved, and in the
Restart pending banner once a saved change is waiting on a restart.
2026-09-25 17:51:54 +10:00
sam 6f2b55960f fix(webui): the live stream reopens after a fatal close; quieter connection status
A non-200 answer to /api/stream (the backend restarting behind a proxy)
closes an EventSource for good, so the top bar read Disconnected until a
reload while every fetch worked. The live-updates store now reopens it
after 1s, doubling to a 30s cap, and resets once live. The connection
status becomes a dot and a label, coloured only when not connected.

History drops the edge fade, which washed out its first and last columns
though nothing overflowed, and its section filter names the section
rather than showing the raw kind.
2026-09-25 17:45:34 +10:00
sam dce3c925c2 fix(webui): cut help text to the facts a label cannot carry
Drops every page subtitle and the hints that restated their label; the
rest become a few words ('Empty: truncate.', '0 = no limit.'). Empty states
and notes shrink the same way.
2026-09-25 17:42:29 +10:00
sam f7074d357f fix(webui): shorter event types empty state 2026-09-25 17:40:11 +10:00
sam 41e5ab32f9 fix(webui): one plain sentence for the empty event types list 2026-09-25 17:39:21 +10:00
sam e44b5398c7 fix(webui): drop the Events description and the captures redaction note 2026-09-25 17:38:02 +10:00
sam 6dcb04c7c0 fix(webui): Events reads as a flow
A Capture → Map → Bind strip with each step's count opens its tab. The
tabs follow that order, sit left-aligned at their own width and carry
count chips; a count that could not be read stays blank. The Inspector
splits into list and detail only when there is a capture to show, and an
empty event-types list explains where proposals come from.
2026-09-25 17:36:05 +10:00
sam d025d4c5be feat(webui): Events header states capture status; copyable capture endpoint
The page says what it is for and whether capture intake is listening,
once that is known, instead of the Inspector repeating the global stream
state. An empty capture list offers the webhook address with a Copy
button.
2026-09-25 16:37:05 +10:00
sam 7555b80f31 feat(webui): New task dialog with workflow cards, recent repositories and run-as identity
Repository with recent ones one click away, the workflow as a radiogroup
of cards showing runs and merge rate, title and instructions, and the
identity (the server requires one) defaulted to the first active actor
under an Advanced disclosure that names it. Cmd/Ctrl+Enter starts the
task and opens it. Replaces the Start work form. Workflows shows an empty
state rather than an editable template when there is none.
2026-09-25 16:34:38 +10:00
sam ceed8b055a feat(webui): Workflows as a list with stats and a tabbed editor
The list shows each stored workflow with its runs, merged-of-runs bar and
average tokens. The editor has Definition (ID and YAML, Validate & save,
Remove, Restore this workflow), Performance (slowest stages and failures
for the selected workflow only) and Runs (its tasks, linking to each).
Restore shipped and New workflow sit in the header. The Start work card
leaves the page: New task in the top bar starts work.
2026-09-25 16:31:42 +10:00
sam f3f3ca90f1 feat(webui): task detail with a parked banner and a right rail
Header: breadcrumb, title, status pill, workflow and forge links, with
Start a new run as the page's one action; a parked task opens with its
park reason in an amber banner. The log/changes/configuration/debug tabs
take the main column; a right rail lists every attempt with its outcome
(replacing the pager inside the stage rail), the selected attempt's
stages, and the task's details.
2026-09-25 16:28:38 +10:00
sam 0bc27ea6da feat(webui): needs-you first Dashboard
The header states what is running and what needs a human instead of a
greeting. A stat strip replaces the throughput tiles. The main column
opens on a Needs you queue: each waiting task with its status, title,
repository, workflow and park reason, an Open link and the actions the
server offers for it. Live activity follows; quality gates and the token
outlook move to a right rail.

A failed task-list fetch no longer reads as an empty list, which would
have told the operator nothing needs them; the header says it cannot
reach archied instead.
2026-09-25 16:25:19 +10:00
sam 049bbf2a7d feat(webui): Plugins and Container runtime settings pages; Advanced keeps only dangerous actions
Plugins: the four extension directories. Container runtime: image, pull
policy (missing or always, the two the daemon accepts), concurrency,
uptime and volume retention as durations, network, and named profiles
with their image and tool allowlist. Advanced now holds only stop and
rollback, and the Managed elsewhere card goes. With every settings kind on
its own page, the generic schema-driven resource editor had no consumer
and is deleted.
2026-09-25 15:32:20 +10:00
sam b5c98a0ccc fix(webui): the legacy config catalog stops advertising fields the control plane owns
skills_dir, plugin_dir, secret_engine_dir and containers.* were listed as
editable in /api/config's schema while the plugin-settings and
container-runtime-policies resources own those values at runtime; nothing
could save them there. Drop them from the catalog, and delete the settings
components that rendered the catalog, none of which any page used.
2026-09-25 15:29:31 +10:00
sam c327f17c35 feat(webui): Identities on the shared components
Replaces raw inputs, buttons and scoped CSS with the shared controls:
lifecycle as status pills, inline rename instead of a browser prompt, and
Retire behind a confirmation dialog.
2026-09-25 15:25:33 +10:00
sam 081e5bbfd9 feat(webui): Task execution, Models and Repositories on setting rows
Task execution: the two time limits as durations over their seconds
fields, steppers for tool steps and gate failures. Models: roles checked
as provider/model and warned when the provider is missing, providers as
cards with class, base URL and key. Repositories: one card per repository
with gate and preflight commands edited as argv tags (duplicates and
commas kept), protected paths, retries and the review, storage and
concurrency switches.

Secret references no longer claim a credential resolved or went missing:
the documents only say a reference is filled in, and an omitted boolean
prop was being read as not found.
2026-09-25 15:23:41 +10:00
sam b1a5954594 feat(webui): Personas and Schedules settings pages
Personas: a filterable list with the default marked, and an editor with
name, a default toggle, the system prompt with a character and token
count, Duplicate and Delete. Renaming or deleting the default keeps the
collection naming one that exists; the last persona cannot be deleted.

Schedules: an empty state, then one card per job with ID, task title,
instructions, when (interval, cron line or a single time) and overlap.
Settings opens on Personas.
2026-09-25 15:14:18 +10:00
sam 9639e7041e feat(webui): Settings > History, and a resizable Settings sidebar
History replaces the Audit card on every settings page: one change log for
all settings, filterable by section, actor and time window, with the
filters in the query so each page's History link opens it filtered to that
page. Rows show the old and new value as a diff and expand to the full
value; Restore still puts a resource back to the version before a change.

The sidebar's edge drags (or takes arrow keys) between 180 and 420px,
resets on double-click and remembers its width per browser.
2026-09-25 15:10:07 +10:00
sam 5b06f0b42a fix(build): task dev starts the State Store and waits for it
Task templates every command, so the PostgreSQL health check's
'{{.State.Health.Status}}' rendered as an empty format string: dev:postgres
always reported unhealthy after 60s, the State Store never started, and the
Gateway and daemon exited on boot or retried against a store that was never
coming. Escape the template, and have dev:daemon and dev:gateway wait for
the State Store's port before starting.
2026-09-25 15:10:00 +10:00
sam 7d37750d40 feat(webui): Channels settings page
One card per channel: set-up channels expand to their fields, the rest
collapse to a row with Set up. Running state shows only when the
messaging service reports it. Telegram token and webhook signing secret
are secret references (an unset signing secret reads as risky); allowed
Telegram users and chat models are tag inputs. Chat session defaults
carry the red unrestricted-filesystem row, max steps with its real zero
meaning (the default of 100), and the rate limit as requests per
duration. Drops the ChannelCard status grid.
2026-09-25 15:10:00 +10:00
sam 7095a583b8 feat(webui): Tools & MCP settings page
MCP servers as editable rows per transport (stdio command and arguments,
HTTP URL, SSE endpoints) with parallel tool calls; MiniMax with its key as
a secret reference; web fetch with byte, duration and a danger-toned
private-networks toggle, its fields disabled while it is off; tool output
limits with a token estimate.

Fixes sticky positioning across the app: the frame and main used
overflow hidden, which made each a scroll container that never scrolls,
so the Settings save bar and sidebar never stuck. Both now clip instead.
2026-09-25 15:09:53 +10:00
sam cb6b902f97 feat(webui): Scheduling policy settings page
Its own page under Settings > Agents instead of a generic card on Advanced:
trigger as a segmented control with the label field shown and required
only when the trigger needs one, the six forge state labels as a fixed
table, a max-retries stepper and a duration input for the poll interval.
Settings pages leave room below the last setting so it can be scrolled up
to eye level.
2026-09-25 15:09:45 +10:00
sam 74aaf39be9 feat(webui): one save flow for Settings
Edits live in the control-plane store as drafts against the version they
started from, so they survive moving between Settings pages. A sticky bar
counts unsaved changes; the review drawer shows a field-level diff per
section with Revert, and saves the sections one at a time, stopping at the
first failure. A conflicting save rebases the draft onto the latest value.
Restart pending is read from apply status. Per-card Save buttons, Live and
Version badges go; leaving Settings with edits asks first.
2026-09-25 15:09:38 +10:00
sam 4690e822d8 fix(webui): overflowing nav rows fade at the edges instead of showing a scrollbar
The top bar and the narrow Settings tabs use shadcn-vue's scroll-fade-x,
which fades each edge in as there is more to scroll to. The Settings
sidebar marks the current page with the raised background alone.
2026-09-25 15:09:31 +10:00
sam 90e222b8ec feat(webui): Settings sidebar shell
Settings is one top-bar link. Its pages render inside a shell with a
grouped sidebar (Agents, Integrations, Runtime) that turns into tabs at
narrow widths, and content capped at 960px. Channels sits under
Integrations.
2026-09-25 15:09:24 +10:00
sam 1bb52fe8c7 feat(webui): five-place top bar with Settings, New task and one connection pill
Dashboard, Tasks, Workflows, Events and Settings replace the Work, Agent
and System menus. Configuration pages move under /settings/* with
redirects from their old paths; Logs and Appearance leave the bar and stay
reachable from Jump to, the Dashboard and the account menu. New task opens
the Start work form in a dialog and lands on the new task. One pill reports
the live stream's state.

Drops docs/prds/dashboard-navigation-groups.md: web UI design is not
tracked in PRDs.
2026-09-25 15:09:18 +10:00
sam e3bf3b7584 feat(webui): add stock and registry primitives for the redesign
Stock shadcn-vue: number-field, tags-input, radio-group, breadcrumb, kbd.
From archie-component-registry: duration-input, byte-size-input,
segmented-control, secret-reference, setting-row, stat-strip, status-pill.
2026-09-25 15:08:59 +10:00
sam 6d8fe247a7 feat(webui): swap the violet palette for the Graphite theme
Neutral warm greys with one swappable sage accent replace the violet canvas,
washes and brand gradient. IBM Plex Sans/Mono replace Geist. The light theme
keeps the same rules with a darker sage. No layout changes.
2026-09-25 15:08:59 +10:00
sam 464ccf83fa Merge pull request #995 from samcharles93/fix/webui-single-stream
fix(webui): multiplex dashboard live updates over one stream
2026-09-25 14:14:58 +10:00
sam 067d365f84 fix(webui): multiplex dashboard live updates over one stream 2026-09-25 14:05:34 +10:00
sam e12aeb8493 fix(build): stamp every service binary with the installer's version flags 2026-09-25 11:10:32 +10:00
sam 7577ae66a7 docs(design): add UI redesign handoff bundle
Add a self-contained design handoff under docs/design/ui-redesign/ (README,
build prompt, HTML mockups, design-canvas sources, CSS and JSON theme
tokens). docs/design/ is held back from the published docs sets like
docs/inspiration/: it is input to building the UI, not a page to read.

Remove the superseded service-decomposition research from docs/inspiration/.
2026-09-25 11:10:32 +10:00
sam 8fea8e8686 feat(controlplane): field-level sys_audit table, audit view on settings pages, whole-task time limit 2026-09-25 09:54:30 +10:00
sam 49d7527f1c fix(webui): open control-plane watch streams before the first change 2026-09-25 09:37:36 +10:00
sam 81862273c0 fix(taskactions): abandon leaves the forge issue open 2026-09-25 08:59:54 +10:00
sam 07d5a7a3cc fix(webui): keep the stage selection across inspector tabs 2026-09-25 08:52:40 +10:00
sam bb3e7b76e8 fix(webui): render sub-second durations as under 1 s 2026-09-25 08:49:52 +10:00
sam cc33dfea54 fix(webui): show park reason, one attempt control in the rail, tighter stage selection 2026-09-25 08:45:31 +10:00
sam 73e718dea4 fix(webui): use Tailwind's standard breakpoints everywhere 2026-09-25 08:37:47 +10:00
sam d01a3c4647 fix(daemon): park a task whose agent container exits before replying 2026-09-25 08:31:46 +10:00
sam 55ad93e8e3 fix(webui): drop ok badge from stage rail, pack run tabs, scope note on changed files 2026-09-25 08:26:04 +10:00
sam 459bbcd5fc docs(prds): reflow playbook-expression-syntax
deploy / gate (push) Failing after 5m32s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-25 02:00:16 +10:00
sam a4d98786a1 chore(release): v1.41.2
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
deploy / gate (push) Failing after 3m35s
2026-09-25 01:58:54 +10:00
sam aa24551d98 fix(update): treat the runtime as the release version; stamp it in dist-zip
The update check still read the retired archie/v* tag stream, so a host on
1.41.1 was offered runtime 1.35.0, and the installer built the agent image
from that stale tag. Both now use the release's archied/v* tag. The dist-zip
build also stamps runtimeVersion, so /version stops reporting 'dev'.
2026-09-25 01:58:20 +10:00
sam cacf25039e test: remove events-page source-string test
deploy / gate (push) Failing after 3m49s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
It asserted on text in the router, nav and Events page sources rather than
on behaviour.
2026-09-25 01:35:26 +10:00
sam 35dd7489dd test: remove layout-pinned route-registry and task-meta fixture tests
TestDashboardPagesRegistryCoversEveryRoute parsed ui/src/router/index.ts as
text, and TestTaskMetaPayloadMatchesFixture plus ui/test/task-meta-snapshot
pinned a formatted JSON fixture. They failed on formatting, not behaviour.
2026-09-25 01:32:20 +10:00
sam be1b3aa6a1 chore(release): v1.41.1
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
deploy / gate (push) Failing after 5m34s
2026-09-25 01:29:59 +10:00
sam 065606b2a5 fix(ci): make the gate tolerate formatting and give deploy a PG 18 client
The page-registry test parsed the route table one line per route and the
task-meta fixture was byte-compared, so the prettier reformat broke both.
The registry test now splits route objects and ignores comments; the
fixture compares compacted JSON. Also drops a stale router comment that
described the removed redirects, rebuilds ui/dist, regenerates the
contracts artifact, keeps prettier off generated output, and installs
postgresql-client-18 in deploy.yml's gate as quality.yml already does.
2026-09-25 01:29:23 +10:00
sam a22030bd65 chore(release): v1.41.0
deploy / dist-zip (push) Skipped
deploy / gate (push) Failing after 3m29s
deploy / build-and-push (push) Skipped
2026-09-25 01:12:45 +10:00
sam a16a17309c Merge pull request #994 from samcharles93/chore/remove-legacy
chore: remove legacy config, compat shims and the SQLite import
2026-09-25 01:11:26 +10:00
sam 0d35e753b5 refactor: format markdown files using prettier, fix spelling concerns, reduce Taskfile bloat 2026-09-25 01:10:28 +10:00
sam c1cd5c8f5b chore(state-store): remove the one-time SQLite import and db_path
Every install serves from Postgres, so the legacyread/legacyimport packages,
the archie-state-store import command, the boot gate that refused to serve
over unimported SQLite files, and db_path (which only located those files)
go. Migration 0010 drops the import_completion table.
2026-09-25 00:40:48 +10:00
sam 4479f212d7 chore(webui): remove legacy hash and Events-tab redirects
The #/path rewrite and the /captures, /mappings and /bindings redirects only
kept pre-cutover bookmarks working.
2026-09-25 00:36:43 +10:00
sam 1340036546 docs(site): publish the event automation product overview 2026-09-25 00:34:57 +10:00
sam 9fd966d6b0 docs(readme): explain event automation and organization model 2026-09-25 00:23:16 +10:00
sam 6e46d4dec9 docs(readme): introduce project overview and setup guide 2026-09-25 00:06:21 +10:00
sam f36e17796c chore(staterpc): remove deprecated unary capture RPCs and Binding.secret
ListCaptures and ListUndispatchedCaptures had no callers once the client
moved to the streaming RPCs; they were kept only for mixed-version rollouts.
Binding.secret was unused since signing moved to Source; its number and
name are reserved.
2026-09-25 00:00:16 +10:00
sam e5105280ad chore(config): remove token_env aliases for forge, artifacts and telegram
Each credential is now only a {engine, key} secret reference. A stale
token_env in a file is reported at startup as an unrecognised key.
nats.token_env stays (no secret-ref form), and providers.api_key_env stays:
it is the carrier the resolver writes each resolved key's env name into.
2026-09-24 23:58:26 +10:00
sam 9a0efa295e chore(config): remove dead [agent], [oidc], [image] and containers.enabled keys
None had a production consumer: [agent] and containers.enabled were decoded
only so old files kept loading, [oidc] was never read (archie-ui takes OIDC
from flags), and [image] was validated but no provider exists.
2026-09-24 23:52:06 +10:00
sam 862b3560e1 Merge pull request #993 from samcharles93/pg/foundation
Postgres persistence and event automation
2026-09-24 23:30:45 +10:00
sam 58eac052a8 fix: add pg to path for CI quality check 2026-09-24 23:16:25 +10:00
sam 0909ebfe60 ```
chore(deps): bump Go module dependencies in go.sum
```
2026-09-24 22:42:07 +10:00
sam ae5e0ad835 fix(ci): install PostgreSQL 18 client tools 2026-09-24 22:40:54 +10:00
sam b9c1663d64 test: check scanner error in openSSEStream 2026-09-24 22:27:56 +10:00
sam 25668c1226 chore: update deps and remediate GO-2026-6253 2026-09-24 22:27:08 +10:00
sam d299448de1 Merge branch 'main' into pg/foundation 2026-09-24 22:21:24 +10:00
sam 440d2e8e46 fix: reject values that exceed Int32 for all SQL LIMIT params 2026-09-24 21:45:27 +10:00
sam c971348a86 docs(development): organise the guides by area
One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
2026-09-24 21:05:29 +10:00
sam 21e4d47907 docs(development): checklists for every kind of change
docs/development/ holds one page per kind of change (settings, State Store
and persistence, task lifecycle, workflows and steps, event automation,
dashboard, agent execution and containers, processes and wiring, merging
work), each naming every layer the change must reach and pointing at the
document that owns the design. The docs build puts them in the development
set; docs/index.md and CLAUDE.md link them.

Also adds the container-profile case to the validator agreement test, the
check the profiles work skipped.
2026-09-24 21:03:34 +10:00
sam 21f333a13e fix(controlplane): stored container policies replace file profiles; add profile image and workflow examples
A stored container-runtime-policies document that carries Profiles now
replaces the file's profiles instead of merging into them, so a profile
deleted in the dashboard stays deleted; one stored before profiles existed
still inherits the file's. Profiles drop their json tags so the stored
document keys them like its other fields.

Adds examples/profiles/Dockerfile.agent-net (agent image plus network
lookup tools) with a build-only agent-net compose service,
examples/workflows/firewall-investigate.yaml with a test that parses every
example against the registered step vocabulary, and names the postgres
service in the compose header.
2026-09-24 20:58:08 +10:00
sam d8bec1ae06 fix(eda): clear completed tasks; document the tool allowlist's reach and unchecked profile names
ClearTerminalTasks now deletes completed tasks, with a test that holds its
SQL list to taskstate.Terminal. The AllowTools comment says agentloop's
built-in file tools are outside the allowlist and why. The PRD model
diagram lists only what a profile holds (image, tools), and the profile
field and AgentProfile say a workflow's profile name is resolved at
dispatch, not when the workflow is saved.
2026-09-24 20:53:51 +10:00
sam d320a1a01a feat(eda): workflow inputs, optional repository and agent profiles
Workflow definitions declare inputs, repository (none, optional or
required; default required) and profile. A binding assigns each input
from a mapped parameter or a constant and may take its repository from a
parameter, which must name a configured repo; both are checked when the
binding is saved and again at dispatch. Inputs travel as structured task
data (tasks.inputs, the task brief, and a JSON block in the agent's
mission), never as body text.

A task with no repository runs in a per-task scratch workspace with no
clone and no publication grant. The agent.run step runs one mission
without a repository and finishes the task in the new completed status.

Agent profiles live under [containers.profiles.<name>]: an image and an
allowlist over the tools archie adds (MCP, scripts, plugins).
[containers].image is the default profile; an unconfigured profile parks
the task. The workflow is now pinned before the container starts so the
profile can choose its image.

Also stop two archied tests writing embedded NATS state into the package
directory, refuse an empty state_dir for embedded NATS, and drop the NATS
store files an earlier lane commit tracked.
2026-09-24 20:29:33 +10:00
sam 74197cd0fc Merge branch 'worktree-agent-a96503bc8828fc104' into pg/foundation 2026-09-24 19:47:03 +10:00
sam be9a45ad2d Merge branch 'pg/foundation' into worktree-agent-a96503bc8828fc104
# Conflicts:
#	docs/data/generated/dev-docs.json
#	internal/app/archied/state_store_test.go
#	internal/app/archied/state_store_toolcalls_test.go
#	internal/contracts/state/v1/state.pb.go
#	internal/daemon/dispatch_bindings_test.go
#	internal/infrastructure/bindingcipher/cipher_test.go
#	internal/infrastructure/captureintake/receiver_test.go
#	internal/infrastructure/edastore/contracts_binding.go
#	internal/infrastructure/edastore/testsupport_test.go
#	internal/infrastructure/postgres/edastore.go
#	internal/infrastructure/postgres/edastore_test.go
#	internal/infrastructure/staterpc/error_test.go
#	internal/store/store.go
#	internal/webui/api_binding_test.go
2026-09-24 19:47:00 +10:00
sam e57221f34b docs(store): drop residual SQLite references; fix lane lint findings 2026-09-24 19:39:06 +10:00
sam a377da6678 Merge branch 'worktree-agent-a62864fcfbdb43f5a' into pg/foundation 2026-09-24 19:34:44 +10:00
sam 30834223dc Merge remote-tracking branch 'origin/pg/foundation' into worktree-agent-a62864fcfbdb43f5a
# Conflicts:
#	internal/app/archied/state_store.go
#	internal/contracts/state/v1/state.pb.go
#	internal/daemon/daemon.go
#	internal/infrastructure/captureintake/receiver.go
#	internal/infrastructure/captureintake/receiver_test.go
#	internal/infrastructure/legacyimport/load.go
#	internal/infrastructure/postgres/edastore_test.go
#	internal/infrastructure/postgres/postgresdb/edastore.sql.go
#	internal/infrastructure/postgres/queries/edastore.sql
#	internal/infrastructure/staterpc/client.go
#	internal/infrastructure/staterpc/values.go
#	internal/webui/api_binding.go
#	internal/webui/api_binding_test.go
#	ui/dist/assets/index.js
#	ui/src/bindings/BindingEditor.vue
#	ui/src/bindings/BindingRow.vue
2026-09-24 19:34:31 +10:00
sam 9864766804 docs: describe the PostgreSQL-only stores, state_dir and the import-only db_path
Architecture, deployment, installer, skill and PRD text now name the Postgres
State Store, the offline recovery commands on database_url, state_dir for host
state, and db_path as the legacy-file locator for archie-state-store import.
Finalised PRDs, CHANGELOG, docs/news and docs/archive are unchanged records.
2026-09-24 14:51:48 +10:00
sam 64f863f228 docs(proto): name the Postgres State Store in the state contract comments 2026-09-24 14:47:53 +10:00
sam 89f5b70287 feat(config): add state_dir for the daemon's host state
The embedded NATS store and endpoint file, the task-log registry and the
readiness disk probe resolve from state_dir (default: the data home's archie
directory) instead of the directory of db_path. db_path now only locates the
legacy SQLite files for the one-time import and its boot gate.
2026-09-24 14:47:21 +10:00
sam 4f8290567b docs(bindings): bindings apply per event type with a filter; mappings count matches 2026-09-24 14:46:44 +10:00
sam fbcb7032e5 feat(webui): bindings pick an event type and filter, mappings show their type and match count 2026-09-24 14:46:21 +10:00
sam ae552db7e0 refactor(store)!: remove the SQLite task store, the PocketBase event store and the SQLite session store
The State Store, event capture and Gateway conversations already serve from
PostgreSQL. This deletes internal/store and internal/infrastructure/edastore,
the SQLite gateway session store and openProductionTaskStore, and the -db
recovery path on a legacy task file; backup, restore, validate and rollback
work on the database database_url names.

- The binding-secret cipher moves to internal/infrastructure/bindingcipher and
  ToolCall to internal/infrastructure/postgres.
- NewSessionStoreMemory is now a pure in-memory store that passes the shared
  SessionStore conformance suite.
- Tests run against PostgreSQL through internal/infrastructure/postgres/pgstore;
  legacyimport/legacyfixture writes the legacy files the import and the boot
  gate read.
- The cron dialect is owned in internal/domain/scheduling, so
  github.com/pocketbase/pocketbase and pocketbase/dbx leave go.mod.
  modernc.org/sqlite stays for the one-time import (legacyread).
- The UI and Messaging architecture gates ban the Postgres and legacy readers
  in place of internal/store.
2026-09-24 14:43:50 +10:00
sam dda12dcdba refactor(scripts): drop the SQLite task-database backup from the installer and watchdog
The pre-update PostgreSQL snapshot is the only backup; the watchdog restores
binaries and never the database.
2026-09-24 14:43:25 +10:00
sam fec0ea1f4e feat(eda): mappings per event type, match counts, several bindings per source
A mapping belongs to an event type and is checked against its inferred
schema on save. Each event a mapping resolves is counted once in
mapping_matches (migration 0008), read back as match_count and
last_matched_at. Bindings carry an optional CEL filter over the mapping's
parameters, checked on save. The per-source unique indexes are dropped:
every armed binding whose mapping matches the capture's event type and
whose filter admits it dispatches once, claimed in the per-binding ledger
before its task is enqueued. The State Store gains RecordMappingMatch and
the new mapping and binding fields.
2026-09-24 14:42:58 +10:00
sam 0cabe5fd65 merge: t2db.40 sources and signing into pg/foundation
Resolves against t2db.36: captures carry both event_type and unsigned (proto field 10), the State Store serves sources and event types from the Postgres EDA store, the capture row shows event type and signature together, and the staterpc sentinels map both ways from one table.
2026-09-24 14:38:40 +10:00
sam a383f6820f refactor(gateway): replace the SQLite session store with an in-memory store 2026-09-24 14:26:42 +10:00
sam 10023b8bc2 refactor(scheduling): own the cron dialect instead of pocketbase tools/cron 2026-09-24 14:26:41 +10:00
sam 6adbdc55a9 feat(eda): sources own signing, with UUIDv7 paths and approved unsigned option
A source is the capture endpoint: a UUIDv7 path by default or a unique
URL-safe custom path, signed by default with an Archie-generated secret
(encrypted via the bindings cipher), or unsigned after an approval.
Intake verifies X-Hub-Signature-256/X-Signature-256 against the source
secret before redaction; an unauthenticated event on a signed source is
captured but never dispatched, an event on an approved unsigned source
dispatches and is marked unsigned. The binding secret is retired; migration
0006 derives sources from existing binding and capture source strings,
moving each binding's secret onto its source. SourceStore crosses the
State Store gRPC contract. The dashboard gains a sources panel and flags
unsigned in the capture inspector, binding list and task timeline.
2026-09-24 14:26:21 +10:00
sam d8d7c5a1f2 fix(legacyimport): imported captures take the new event_type column's default 2026-09-24 14:26:18 +10:00
sam f279e3b9c0 Merge branch 'worktree-agent-a88b86b51f454341b' into worktree-giggly-marinating-lamport 2026-09-24 14:21:53 +10:00
sam 1c03c6bc1a feat(webui): inspector shows proposed and unidentified events, names and pastes event types 2026-09-24 14:21:21 +10:00
sam c1e2a14390 feat(staterpc): event type RPCs and capture event_type on the wire 2026-09-24 14:21:21 +10:00
sam 80b0d1f78d feat(eventtype): infer event types from captures and gate dispatch on identification 2026-09-24 14:21:20 +10:00
sam 00e3520a1e Merge branch 'worktree-agent-a2b33953bdffebf56' into worktree-giggly-marinating-lamport
# Conflicts:
#	docs/data/generated/dev-docs.json
#	internal/app/archied/state_store_pool.go
2026-09-24 10:06:00 +10:00
sam 368e33a9a5 feat(archied): serve the State Store, event store and Gateway conversations from Postgres
The State Store's task and event-capture stores and the conversation store
read by archied and served by archie-gateway now open on database_url.
Every serving process refuses to start when legacy SQLite data exists and no
import completion is recorded, naming archie-state-store import; a fresh
install records completion itself. The Gateway holds its Postgres serve
claim for its lifetime and releases it before the pool closes.
2026-09-24 10:01:54 +10:00
sam a86be2fa49 Merge branch 'worktree-agent-a091696d945ed3377' into worktree-giggly-marinating-lamport
# Conflicts:
#	cmd/archie-state-store/recovery.go
2026-09-24 09:56:10 +10:00
sam 5e6c3fa3d3 Merge pull request #992 from samcharles93/feat/865-dashboard-vocabulary
feat(webui): serve change statuses and the config schema through /api/task-meta
2026-09-24 09:50:19 +10:00
sam 1b5ba30113 feat(archied): recovery commands on PostgreSQL; fail-closed pre-update snapshot, no automatic schema rollback
Without -db, backup/restore/validate/rollback resolve database_url from the
config and work on the whole PostgreSQL database. Restore claims every service
role; rollback claims the State Store role; validate refuses a schema newer
than the binary. The installer refuses a daemon update it cannot snapshot
first; the watchdog never restores the database and prints the explicit
offline restore instead.
2026-09-24 09:50:10 +10:00
sam 5009288729 fix(state-store): real-process tests give the State Store a database_url 2026-09-24 09:48:58 +10:00
sam d2b55e941a Merge branch 'worktree-agent-a7131b2ebdff5f551' into worktree-giggly-marinating-lamport 2026-09-24 09:46:02 +10:00
sam 35b0a305eb feat(state-store): one-time import of the legacy SQLite stores into Postgres
archie-state-store import copies the State Store task database, the
PocketBase event store and the Gateway conversation store, all named from
db_path, into Postgres in one transaction. The bead asked for an archied
command; offline maintenance of a store belongs to the binary that owns it,
so it sits beside backup/restore/validate/rollback instead.

It refuses rather than guesses: while the state-store or gateway ownership
claim is held, when a domain it imports already holds rows (an allowlist of
that domain's tables, checked after Migrate), on a completed prior import,
on FK orphans, alias case collisions, duplicate bindings, events whose (at,
id) order microsecond storage would change, schema gaps, and any value the
target column cannot hold, naming table, row, value and rule. Historical ids
are kept and every identity sequence is set from AUTOINCREMENT's high-water
mark. After loading it compares key sets, event order, resource blobs and
binding secrets byte for byte and the next id of every sequence, checks the
source files were not written while read, and only then writes an
import_completion row (migration 0005) in the same transaction.

postgres.ImportComplete and legacyimport.HasLegacyData are the two halves
of the boot gate: legacy data without a completed import must not serve.
2026-09-24 09:45:26 +10:00
sam 651021130d feat(postgres): whole-database backup and offline restore on pg_dump/pg_restore
Restore claims every service role (state-store and gateway) non-blockingly
and refuses if any is held or the claim cannot be checked; it drops tables a
later migration added before pg_restore --clean so a restored schema matches
the snapshot. Backup validates the archive before replacing the previous one.
Ports the store's write-side clip, park-class and transition-audit coverage
from internal/store.
2026-09-24 09:32:39 +10:00
sam 0f88e08913 Merge remote-tracking branch 'origin/main' into worktree-giggly-marinating-lamport 2026-09-24 09:31:28 +10:00
sam 5687d1b04e feat(webui): serve change statuses and the config schema through /api/task-meta
Closes #865. The dashboard hand-copied the Change* file-status ids and events.ConfigCapturedSchema. /api/task-meta now serves both; the Vue dashboard renders ui/src/lib/task-meta-snapshot.ts until the served catalog lands. The Go handler is pinned to internal/webui/testdata/task_meta.json and the snapshot is pinned to that same fixture, so a one-sided rename fails a test.
2026-09-24 09:31:09 +10:00
sam 671441ac4b feat(legacyread): read-only readers and import verification for the legacy SQLite stores 2026-09-24 03:28:42 +10:00
sam 8b006b35aa fix(postgres): lock keys follow D3.7/D4.3; event reader never sees a later id before an earlier one 2026-09-24 03:23:38 +10:00
sam c367a9e606 Merge pull request #991 from samcharles93/eda/event-automation
Eda/event automation
2026-09-24 03:10:54 +10:00
sam 88030e32e9 Merge pull request #990 from samcharles93/sams-cleanup
Sams cleanup
2026-09-24 03:08:53 +10:00
sam 5cbc9f9d6c feat(postgres): event inserts take a transaction advisory lock so ids commit in order 2026-09-24 03:01:41 +10:00
sam 20929cd444 feat(postgres): State Store claims serve ownership with a session advisory lock 2026-09-24 02:57:38 +10:00
sam fe73025d47 refactor(postgres): resources and statestore tests use storecontract, not internal/store 2026-09-24 02:47:06 +10:00
sam 4ce4b46977 style(postgres,gateway): adopt task fmt rewrites from the lane merge 2026-09-24 02:41:34 +10:00
sam f3a1ef6de1 fix(postgres): one isUniqueViolation after merging the EDA and status lanes 2026-09-24 02:33:52 +10:00
sam ecc1997384 Merge branch 'run/pg-w2-5' into worktree-giggly-marinating-lamport
# Conflicts:
#	internal/infrastructure/postgres/postgresdb/models.go
2026-09-24 02:31:06 +10:00
sam 5e1c43f1c5 Merge branch 'run/pg-w2-3' into worktree-giggly-marinating-lamport 2026-09-24 02:30:51 +10:00
sam dfed51547c Merge branch 'run/pg-w2-2' into worktree-giggly-marinating-lamport 2026-09-24 02:30:48 +10:00
sam cb1cd62eea Merge branch 'run/pg-w1' into worktree-giggly-marinating-lamport 2026-09-24 02:30:47 +10:00
sam feeaa16c7b feat(postgres): wire the State Store to Postgres — DB URL, fail-closed pool, composition seam
Wave 1 of the Postgres migration (archie-core-7r0x.9). This is the shared shape
every port lane builds on; nothing here switches a live path to Postgres yet.

- config: add `database_url` beside `db_path` (config.go), mark it bootstrap-only
  in denied_keys, expose it in the webui StorageView/config schema, and add it to
  config.example.toml plus all deployments/*.toml.
- docker-compose: add a postgres:18 service; `task dev` (dev:postgres) brings it
  up and waits for it before the State Store boots.
- archied: `openStateStore` now opens and migrates the process-scoped Postgres
  pool via `openStateStorePool`. The State Store fails closed (D1.2) when
  database_url is absent or invalid rather than fall back to SQLite; serving
  against Postgres later requires an import-completion record (D1.3), which is a
  later lane's gate, not this one.
- composition seam: task-store construction (state_store_task.go) and EDA-store
  construction (state_store_eda.go) are extracted from openStateStore, with the
  pool open in state_store_pool.go. This is a behaviour-preserving refactor only
  — no store, interface, error, ordering or logging change — so L1 and L2 build
  against separate files instead of sharing state_store.go.

Tests: fail-closed pool behaviour is pinned (absent/invalid URL); the State Store
boot/restart tests now run against a throwaway Postgres 18 container (pgtest
TestMain). Scoped test command and module-wide build pass; see lane report.
2026-09-24 02:18:56 +10:00
sam cadf248b1f feat(postgres): port events/identities/status surfaces, fix shipped defects
CHECKPOINT -- the full State Store port is in progress; this lands the
compile-clean core so the review pass has a diff to work against. Remaining:
advisory-lock ownership, event-insert serialization, maintenance, and the
ported test battery.

Two corrections to behaviour that already shipped, not new features:
- UpdateTask wrote park_reason raw where SQLite applies clip(park_reason,
  4000); the PostgreSQL adapter now clips before binding (clip.go).
- tasks.review_cursor existed on the protobuf wire and in workflow.Task but
  not in the PostgreSQL schema; 0004 adds it as a NEW migration rather than
  amending 0001 because a dev database may already have applied 0001 and
  goose tracks version numbers, not checksums.

Also moves the control-plane Resource/ResourceWrite types and their sentinels
into storecontract so the postgres package can stop importing internal/store
(they stay aliased there for daemon callers).
2026-09-24 02:17:44 +10:00
sam f3471131ff feat(postgres): port EDA store to Postgres (captures, mappings, bindings, ledgers, tool_calls)
L2 of the PocketBase->Postgres migration (bead archie-core-7r0x.3): a new
Postgres-backed EDA adapter (postgres.EDA) plus its goose migration
(0002_edastore.sql) and sqlc queries (queries/edastore.sql), satisfying the
same storecontract surfaces as internal/infrastructure/edastore.Store so the
cutover wave can swap them behind the contract. The PocketBase opener in
internal/app/archied/state_store.go is untouched: production still opens
SQLite, and the cutover waits for the one-time import.

Three recon-found hazards, each pinned by a test, not a comment:

1. Empty-secret early return. applyBinding deliberately never writes the
   secret column when the incoming secret is empty, so an edit form that does
   not echo the secret must not blank an armed binding's HMAC key. The
   UpdateBinding query keeps the stored secret via
   `secret = CASE WHEN $secret = '' THEN secret ELSE $secret END`; pinned by
   TestUpdateBindingEmptySecretPreservesStored (raw column unchanged across an
   empty-secret edit).

2. Unique-violation detection by SQLSTATE. isUniqueViolation previously grepped
   the driver's error text for "unique"/"already exists"; Postgres reports
   SQLSTATE 23505 and the text match would not fire, losing ErrAlreadyDispatched.
   The adapter detects by pgconn.PgError.Code == "23505"; pinned by
   TestIsUniqueViolationDetectsBySQLState (23505 with a message lacking those
   words is detected; a non-23505 whose text says "unique" is not).

3. One-binding-per-source / one-armed-binding-per-source were read-then-refuse
   with no transaction and a non-unique idx_bindings_source_status. Made them
   constraints: UNIQUE(source) plus a partial UNIQUE(source) WHERE
   status='armed' (the full unique subsumes the armed rule today, kept explicit
   for a future matcher extension). A concurrent insert for one source yields
   exactly one success and one ErrBindingOverlap; pinned by
   TestConcurrentInsertBindingSameSource.

Dispatch ledgers kept exactly: UNIQUE(binding, capture) and
UNIQUE(playbook_id, playbook_version, event_id, action_id); binding_version is
stored but deliberately not part of the key (pinned by
TestBindingDispatchVersionBumpDoesNotPermitRedispatch). The cipher is
unchanged: AES-256-GCM, key = SHA-256(material), decrypt stays in the store and
the gRPC wire still carries plaintext.

Notify is left as an injected callback (EDA.SetNotify) and is NOT wired to
LISTEN/NOTIFY. It is dead code today: edastore.Config.Notify is omitted at its
only production construction and no consumer maps binding_changed/
mapping_changed, so building a LISTEN/NOTIFY path would be building for a
consumer that does not exist. Wired or not is a separate decision.
2026-09-24 02:17:31 +10:00
sam 710fbab094 feat(gateway): port session store to Postgres
Move sessions, messages, turns and full-text search off the per-process
SQLite file onto Postgres behind the existing messaging.SessionStore
contract. New adapter internal/gateway/session_store_postgres.go, sqlc
queries/gateway.sql, migration 0003_gateway.sql, regenerated postgresdb.

FTS5 becomes a STORED generated tsvector column over (sender, text) plus
GIN. plainto_tsquery is the tsvector analog of ftsMatchQuery's
quote-escaping: query text is parsed as plain text, never query syntax, and
the surviving terms are ANDed. MessagePage.Truncated stays always-false on
Postgres too: the result set is counted exactly.

On internal/domain/messaging/session_store.go: this is a comment-only edit
to the MessagePage.Truncated doc comment (the brief's own "change the
comment" instruction). It changes no type, method or value, so L2 and the
import lane still build against an unchanged contract and the wire is
unaffected. No interface widened or altered.

Semantics preserved verbatim:
- The timestamp clamp is SQL-atomic (INSERT ... SELECT MAX(ts)+1). Appends to
  one session are serialised by a transaction-scoped advisory lock keyed on
  the session so two concurrent appends cannot read the same MAX(ts); a Go
  clamp would race (proven by the new cross-handle monotonicity test).
- Session ordering is GREATEST(last_active_at, created_at) with a matching
  expression index.
- ClaimTurn is insert-first (ON CONFLICT DO NOTHING), with a race test across
  two handles.

State outside the store is NOT made shared by this change, and none of it is
silently improved or worsened:
- sessionTracker.active, Router.titling and per-session persona selection are
  in-memory, per-process caches; a second Gateway still diverges from the
  first.
- messaging.Turns lanes and the per-process recovery latch stay per-process.
- RecoverTurns still fails every turn owned by another process, so a second
  Gateway starting would still fail the first's in-flight turns. This lane
  does NOT make that safe and does not try to: the safeguard is D4.1's
  single-Gateway advisory serve-ownership lock (not implemented here), which
  prevents a second Gateway from serving at all. The turn-recovery semantics
  are left exactly as they were.

Production openers still return SQLite; this lane adds the adapter and tests
only. The cutover and the state-sharing questions remain follow-up work.
2026-09-24 02:17:23 +10:00
sam 038b8035ff feat(postgres): preserve resource write semantics 2026-09-24 01:38:40 +10:00
sam a69f9c81c2 feat(postgres): State Store schema and sqlc queries, with the claim path proven on PG 18
goose migration 0001 lands the twelve State Store tables on Postgres, and sqlc generates the task queries from it. Two behaviours that genuinely differ from SQLite are pinned by tests against a real PG 18: claiming takes the oldest queued row with FOR UPDATE SKIP LOCKED (without the clause a second claimer blocks, which the test shows by timing out), and every column behind a Go int is bigint -- SQLite's INTEGER is 64-bit, and the chat issue-number allocator seeds at 10^15, which does not fit an int4.

task db:generate writes the committed postgresdb package; task db:check regenerates it in the gate, as proto:check and ui:check do.

The remaining store methods (events, resources, identities, the status tables) still run on SQLite: porting them is the rest of archie-core-7r0x.2.
2026-09-24 01:18:19 +10:00
sam c6df4b4a54 refactor(state-store): remove the PocketBase admin view
stateadmin served read-only PocketBase views over the SQLite task file on -admin-addr. PocketBase is SQLite-only and the State Store moves to Postgres (archie-core-7r0x), so the view goes; operators use a Postgres tool of their choice.
2026-09-24 01:09:42 +10:00
sam c620e00396 feat(postgres): pool that refuses servers before PG 18, goose migrations under an advisory lock, testcontainers harness
internal/infrastructure/postgres opens a pgx pool, checks server_version_num >= 180000, and applies goose migrations with a Postgres session advisory lock so processes starting together apply each migration once. internal/infrastructure/postgres/pgtest starts postgres:18 through testcontainers per test binary and gives each test its own database. Adds jackc/pgx/v5 v5.11.0, pressly/goose/v3 v3.28.0 and testcontainers-go v0.44.0. The database URL config, sqlc, the Compose service and the ownership lock move to archie-core-7r0x.2, where they have consumers.
2026-09-24 01:03:08 +10:00
sam 01586f1630 docs(prds): orgs, workspaces and access control
Approved design for orgs and workspaces, people and agents as identities, the Cedar policy chain (instance with network rules, org, workspace, identity and workflow, object), server-derived credential scope, and one run credential per agent run. Secrets move from agent profiles to identities; event-automation.md is marked superseded where it said otherwise.
2026-09-24 00:34:14 +10:00
sam d03e7fdef4 docs: regenerate dev-docs.json for the event automation PRD 2026-09-24 00:30:22 +10:00
sam f4d20cfe0a fix(build): task check runs in ~27s cold, ~12s warm
task test runs -short with the test cache on; task test:full keeps the
uncached run. The 50s keepalive proof skips under -short (the deploy
workflow's full go test still runs it). Sleep-bound archied watch tests
run in parallel, and the read-only gate steps run concurrently after fmt
and proto:check. ui:deps is run: once so the parallel UI steps install once.
2026-09-24 00:29:07 +10:00
sam 94ca015070 docs(prds): event automation — identified events, typed parameters, purpose-built agents 2026-09-23 23:50:27 +10:00
sam 7c6e7d54ad fix(webui): binding ids are strings and a new binding gets a generated signing secret
bindingPayload sent mapping_id as Number(id), which is 0 for every current mapping id, so every binding created or edited from the dashboard was refused. A new binding now starts with a generated secret the operator copies to the sender; an edit keeps the stored one unless replaced. The dev proxy keeps the browser's Host and forwards /webhooks. Checked with typecheck, task ui and task test:ui; the full gate was not run.
2026-09-23 23:50:27 +10:00
sam 86690ef73e fix(bindings): a new binding is created pending approval
Nothing moved a binding out of draft except an unrelated edit, so a newly created binding could not be approved and the dashboard showed no Approve button. Draft is removed; existing draft rows are promoted to pending_approval when the EDA store opens.
2026-09-23 23:13:49 +10:00
sam 528d6c4be2 fix(webui): dev proxy keeps the browser's Host, and editor errors show beside Save
Vite's proxy shorthand sets changeOrigin, so every mutation through the dev server failed archie-ui's same-origin check. The mapping and binding editors rendered their refusal at the top of a scrolled dialog, out of view of the Save button.
2026-09-23 22:58:45 +10:00
sam 891970f1ad feat(eda): playbook.Load findings name the offending action, when or args line 2026-09-23 22:42:14 +10:00
sam 3b303b353f refactor(playbooks): serve on go.lsp.dev/protocol instead of hand-written LSP types
Replaces sourcegraph/jsonrpc2 with the go.lsp.dev stack (protocol, jsonrpc2, uri). The exit notification now ends Serve; closing the connection from inside the exit handler deadlocked.
2026-09-23 22:34:33 +10:00
sam fda2c51f6d feat(playbooks): archie-playbooks serve, a language server publishing lint findings as diagnostics 2026-09-23 22:22:56 +10:00
sam 61dd33edce feat(playbooks): lint an EDA playbook directory with -eda-dir 2026-09-23 22:11:01 +10:00
sam 534153d50a feat(eda): reject an args value whose checked CEL type cannot fill its Args field 2026-09-23 22:05:50 +10:00
sam 2bc4b8db32 feat(eda): run action playbooks at pin time through the at-most-once dispatch ledger 2026-09-23 22:00:52 +10:00
sam 6046948ff0 docs(eda): playbook dispatch rows are retained until an explicit delete 2026-09-23 21:52:10 +10:00
sam 4237b560b0 fix(eda): type-aware actions classifier, one stable-identifier grammar, loader tests that fail for the named reason 2026-09-23 21:48:52 +10:00
sam 3a4af23caa feat(workflow): routing and playbook findings carry the key's file:line 2026-09-23 21:41:56 +10:00
sam 288e9ea370 fix(webui): move the live stream to /api/stream so reloading /events serves the page 2026-09-23 21:16:29 +10:00
sam aa054f8109 feat(webui): two-section quality gates, sweep the restating card prose
The quality gates card stacked its number and rows across the full row
width -- the rate pinned to the left edge, the counts to the right --
which reads as two places at once. The card now has two internal
sections, left to right: the rate, and the per-workflow rows that
explain it; the row collapses under 720px.

Also swept the restating descriptions: 'Work that passed its quality
gates' under Quality gates, 'Archie needs these before it can work on
its own' under Finish setting up, 'Next 30 days at the current rate'
under Token outlook, 'Last 50, newest first' under Live activity. A
title and a sentence that restate each other are noise; the table or
chart says the thing. CapturesCard's redaction note is a security fact,
not restatement, and stays. The unconfigured versions state is one
quiet line, not a card with a title, a description, and a sentence.
2026-09-23 15:29:28 +10:00
sam 5e82a18697 feat(webui): compact quality gates card, drop the setup celebration, hover nav
Three dashboard refinements from operator feedback:

The setup panel's completed state was celebration prose -- a full card
saying setup was done, occupying a grid cell until dismissed. A
configured daemon is the absence of a problem: the state machine now
only distinguishes incomplete from omit, the checklist returns on its
own if setup regresses, and the dismissal machinery is deleted with it.

'Gate pulse' led with a donut whose entire payload was one number, and
the name was decoration too. The card is 'Quality gates' now: the pass
rate as the number itself beside its run count, per-workflow rows as
tight hairline rows instead of muted pills, and the parked line is gone
-- Throughput's Needs-you tile already speaks for parked tasks, from the
statuses themselves. base/Gauge.vue had no other consumer and is deleted.

Topbar nav groups open on hover and close on leave, with a short grace
period bridging the trigger-to-content gap; click and keyboard
activation keep working through the same controlled open state.

The live activity feed scrolls within its card (previous commit); the
health row's cards are now compact enough to match it.
2026-09-23 14:53:40 +10:00
sam d76bf2be67 fix(webui): bound the live activity feed to the card
Group rows multiply with the number of interleaved tasks -- one group
per task per detail shape -- and nothing capped the card's height, so a
live instance rendered the dashboard ~4,700px tall with a void beside
the token outlook card. The feed now scrolls inside a 28rem region with
a sticky header: newest events at the top, the rest in place, and the
RIGHT NOW section's two cards stay comparable in height.
2026-09-23 14:42:43 +10:00
sam 475dc7c097 docs(releasing): record that main and the branch diverge on every release
The release commit lands on main, because tools/release.sh refuses to run
anywhere else, while the working branch keeps advancing. So after every release
neither tip is an ancestor of the other and --ff-only fails in both directions
-- a refusal that reads as "the tree is not ready" when the tree is fine. It
cost confusion on both v1.38.0 and v1.40.0, and both times the correct answer
had to be re-derived from the commit graph.

Documents the order that keeps a conflict off main (merge main into the branch
first, then fast-forward), and the trap that catches people looking for main: a
detached worktree sitting at the same commit accepts --ff-only and moves
nothing, which looks like success.
2026-09-23 14:42:32 +10:00
sam 19cf9ae2ab chore(release): v1.40.0
deploy / gate (push) Failing after 5m33s
deploy / dist-zip (push) Skipped
deploy / build-and-push (push) Skipped
2026-09-23 13:30:57 +10:00
sam 67c2dff3e1 merge(release): bring the v1.39.0 release commit into sams-cleanup
The branch and main diverged at 8faa0f6a: the release commit was cut on
main while the branch kept advancing with the park-classification wave.
Merging main here first, so main can fast-forward to the branch tip
without a merge on the release side. No content conflicts: the release
commit touches the changelog and news artifacts only.
2026-09-23 13:23:16 +10:00
sam 10dd85443d feat(staterpc,daemon): park classification on the wire and at the park sites
Domain fields ParkClass/RemediationRounds landed in d6f61c2c; this is
the wire and daemon half. Task gains park_class (32) and
remediation_rounds (33) and maps both directions; the classified park
write crosses the wire as ParkTask on a narrow TaskParker contract
(TaskLifecycle stays under the 8-method cap), with conformance
coverage local + grpc including the stale-guard sentinel and
needs_human normalization. Every daemon park site now states its
class: terminal for a repo that left config and a retired identity,
transient for the environmental parks (worktree, storage, grants,
taskrun), and identityMayAct returns the class beside its reason.
2026-09-23 13:18:08 +10:00
sam 53bdbd3309 fix(staterpc): carry park class and remediation rounds across the wire
d6f61c2c added Task.ParkClass and Task.RemediationRounds to the domain
without the wire half; the parity guard went red. Add the two proto
fields (32/33) and map both directions in values.go.
2026-09-23 13:10:31 +10:00
sam 5d6fbd5c30 fix(release): CI owns the release stamp; :latest moves only from a release
Two beads, one root: four sites stamped a version and only two of them were CI.

`Taskfile.yml`'s build and `install.sh` derived GATEWAY_VERSION/RUNTIME_VERSION
from `git describe`, so a from-source build claimed a release it was not
running, and the stamp became a function of the commit graph -- the one input a
content-checksum build cache cannot see. An empty commit moved `git describe`
while `task build` reported "up to date" and shipped the previous stamp
(archie-core-pdq2). Both sites now stamp `dev`: a source build says so, and the
version a release carries is written into the artifact CI publishes. That
removes the non-file input rather than caching it, and traceability for a local
build is the checkout it came from.

`deploy.yml` published `:latest` from any push to main, so a release's own
stamping survived only until the next ordinary commit -- minutes, in an active
repo -- and a host deploying :latest reported dev, leaving the update path
unable to tell current from stale (archie-core-i5nb). `:latest` now moves only
from a commit that IS a release; every other build publishes `:edge` (mutable,
newest main) and `sha-<commit>` (immutable). A host that runs releases follows
`:latest`; a host that tracks main follows `:edge`, which RELEASING.md now says.

Verified: `task build` reports `archied dev`; the new workflow test fails
against the old workflow on all five guards and passes after; deploy.yml
parses; install.sh passes `bash -n`.

Gated with `task check` (exit 0) at 8faa0f6a -- the v1.39.0 base, CI-green --
with these five files applied. It is NOT gated at HEAD: HEAD carries an
unrelated red, `TestTaskProtoCarriesEveryDomainField`, because d6f61c2c added
ParkClass and RemediationRounds without the proto mapping. This change neither
causes nor fixes that.
2026-09-23 13:09:01 +10:00
sam 3940487335 feat(webui): show the park class beside the Parked badge
The classification rides the API for free (taskView embeds task.Task),
so this is the read side only: a parked row shows what kind of
intervention it needs -- needs you, transient, terminal -- as a chip
with the answer in its tooltip, instead of a bare Parked every time.
Non-parked rows render nothing.
2026-09-23 12:57:27 +10:00
sam d6f61c2c6f feat(workflow): typed park classification and split remediation budgets
The F2+F3 schema wave from the auto-fix/resume investigation, sequenced
together as one migration. Every failure funneled to one parked status
with free-text ParkReason, and Task.RetryCount doubled as the
operator-retry budget and the review-remediation round budget -- so N
operator retries ate the remediation budget, a repo-level round cap
could re-park a task an operator had just legally retried, and no
surface could answer what a park needed from an operator.

Park class (F2): a producer-recorded vocabulary in taskstate --
needs_human (the default, so an unclassified park always reads as
operator-actionable), transient (environmental; a requeue can succeed),
terminal (retrying is pointless). Recorded at the park site, never
inferred from reason text; NormalizeParkClass makes unknown values
persist as needs_human. Transition-to-parked defaults the class, so
every existing unclassified park site reads correctly with no call-site
churn; the classified ParkTask write follows for parks that know
better. Requeue, RetryTask and BeginRemediation clear the class back to
the default with the reason.

Split budgets (F3): Task.RemediationRounds is the remediation's own
budget; RetryCount stays the operator's. The round-cap stage counts and
caps rounds; operator retry keeps counting RetryCount and can drive a
task to dead without touching rounds. remediation_rounds is a
presence-gated migrator column written through Update.

Known state: proto fields, the ParkTask RPC, the staterpc mapping and
the daemon-side park-site classification follow in the wire half of
this wave (the proto parity test is intentionally red until then).
2026-09-23 12:55:03 +10:00
sam ee78bfa7bc chore(release): v1.39.0
deploy / dist-zip (push) Skipped
deploy / gate (push) Failing after 5m48s
deploy / build-and-push (push) Skipped
2026-09-23 12:53:48 +10:00
sam 8faa0f6a30 feat(daemon,forge): the review-reaction producers
Sequencing steps 6 and 7 of pr-review-remediation.md: the consumer
landed in 052e350b, and these are the two sources that feed it.

Webhook (decision 2, low latency): the GitHub receiver decodes
pull_request_review and pull_request_review_comment events behind the
existing HMAC verification and publishes the same typed reaction the
poller produces, keyed source-independently so PublishUnique collapses
the two sources. Only submitted/created carry a verdict to remediate;
edited and dismissed are acknowledged. Reaction deliveries are
rate-limited per source (decision 6's 'add when the receiver gains a
second event family'), and the reaction path carries no dispatch
predicate -- eligibility is the consumer's owned-PR lookup.

Poll (both forges, the no-webhook backstop): one shared scan over all
pr_open tasks, each with the forge client its own identity owns
(reconcilePRs's shape), listing reviews and comments since per-task
persisted high-water marks and skipping the owning identity's bot user
(decision 5's own-comment exclusion, which the poll is positioned to
make identity-correct).

The cursors are two, not one: review IDs and comment IDs are independent
forge sequences, and a combined high-water mark would silently skip
reviews once a larger comment ID landed. watch_comment_id -- dead since
the comment-watch design it was created for never shipped -- carries the
comment cursor; review_cursor is a new presence-gated migrator column,
and SetReviewCursors is its guarded RPC (pr_open only, so cursors never
move under a run that owns the task). forge.ReviewComment gains ReviewID
so a comment is collectable into its review's unit (decision 5) on both
forges, and forge.Review gains Body so poll-delivered reviews carry
their summary.

Note: the store/proto/facade half of this work landed early in a65eae24
under a release session's message -- a shared-checkout collision, kept
rather than rewritten; that commit carries the review_cursor migration
and the SetReviewCursors contract, this one carries the producers.
2026-09-23 12:41:53 +10:00
sam 59614cc63f style(update): adopt the formatter's alignment in the watchdog test
task check's fmt pass rewrites this literal; the version committed with
the readiness-wait change predated that pass.
2026-09-23 12:30:10 +10:00
sam 40f2e13f0b fix(docs): derive the docsite artifact from the commit, not the working tree
docs:artifact:check regenerated the artifact from a directory walk of
docs/, which also sees an UNTRACKED page. The committed artifact then
looked stale and the gate demanded a regeneration that was already
correct -- one that would have committed a page belonging to no commit.
It cost two sessions in one day: a migration branch, and an unrelated
writer adding a PRD.

Enumerate through `git ls-files --cached` instead, so a page the commit
carries is required in the artifact and a working-tree scratch file is
not. The index counts as well as HEAD, deliberately: a page staged for
this commit is about to be carried by it. Outside a git work tree there
is no commit to disagree with, so the walk is kept and says so on stderr
rather than passing as the stronger guarantee.

Test fails against the walk with the gate's own message ("is stale;
regenerate it by running ...") and passes against the enumeration.
2026-09-23 12:29:29 +10:00
sam a65eae2458 docs(agents): a bead never carries production instance detail
Beads sync to a Dolt remote, so anything written into one is published.
Two beads filed earlier today named an operator host, its internal
address and its filesystem paths -- the tracker was treated as a private
store, which it is not.

The rule is stated where the tracker is described, next to the existing
one about .beads/ never reaching a commit, because it is the same class:
the tracker is not a private store. Host-specific facts belong in the
operator's memos instance, which a bead may point at.
2026-09-23 12:29:29 +10:00
sam 052e350bf1 feat(daemon): wire the review-reaction consumer to remediate runs
The remediate workflow was registered but had no trigger: the reaction
stream was provisioned, the envelope, resolver and owned-PR lookup all
landed, yet nothing consumed the stream (pr-review-remediation.md's
sequencing left the consumer for this step). The daemon now drains the
reaction stream each cycle, before the task drain, so a reaction can be
claimed in the same pass that carried it.

Per decision 3, the store's owned-PR lookup is the authorization
boundary: an unmatched, merged or closed PR drops with a counter, and a
public reaction can never start an agent against a foreign repository.
Per decision 5, a review is the unit of remediation -- its comment
events are appended to the unit while it is queued and dropped once the
run is claimed (the round cap bounds the exchange); a standalone comment
is its own unit of one; approved reviews never remediate; and archie's
own comments, matched on the owning identity's bot user, are excluded so
its replies cannot retrigger it.

The guarded BeginRemediation/UpdateReviewPayload store methods are the
dedup: the pr_open -> queued transition carries the review unit in the
same write, so re-delivered reactions fail the status guard instead of
starting a second round. Both are new StateStoreService RPCs following
the Requeue shape, covered by the local/grpc conformance battery.
2026-09-23 12:08:44 +10:00
sam 2393ec6dae docs(prds): approve the master-detail run page PRD
The maintainer approved task-run-master-detail.md after the
adversarial-review round; its status moves Draft -> Approved while the
work it describes is completed and verified.
2026-09-23 11:36:16 +10:00
sam 00cfd6bda0 fix(webui): reset the stage filter on an attempt switch
A stage filter is a command scoped to the attempt it was made on: the
rail set it against that attempt's stage list. selectAttempt and
performRetry left filters untouched, so a stage selected on attempt 2
carried into attempt 1 -- a same-named stage there rendered as selected
without ever being commanded, or the log stayed narrowed to a stage the
new attempt does not have. The stage filter now resets when the selected
attempt changes; the level filter is attempt-agnostic and survives.

The master-detail PRD absorbs the adversarial review's verified findings:
the reload claim is narrowed to the URL contract (filters are not in the
URL), the unimplemented scroll and pinned claims are dropped, the
unnamed-stage and level-filter contracts are stated, the rail inventory
is corrected, and the acceptance list gains criteria for the
command-not-binding rule, attempt-switch reset, and keyboard selection.
2026-09-23 11:31:58 +10:00
sam 89fc8fc7f1 fix(webui): group live activity by payload, not by event kind
The first cut grouped consecutive same-kind events, but the real noise
shape is an interleave: one background cycle emits curator_run,
session-memory and curator_action events carrying the same payload, and
kind-keyed grouping left them all visible. The grouping key is now the
rendered detail plus the task, so one cycle of noise collapses to one
row regardless of which internal kind emitted each event, while events
carrying different information never merge. Verified against a live
daemon: 50 background events collapse to one expandable row.
2026-09-23 11:20:45 +10:00
sam fd3f661a73 feat(webui): split the task run page into a master-detail pane
The five tabs gave the stage rail less than a third of the screen and
disconnected the log stream from the stage that produced it. The stage
rail is now the page's master pane, always visible; the four context
panels are the inspector and own the tab bar. Selecting a stage commands
the inspector to the log tab with that stage's filter set; clicking the
selected stage clears it. Selection is a command, not a binding -- the
operator can change the filter afterwards.

No endpoint, RPC or contract changed. tab=stages still resolves, to the
log tab; every inspector tab and attempt deep-link survives a reload.
Below the shell's 900px frame breakpoint the rail stacks above the
inspector. Design of record: docs/prds/task-run-master-detail.md (Draft,
per-run panel contracts unchanged from task-run-detail.md).
2026-09-23 11:20:45 +10:00
sam cdedbaa1f5 feat(webui): collapse runs of background telemetry in live activity
The feed's 50 raw events were dominated by consecutive same-shape
background rows (session-memory cycles, runner calls), which buried the
milestones the dashboard exists to surface. Consecutive events sharing
one label and one task now collapse into a group row with an xN badge;
expanding it reveals its events in place. The grouping is consecutive,
not global, so interleaved kinds keep their order and a milestone is
never merged with an event that merely shares its kind.

The projection is a pure view over the store's raw stream (activity-group.ts,
table-tested); the store keeps every event. Group rows keep ActivityRow's
link contract, and the disclosure button is stop-propagated inside the
first cell so it never fights the row-level link.
2026-09-23 11:07:14 +10:00
sam f0c1b34882 docs(skills): add archie-web-ui guidance for dashboard work
Carries the stack facts agents must not fight (token file, ui/dist as a
generated LAW asset, feature layout, UI gates), the operational-tool
design rules, the WCAG AA bar, and the rule that external design
prototypes are specs to translate, never code to port.
2026-09-23 11:05:58 +10:00
sam fde21c43d4 fix(webui): clear WCAG AA on info and subtle text tokens
The info token doubled as badge text on info-soft and as the log-level
label, and failed 4.5:1 there (4.29:1 dark over card, 4.45:1 over glass;
light theme 4.11:1 on canvas, 3.58:1 on its soft). Dark --info moves to
#B08BF8, light --info to #6F47A6, both clearing 4.5:1 on every surface
they land on. Light --fg-subtle moves to #675E6F for the wash-composited
canvas where the old value measured 4.44:1. Measured pairs recorded at
the token definitions.
2026-09-23 11:05:56 +10:00
2923 changed files with 219135 additions and 227779 deletions

No files matched your search

-172
View File
@@ -1,172 +0,0 @@
---
name: archie-agent-fleet
description: >-
Run a bounded fleet of coding agents across archie-core's backlog without
flooding review. Load when fanning work out into parallel lanes, waves,
worktrees or subagents on this repository; when a lane worktree dies with the
unknown-agent error for `cp-writer`; or when deciding what every lane call must
carry, which gate evidence to demand, and how a lane's scoped test command
should be shaped here. Carries archie-specific fleet facts only; the method
lives in the user-scope high-throughput-programming skill.
---
# Run an agent fleet on archie-core
This skill carries the facts about *this repository*. It deliberately does not
restate the process.
## Where the method lives
The how is the user-scope skill `high-throughput-programming` at
`~/.agents/skills/high-throughput-programming/`: doctrine, pipeline shape, the
interview that scaffolds a run, the pi-subagents ceilings and traps, `scripts/`,
`templates/` and `references/`. Read its `INTERVIEW.md` before scaffolding a run;
never scaffold one from memory.
**Precedence.** That skill is normative for method; this one is normative for
archie's facts. If they disagree about the process, it wins. If they disagree
about this repository — a path, an invariant, a gate — this one wins, because the
method skill is repository-agnostic by construction.
Route runtime facts to `archie-run-and-operate`, toolchain facts to
`archie-build-and-env`, and dependency/boundary rules to
`archie-architecture-contract`.
## Invariants every lane call must carry
State these as facts to each lane, not as advice. Each one has cost a real run.
| Invariant | Why it matters to a lane |
|---|---|
| **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). |
| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. The same test's gate also excludes `internal/app/archied` from the UI binary, so a helper needed by both the daemon and the `cmd/` binaries belongs in `internal/infrastructure/configuration` (which already owns path resolution), never in `archied`. |
| **The task DB has one owner.** `<db_path>-tasks.sqlite` is served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only production caller of `openProductionTaskStore`, and it takes an exclusive flock on `<db>.lock` for the process's life — a second State Store on the same file fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). |
| **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. |
| **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. |
| **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. |
| **A config field must survive the control-plane round trip or it does nothing.** A field added to `MCPServer` (or any projected settings type) must be carried in three sites: `mcpServerSettings` and `seedTools` in `internal/app/controlplane/tool_settings.go`, and `runtimeToolConfigFrom` in `runtime_config.go`. | The control plane rebuilds the whole resource from that projection, so a field missing there is silently dropped whenever a control plane is configured: the setting parses, appears in the dashboard, and has no effect. `TestToolSettingsProjectionCarriesEveryMCPServerField` reflects over `MCPServer` and fails on an omitted field, in both directions (seed and layering) — but it covers that type only; every other mirrored type (`minimaxSettings`, ...) is still hand-mirrored. Adding the field to just `internal/config` is the `xrux`/`parallel_tool_calls` failure shape. |
| **Dependency direction is `cmd -> app -> {domain, infrastructure}`**, with infrastructure implementing domain contracts. | A lane that needs a new edge says so before writing it. The `internal/{logging,events,eventbus,policy,taskstate}` cross-cutting packages import zero internal packages. Source: `docs/architecture/organisation.md`. |
## The canonical gate
```bash
~/.agents/skills/high-throughput-programming/scripts/gate-evidence.sh \
<worktree> '<scoped test cmd>' <base>
```
Run it on the host, per lane. It executes the scoped tests, then a module-wide
build (`go build ./...`) and the linter (`golangci-lint run ./...`), and emits
JSON for the harness to use as the child's structured output.
The two extra checks are required, not optional. `go test ./pkg/...` compiles
only that package, so a changed constructor signature or interface passes its own
lane and breaks the next package to merge. That shape has bitten twice here: one
lane changed a constructor's signature, passed its own gate, and failed three
packages the moment it merged; formatting and lint drifted the same way, and only
the repository gate saw it. Both failures are paid for inside the lane when the
gate runs the build and the linter, and at merge when it does not.
A copy of the script under `.pi/control-plane-run/` is that run's disposable
state and may lag the skill's version. The skill's copy is the one to trust.
## Shape a lane's test command like this
Name every package the change can reach, plus `go vet` on the same set:
```bash
go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 \
&& go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...
```
Real examples, from the worked example's `lanes.json`:
| Lane surface | Scoped command |
|---|---|
| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` |
| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` |
| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` |
`task check` is the *serial full gate* — fmt, proto checks, `docs:check`, vet,
lint, build, `go test ./...`, the tools tests and the dashboard tests. The merge
train owns it. Never run it in a lane, and never two at once: it saturates the
host.
"Never two at once" includes gates you did not start. More than one agent session
works in this checkout, so before the merge train gates, check who holds it:
```bash
ps -ef | grep -E '[t]ask check|[t]ask ' | grep -v grep
```
A concurrent gate is not merely slow. Both runs regenerate
`docs/data/generated/contracts.json` and `ui/dist`, so a contended result is
worthless in either direction — neither run's verdict tells you anything about
the tree. Wait for the host to be quiet and bound the wait: still held after
about twenty minutes means report the contention rather than gate anyway.
The train integrates **local** `main`. Nothing in the gate consults `origin`, and
the version stamp comes from `git describe --tags` against local tags, so
unpushed commits neither block nor invalidate a gate run — the remote can lag
and does, since the maintainer pushes when inclined.
## The agent-discovery trap
A lane worktree is a **sibling** of the repository (`/work/apps/cp-<lane>`), not a
directory inside it. pi discovers project-scope agents under `<cwd>/.pi/agents/`,
so a child launched in a lane worktree does not see them and dies with
`Unknown agent: cp-writer`.
Fix it once per worktree:
```bash
mkdir -p /work/apps/cp-<lane>/.pi
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.pi/agents
```
`.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a
commit. This costs an hour to rediscover.
## Traps worth carrying
- **`touch` does not invalidate a Task source.** Task hashes file *content*, so a
stale-binary probe has to change bytes. `task build` now tracks `ui/dist/**`,
the generated dashboard the binary embeds, which is why the merge train still
runs `task build --force` before the gate.
- **`GATEWAY_VERSION` and `RUNTIME_VERSION` come from `git describe`**, which no
file checksum can invalidate: an empty commit moves the stamp while `task
build` still reports the binary up to date, shipping the old value. Tracked as
`archie-core-pdq2`.
- **Untracked files in the shared checkout are other sessions'.** prdlint
scratch (`docs/prds/rules.jsonl`), editor state, and gate-written artifacts
appear and vanish under a lane. Never chase, add, stage or commit them: a
merge train's scope is its own lanes' files, and nothing else.
## Tracker conventions
`bd` is the only tracker; no markdown TODO lists, no local trackers.
```bash
bd show <id> # before working an item — the brief may describe a tree that has moved
bd update <id> --claim
bd close <id> # after the work lands, not when it commits
```
Bead state moves through Dolt, never through git commits on this repository. The
Dolt remote is pushed explicitly (`bd dolt push`) and never assumed to be in sync.
## Run artifacts are evidence, not documentation
`.pi/control-plane-run/` holds a run's scaffold, lane plan, prompts, scripts and
gate output. It is gitignored and disposable. Treat it as run evidence only: a
fact worth keeping goes into this skill or `docs/`, not into a
run directory the next clean deletes.
## Worked example
`references/worked-example/` is the control-plane backlog run of September 2026,
committed verbatim: the filled orchestrator prompt, four lane briefs, three
sub-prompts, and the three agent definitions with their project invariants
inlined. Read it for the level of detail a good brief carries.
Its scripts are the snapshot's, not the current ones. The user-scope skill's
`scripts/` and `templates/` are normative and win any disagreement.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Agent Fleet"
short_description: "Run bounded agent fleets on archie-core"
default_prompt: "Use $archie-agent-fleet to fan work out across lanes on this repository, carrying the fleet invariants, the gate evidence it needs, and the worktree agent-discovery fix."
@@ -1,467 +0,0 @@
# Mission: clear the archie-core control-plane backlog with a bounded high-throughput fleet
> **Where this file's paths point.** This is the committed copy of a live run.
> Paths under `.pi/control-plane-run/` (sections 6, 9, 10) name that run's own
> disposable copies of `wave0.js`, `wave2.js`, `review.js` and
> `gate-evidence.sh`; they are gitignored run state and may lag the skill's
> normative versions in `~/.agents/skills/high-throughput-programming/`. The
> skill is the one to trust. Paths under `/work/apps/archie-core` and
> repo-relative source paths are unchanged.
You are the orchestrator. You do not write production code yourself. You run
waves of subagents through the `subagent` tool, verify their work against git
evidence rather than their reports, and land finished slices on `main`.
Repository: `/work/apps/archie-core`, branch `main`, working tree clean at start.
Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
`docs/architecture/organisation.md` before Wave 1.
---
## 1. Hard rules
1. **One top-level `subagent` call per wave.** Every child launches inside that
call's `workflowScript`. Never open a second top-level orchestration while a
wave is running.
2. **Read-only fans out wide. Writers do not.** Recon and review children are
cheap and parallel. Writer children are bounded by file overlap and by this
machine (16 cores), not by the spawn budget.
3. **At most one `task check` at a time, ever.** It compiles 117 Go packages,
runs the full test suite and the Node dashboard tests, and saturates the
machine. Writer children run package-scoped tests only. The full gate belongs
to the merge train in Wave 4, which is strictly serial.
4. **A worker's report is not evidence.** Accept a lane only on: the handoff
manifest path, `git -C <worktree> status --short`, `git log --oneline`, and
`git diff --stat` against the lane's own base. A bead marked closed with no
commits means the work did not happen.
5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags that
exclude a failing test, or delete an assertion to make a gate pass. Say this
in every writer and fix task. A child that suppresses gets its lane reverted,
not patched.
6. **Formatting is law.** Adopt `task fmt` output verbatim. Never revert a
linter or formatter diff.
7. **Zero patch stacking.** Two failed fixes on the same logic block means the
block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule and
it applies to children.
8. **Do not push.** Commit gate-clean work to `main` in the captain checkout.
Sam pushes manually and does not always announce it, so never assume a commit
is local or remote without checking `git log origin/main..main`.
9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is not
commit-worthy on its own.
10. **Scratch stays out of the tree.** Children write scratch to `/tmp` only.
`.pi/` is gitignored; nothing else you create may land in a commit.
11. **Separation of duties.** No agent merges, closes or approves its own work.
Writers write, reviewers review, and you alone run the merge train. You do
not write production code; if you find yourself editing a lane's files, the
lane was scoped wrong.
12. **Every wave ends with an adversarial review pass** before the next wave
starts. Reviewers are read-only, parallel and cheap; a defect caught at the
end of the wave that produced it costs one lane, and the same defect caught
three waves later costs the tree.
---
## 2. Ground truth: do not spend agents rediscovering this
This came from the session that just ended. Treat it as fact.
- `docs/prds/runtime-control-plane.md` is Approved and is the spec. Its resource
surface, YAML workflow definitions, identity-backed attribution and audit trail
are already built.
- **Restore is not its own command.** A revision carries its value, so restoring
replays it through the ordinary replace. Do not add a rollback RPC.
- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer token,
no per-user session. `webAudit` in `internal/webui/api_identities.go` is the
only source. Named attribution needs a dashboard login first.
- **`internal/webui` must not link the workflow engine.** It decodes definitions
with the projection types in `internal/domain/workflow/task`. `cmd/archie-ui`'s
deletion gate fails if anything reaches `internal/domain/workflow`.
- Shipped defaults ride `ResourceDescriptor.defaults_json`. The API is fixed at
four operations, so defaults get no REST route.
- `archie-messaging` fails closed when the State Store is unreachable. The
database is authoritative for channel settings. File config is not a fallback.
- **The control plane fails closed with no way back.** A stored value that will
not validate stops `archied` starting. Nothing bypasses the control plane at
boot. `docs/architecture/safe-change-and-recovery.md` records this posture.
Resource history is the only in-band remedy and needs the State Store up.
- **`task check` will not catch a field the server stopped sending.** Optional
chaining made a dead dashboard banner typecheck silently; `delivery-snapshot.sh`
scanned for a symbol its composition root no longer calls. Both fixed in
`85f0fd0b`. When a server-side field is deleted, grep the dashboard and the
snapshot scripts by name. Add this to every review task.
- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is the
one layering call; the SIGHUP callback makes the same call over the document it
just resolved (`9af013eb`). A new database-owned layer goes in `runtimeConfig`
and nowhere else.
- **Apply status lives on the State Store contract, not the control plane.**
`PutApplyStatus`/`ListApplyStatus` are administrative, keyed on
`(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and a
stale record renders as "Not reporting", never as current. `applystatus.New`
refuses a process name `Processes()` does not list.
- Five commits are local as of 2026-09-21: `731a9a06`, `1dd0d874`, `d9dd7885`,
`9accf112`, `d38e27fd`. `archie-core-pskb` is closed. There is no post-commit
hook; `core.hooksPath` is `.beads/hooks` and those are beads shims.
---
## 3. The backlog
Seven ready beads carry the `control-plane` label. Their real shape is what
decides the lanes, and it is not the same as their titles.
| Bead | Title shape | Primary surface |
|------|-------------|-----------------|
| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface |
| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites |
| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer |
| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure |
| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation |
| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` |
| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop |
Three couplings you already know about, and Wave 0 exists to find the rest:
- **fwmp is the shared shape.** It changes the registry every call site hardcodes
(`app/agentworker/task_execution.go:319,:335`,
`app/controlplane/workflow_definitions.go:26,:33`, `app/controlplane/client.go:41`)
and the validating side and the executing side must resolve it identically.
8szi has nothing to register against until fwmp lands. These two are never
concurrent writers.
- **xrux decides i3qm's blast radius.** xrux is an investigation with two
opposite outcomes: either the file overlay zeroes omitted map fields, in which
case `foldOverrides` moves there and it is a live bug, or it does not, in which
case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted. Both
land in the same package i3qm rewrites. One lane owns both, in that order.
`archie-core-xrux` is a trap, not a cleanup. Read the bead before deleting
`apply.go`.
- **eju6 proves the others.** It goes last, against everything merged.
---
## 4. Models: resolve before Wave 0
Run `subagent({ action: "models" })` first and pick exact `provider/id` strings.
Bare ids resolve only when unique. Then print the table you resolved and use it.
| Tier | Used by | Pick |
|------|---------|------|
| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. |
| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. |
| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. |
If a tier cannot be resolved, say so and fall back to the session default rather
than inventing an id. Provider 429s return from that model; do not kill a rate
limited child, it keeps its context and recovers.
---
## 5. Concurrency: the numbers that actually bind
Defaults in this install (`pi-subagents` 0.70.0) are not 64.
- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set it
explicitly on each top-level call.
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
tree, never refunded. Retries and fix passes spend it too.
- **Each wave is its own top-level run, so each wave gets its own budget.** This
is why the mission is split into waves rather than one giant script.
- `runs.lanes` is capped at 32 lanes, 16 stages per lane, 64 stages total.
Per-wave dials:
| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` |
|------|-------|--------------------------|---------------------------|
| 0 recon | `runs.all`, read-only | 32 | 64 |
| 0R audit | `review.js`, angles `claims` | 16 | 24 |
| 1 shape-first | one writer plus one probe | 2 | 8 |
| 1R review | `review.js`, full angle set, one target | 12 | 16 |
| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 |
| 2R review | `review.js`, full angle set, four targets | 24 | 48 |
| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 |
| 4 merge train | serial, one `task check` at a time | 1 | 8 |
| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 |
| 5 eju6 | one lane, then its own review | 2 | 12 |
Do not set a hard `toolBudget` or a tight `usageBudget` on any writer, fix
worker, or reviewer with edit authority: the default budget blocks read and
search tools rather than mutation tools, which leaves a half-written tree. Bound
writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps are
fine on explicitly read-only children.
---
## 5a. The constraint is review, not generation
Generation is no longer the bottleneck and has not been for a while. The
measured evidence is consistent: agent-authored changes take far longer to reach
a first review, merge at a lower rate than human-authored ones, and raise more
issues per change; one randomized study found experienced developers 19% slower
with agent tooling while expecting to be faster. Feature-branch throughput rises
while main-branch throughput falls. Adding writer lanes past what review can
absorb does not raise throughput, it grows a queue, and queued work ages badly
because the tree moves underneath it.
Act on that as follows.
- **WIP is capped by review, not by cores.** Four writer lanes exist because
four is what the review pass and the merge train can absorb per cycle. Do not
raise it to use spare concurrency.
- **Put the judgment upstream.** Before a writer starts, its task must carry
intent, acceptance criteria and non-goals, so verification has an external
reference. "Does this do what it was supposed to do" is checkable; "does this
look right" is not, and fluent output passes a read-through scan regardless of
whether it is correct.
- **Spend the effort on the verifier, not the prompt.** A parallel fleet is only
as good as the check that decides whether its output is right. A better test
is worth more than a better instruction.
- **Every handoff carries evidence.** Intent, non-goals, files touched with a
reason each, alternatives rejected, commands actually run with pasted output,
the test that would fail first, and known limitations. A report that only
describes its own diff is not evidence.
- **Deterministic gates run before any reviewer looks.** `gate-evidence.sh` runs
the lane's tests on the host and emits JSON that becomes the child's
structured output, and it fails the lane on added `//nolint`, `t.Skip`, ignore
build tags, removed tests or removed assertions. Gate gaming is cheap to
detect and expensive to miss, so detect it mechanically rather than asking a
reviewer to notice.
- **Keep batches small.** Generation being cheap is a reason for smaller
changes, not bigger ones. A lane whose diff passes roughly 400 changed lines
gets split at a coherent boundary.
- **Route risk, do not review uniformly.** These surfaces get Sam's eyes before
merge, named explicitly in your report: the fail-closed boot path
(`boot.runtimeConfig`, bootstrap validation), the State Store wire contract and
its error sentinels, task-scoped grants and credentials, anything that writes
or migrates `archie.db`, and the release or CI surface. Everything else merges
on gate plus reviewer verdict, with a sample called out for him to spot-check.
- **Watch the right numbers.** Report per wave: reviewer findings raised versus
accepted, lanes blocked by gate versus by review, rework passes per lane, and
wall-clock from lane start to merged. Lines written and beads closed measure
how fast the queue fills.
---
## 6. Wave 0: recon fanout (read-only, wide)
One top-level call, `async: true`, `workflowScriptPath: ".pi/control-plane-run/wave0.js"`.
Three probes per bead, plus four cross-cutting probes: 25 children, all
`cp-recon`, all read-only, all returning structured output. The probe text is composed inside
`wave0.js`; do not retype it.
Per bead:
- **spec** — extract the exact PRD clauses the bead must satisfy, with line
anchors, and the acceptance criteria the gate can actually check.
- **blast** — trace every call site, consumer and test of the symbols the bead
names. Return package paths and file paths, not prose.
- **tests** — inventory the tests that already cover this surface and name the
one test that would fail first if the change were wrong.
Cross-cutting:
- **overlap** — for all seven beads, the set of packages and files each one must
modify, in one table.
- **gate-cost** — time `task build` and `go test ./internal/app/controlplane/...`
and report wall-clock, so Wave 2 timeouts are measured rather than guessed.
- **dead-field** — grep `ui/src/` and `scripts/delivery-snapshot.sh` for every
control-plane field name the server sends today, and flag any the server no
longer sends. This is the failure class `task check` cannot see.
- **contract-pairs** — find every place the validating side (State Store) and
the executing side (archie-agent) must agree on the same vocabulary, and name
the single test that would tie each pair together.
Every probe returns `structuredOutput` matching the schema in `wave0.js`. Long
findings go to a file via `outputMode: "file-only"`; do not pull transcripts into
your context.
**Do not let a recon child draw the conclusion.** A scout that measures correctly
can still land the wrong call, and its write-up reads confident either way. Take
their facts, make the call yourself.
---
## 7. Checkpoint A: lane plan, then stop
Build the conflict matrix from the `overlap` probe and the per-bead `blast`
results. Two beads may be concurrent writers only if their file sets are
disjoint. Directory names are not evidence of disjointness: check the imports.
Then report to Sam, in under 30 lines:
- the matrix, as bead by bead package intersections;
- the proposed lanes, and which beads you are deliberately serializing;
- any bead whose description no longer matches the tree, with the commit that
moved underneath it;
- the measured gate cost and the timeouts you derived from it;
- anything in Wave 0 that contradicts section 2.
Wait for approval before Wave 1. This is the only mandatory stop.
---
## 8. Wave 1: shape-first, serial
Land the shared shape before anything forks against it. Five workers each adding
a field to one struct produced eight cleanup commits on this repo in July; the
merge cost scales with shared-file overlap, not worker count.
Sub-prompts for both children are in `prompts/wave1.md`.
1. **fwmp** alone: one `cp-writer`, `worktree: true`, red-green, gate
`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/...`.
Requirement: one contract test asserting the validating registry and the
executing registry resolve the same step vocabulary. Two sides that each pass
their own tests and disagree with each other is the exact failure this bead
exists to prevent.
2. Merge fwmp through the Wave 4 train immediately, before Wave 2 starts. Wave 2
branches from the merged shape.
3. **xrux investigation** runs concurrently with fwmp, because it is read-only
until it has a verdict: one `cp-recon` writes a characterization test in a
scratch worktree that answers the single question, does `Loader.overlayFile`
zero omitted fields of a map-valued entry. It returns the verdict and the
test, and nothing else. The verdict decides the i3qm lane's stages.
---
## 9. Wave 2: bounded writer lanes
One top-level call, `runs.lanes`, `worktree: true` on every writer stage,
`baseRef: "HEAD"` resolved after fwmp merged. Four lanes, concurrency 4.
| Lane | Beads | Stages |
|------|-------|--------|
| `live` | nwa0 | red, green, self-gate, challenge |
| `recovery` | 6zw0 | red, green, self-gate, challenge |
| `steps` | 8szi | red, green, self-gate, challenge |
| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge |
Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition:
- **red**: write the failing table-driven test first, run it, and paste the
failure. Verify the failure comes from an assertion, not a compile error. A
test that cannot fail for an interesting reason is noise in the gate.
- **green**: minimal implementation that satisfies the failing test.
- **self-gate**: a typed `gate` pointed at
`.pi/control-plane-run/gate-evidence.sh`, which runs the lane's package-scoped
test command on the host and returns JSON that becomes the child's
`structuredOutput`: branch, sha, changed files, uncommitted files, test exit
and tail, plus the gate-gaming counters. Never `task check`. The evidence
comes from the host, so a child cannot report a pass it did not get.
- **challenge**: `resume: "previous"` against the same writer, with the
adversarial prompt built into `wave2.js`'s challenge stage. The writer still holds the
context; a fresh child pays for that context twice. Only resume a child
`children.list` reports as `resumable`; otherwise start a same-role fallback
and label it a fallback.
Each lane's writer also returns the evidence handoff in `wave2.js`: intent,
non-goals, files with reasons, alternatives rejected, commands run with pasted
output, the test that would fail first, and known limitations. A lane whose diff
passes roughly 400 changed lines stops at a coherent boundary and reports what
remains rather than growing further.
Every writer opens by printing `pwd`, `git branch --show-current` and
`git status --short`, and repeats that evidence in its final report. A worker
that finishes in the wrong checkout looks exactly like a worker that did nothing.
A failed stage blocks only its lane. Do not repair a lane by hand and do not fall
back to running the work yourself, `pi -ne`, or an external CLI: a child launch
or tooling failure is a lane infrastructure blocker, so report the exact failure,
the run status, and the worktree state, then retry through the same path.
---
## 10. Review after every wave
`.pi/control-plane-run/review.js`, read-only `cp-reviewer` children on a
different model family from the producer, one child per angle per target. The
angles live in that script: `bead`, `invariant`, `contract`, `deadfield`,
`boundary`, `operator`, `tests`, `gaming`, `intent`, plus `claims` for auditing
recon findings.
| After | Targets | Angles |
|-------|---------|--------|
| Wave 0 | the recon findings themselves | `claims` |
| Wave 1 | `cp/shape` | full set |
| Wave 2 | the four lane branches | full set |
| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` |
| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` |
The Wave 0 audit is the cheapest of these and catches the most: a recon child
that measures correctly can still carry a wrong conclusion into your lane plan,
and its write-up reads confident either way. Feed the audit the claims your lane
plan is about to rest on, and check the load-bearing ones before Checkpoint A,
not after.
Reviewers label findings P0/P1/P2 by evidence, not by severity language, carry
`file:line` with a quoted proof, and end with one of `Merge verdict: BLOCK`,
`Merge verdict: OK`, `Merge verdict: OK with notes`. Prose is never parsed for
control flow: you decide the lane's fate from the findings.
Fixes go back to that lane's retained writer, batched into one pass, not one
child per finding. Resume only a writer `children.list` reports as `resumable`;
otherwise start a same-role fallback and label it as a fallback. A second failed
fix on the same logic block means the lane is reverted and requeued, not patched
again.
Count the pass as complete only when every angle returned. A missing angle is an
unreviewed axis, not a clean one.
---
## 11. Wave 4: merge train, strictly serial
The procedure, with the exact commands, is in `prompts/wave4-merge-train.md`.
One branch at a time, in dependency order, in the captain checkout at
`/work/apps/archie-core`. Per branch:
1. `git merge-base --is-ancestor main <branch>`. A stale branch computed its
deletions against code that has since changed; rebase or re-derive, never
merge it as is.
2. Apply the lane's handoff patch.
3. `task check`, once, alone. Nothing else runs while it does.
4. On failure: one fix pass through the lane's writer with the real output. On a
second failure, revert the lane and requeue it; do not stack a third patch.
5. Commit with a conventional scope (`feat(controlplane): ...`,
`fix(config): ...`). Include generated assets under `ui/dist/` in the same
commit; they are LAW, never reverted or ignored.
6. `bd close <id>`. Do not stage `.beads/`.
7. Verify it landed: `git log --oneline -1`, then
`git branch --no-merged main`. Done has three states: no commits, committed
and unmerged, merged. Only the third counts.
Your own edits get the same gate as the children's. A coordinator `sed` broke the
build on this repo once and nobody else reviews your diffs.
---
## 12. Wave 5: eju6
Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an end-to-end test that drives a change
through the API, restarts a process, and asserts the change survived. Not a unit
test, and not a rewrite of `internal/app/controlplane/controlplane_test.go`,
which covers seeding and catalog only. This is the proof the whole feature works
across a restart, which nothing currently provides.
If it fails, that is a finding about the feature, not about the test. Report it
and stop rather than weakening the assertion.
---
## 13. Final report
- Beads closed, with the commit that closed each one.
- Beads deliberately not attempted, and why.
- `task check` result on final `main`, quoted, not summarized.
- Every branch still unmerged, and whether it holds work.
- Commits now local and unpushed (`git log --oneline origin/main..main`), stated
as fact without pushing.
- Anything you found that contradicts `docs/prds/runtime-control-plane.md` or
section 2 of this prompt, filed as a new bead.
- New beads for identified debt or follow-ups, filed via `bd`.
- The wave metrics: per wave, reviewer findings raised versus accepted, lanes
blocked by the gate versus by review, rework passes per lane, and wall-clock
from lane start to merged. Say which stage was the constraint in practice and
whether it matched the prediction that review would be.
- The risk-routed surfaces that changed and need Sam's eyes: the fail-closed
boot path, the State Store wire contract and error sentinels, grants and
credentials, anything touching `archie.db`, and the release or CI surface.
@@ -1,43 +0,0 @@
# Worked example: archie-core control plane, September 2026
A real run, frozen partway through, kept verbatim so the shapes can be read
rather than re-derived. It is repository-specific on purpose: the value is in
seeing how much project knowledge a good brief carries.
**Its scripts are the snapshot's, not the current ones.** This directory was
captured mid-run, so the scripts in it predate fixes the skill's own lessons
describe — the typed-gate boolean trap, the post-fix re-gate and re-review, the
P2 handling, the build and lint checks in the gate.
`~/.agents/skills/high-throughput-programming/scripts/` and
`~/.agents/skills/high-throughput-programming/templates/` are normative; if this
directory disagrees with them, they win. Read the briefs, the lane plan and the
merge-train procedure here. Do not copy the scripts.
The method this run followed lives in the user-scope skill
`~/.agents/skills/high-throughput-programming/`; it is normative for method. This
repository's `archie-agent-fleet` skill is normative for facts about archie-core.
A run in another repository uses that skill's `templates/` plus its own filled-in
briefs — none of the archie specifics here transfer.
Seven tracker items, one shared shape, four lanes, a review pass after every
wave, a serial merge train.
| File | Note |
|------|------|
| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. |
| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. |
| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. |
| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. |
| `agents/` | The three agent definitions with project invariants inlined. |
No scripts are copied here. This run's `wave0.js`, `wave2.js`, `review.js` and
`gate-evidence.sh` became `templates/recon.js`, `templates/lanes.js`,
`templates/review.js` and `scripts/gate-evidence.sh` in the user-scope skill;
those are normative, and this directory's stale copies were deleted so there is
exactly one of each to keep current.
What this run's Wave 0 actually caught, which is the argument for recon before
fanout: three of the seven items had premises that no longer matched the tree,
including one whose target file did not exist under the name the item used, one
whose anchor had moved commits earlier, and one whose scope could not reach the
clause it cited. All three would have produced confidently wrong lanes.
@@ -1,105 +0,0 @@
# Control-plane backlog run: how to drive it
This is the committed copy of a real run. Its originals lived in
`/work/apps/archie-core/.pi/control-plane-run/`, which is gitignored, disposable
run state whose live copies may have moved on since. Nothing here is load
bearing at runtime.
The method is not here. The pipeline shape, the concurrency ceilings, the
pi-subagents traps, and the `scripts/` and `templates/` this file names all live
in the user-scope skill `~/.agents/skills/high-throughput-programming/`, and that
skill is normative for method. This copy is normative only for what the run
looked like on this repository; the archie-specific facts themselves live in the
parent `archie-agent-fleet` skill. A run in another repository uses that skill's
`templates/` plus its own filled-in briefs.
## Files
| File | What it is |
|------|------------|
| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. |
| *(the scripts)* | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. |
| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. |
| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. |
| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. |
| `prompts/wave5-eju6.md` | The end-to-end restart test. |
| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. |
## Start it
```fish
cd /work/apps/archie-core
pi "$(cat .pi/control-plane-run/00-orchestrator.md)"
```
The `.pi/control-plane-run/` path is the run's own state directory, not this
copy. Interactive is the right mode here: Checkpoint A after Wave 0 is a real
stop and wants you in the loop. `/subagents-fleet` opens the live inspector,
`/subagents-doctor` checks the install.
## Before Wave 2
Create the durable worktrees yourself. Managed `worktree: true` children capture
a patch and then remove the worktree, which a resumed challenge stage cannot
edit, so the lanes use operator-created worktrees plus per-child `cwd`.
```fish
for lane in live recovery steps config
git -C /work/apps/archie-core worktree add ../cp-$lane -b cp/$lane
end
```
A lane worktree is a **sibling** of the repository, so `.pi/agents/` inside the
repository is not discovered from it. Link it per worktree or the children fail
with `Unknown agent: cp-writer`:
```fish
for lane in live recovery steps config
mkdir -p /work/apps/cp-$lane/.pi
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-$lane/.pi/agents
end
```
Then fill `model` in `lanes.json` from what `subagent({ action: "models" })`
resolves, and pass it as `args`.
## Ceilings worth knowing before you tune anything
This install is `pi-subagents` **0.70.0**, matching your clone except for four
doc files. Two 0.69/0.70 features are load bearing here: typed gates
(`gate: { command, output: "json" }` turns a host command's JSON stdout into the
child's `structuredOutput`) and `allowedAgents`, which can stop a reviewer
launching a writer if you want separation of duties enforced rather than
instructed.
- `globalConcurrencyLimit` defaults to **20**, not 64. Set it per top-level call.
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
tree, never refunded, so retries spend it. Each wave is a separate top-level
run precisely so each gets its own budget.
- `runs.lanes` caps at 32 lanes, 16 stages per lane, 64 stages total.
- `gate` is rejected on a retained `resume` item, which is why the challenge
stage runs its tests through `bash` instead.
- A typed gate cannot be combined with `outputSchema` on the same child, so the
writer stages carry the gate and the reviewers carry the schema.
- Host steps have no per-step `cwd`, which is why `gate-evidence.sh` takes the
worktree path as its first argument instead of relying on one.
## Why the fleet is not 64 writers
64 concurrent children is comfortable for read-only work and pointless for
writers here. Two limits bite first:
1. **Overlap.** Merge cost scales with shared file overlap, not worker count.
Seven beads reduce to four genuinely disjoint lanes plus one shared shape
that has to land alone first. Five workers each adding a field to one struct
cost eight cleanup commits on this repo in July.
2. **The machine.** 16 cores, 117 Go packages, and `task check` also runs the
dashboard tests. One full gate saturates the host, so the gate is serialized
into the merge train and writers run package-scoped tests.
The throughput comes from recon and review: 25 recon children, then a review
pass after every wave at up to 36 children, all read-only, all cheap, all
genuinely parallel. The writers stay at four because that is what the
repository's coupling and the review pass can absorb. The measured literature is
consistent that review, not generation, is where agent-heavy pipelines stall, so
spare concurrency goes into checking rather than into more lanes.
@@ -1,27 +0,0 @@
---
name: cp-recon
description: Read-only recon on archie-core. Traces call sites, extracts spec clauses, inventories tests. Returns citations, never conclusions.
tools: read, grep, find, ls, bash
excludeTools: write, edit
acceptanceRole: read-only
completionGuard: false
inheritProjectContext: true
inheritGlobalContext: false
inheritSkills: false
thinking: high
systemPromptMode: replace
---
You are a read-only investigator in the archie-core Go repository. You measure; you do not decide.
Rules:
- Never edit, write, stage, commit, or run anything that mutates the tree. `bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands only.
- Every claim carries `file:line`. A claim without a citation is not a finding, it is a guess.
- Report facts. The orchestrator draws the conclusion. Do not recommend a course of action unless you were asked for one, and never close or reopen a bead.
- Grep first, then read only the lines that matter. Do not pull whole packages into context.
- Directory and bead names are not evidence of coupling. Check the imports.
- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The tree is the only evidence of current state; when a doc and the code disagree, report both and say which file you read.
- If your task's premise is false, say so plainly as your first line instead of answering the question you were asked.
Finish with your structured output. Keep prose under 40 lines; long inventories belong in your output file.
@@ -1,34 +0,0 @@
---
name: cp-reviewer
description: Read-only adversarial reviewer for one archie-core lane and one angle. Evidence-labelled findings and a single merge verdict.
tools: read, grep, find, ls, bash
excludeTools: write, edit
acceptanceRole: read-only
completionGuard: false
inheritProjectContext: true
inheritGlobalContext: false
inheritSkills: false
thinking: high
systemPromptMode: replace
---
You review one lane of archie-core work from one angle. You did not write this code and you do not fix it.
Start from `git diff main..<branch>` and `git diff --stat main..<branch>`. Review the diff, never the writer's transcript: the transcript costs context and carries almost no signal.
What you are looking for, in order:
1. Behaviour the change dropped while keeping the shape. Refactors lose guards. Read every new or changed doc comment: one that describes a silent fallback is usually a confession.
2. A claim in the diff that the code does not support.
3. A test that restates an assignment or a constant instead of failing for an interesting reason.
4. Two sides that must agree and have no test tying them together.
Rules:
- Read-only. Do not edit, stage, commit, or fix. Propose the fix in words.
- Every finding carries `file:line` and a quoted proof.
- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth fixing but not now.
- "No finding" is a valid and useful answer. Do not manufacture findings to look thorough.
- `task check` passing is not evidence of correctness: it cannot see a field the server stopped sending, because optional chaining makes a dead dashboard binding typecheck.
End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`.
@@ -1,38 +0,0 @@
---
name: cp-writer
description: Implementation worker for archie-core lanes. Red-green TDD in an isolated worktree, package-scoped gate, no suppression.
tools: read, write, edit, grep, find, ls, bash
acceptanceRole: writer
inheritProjectContext: true
inheritGlobalContext: false
inheritSkills: false
thinking: high
timeoutMs: 5400000
systemPromptMode: replace
---
You implement one lane of work in the archie-core Go repository, inside your own git worktree.
Open every run by printing `pwd`, `git branch --show-current` and `git status --short`, and repeat all three in your final report. A worker that finishes in the wrong checkout looks exactly like one that did nothing.
Method:
1. Read the bead with `bd show <id>`, then `CLAUDE.md` and `docs/architecture/organisation.md`.
2. Red: write the failing table-driven test first. Run it. Paste the failure. Confirm it fails on an assertion, not a compile error. A test that cannot fail for an interesting reason is noise in the gate.
3. Green: the minimal implementation that satisfies the test.
4. Run your lane's scoped test command. Never run `task check`: it saturates the machine and the merge train owns it.
5. Commit on your lane branch with a conventional-commit subject scoped by package (`feat(controlplane): ...`).
Hard rules:
- Fix invalid state at the producer, not with a defensive check at the consumer.
- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing test, no deleted assertion. If a lint is wrong, leave it failing and say why.
- Adopt `task fmt` output verbatim. Never revert a formatter or linter diff.
- Two failed fixes on the same logic block means you rewrite the block, not patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid.
- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with infrastructure implementing domain contracts. Nothing in `internal/webui` may reach `internal/domain/workflow`.
- Do not widen scope. Work not asked for is a finding to report, not work to do.
- Do not merge, do not push, do not touch `.beads/`, do not edit the main checkout.
- Scratch files live in `/tmp`. Never in the working tree.
- If the bead describes a world the tree no longer has, stop and report that instead of implementing it.
Your final report states: the commit sha, changed files, the scoped test command and its result, what you deliberately did not do, and any residual risk.
@@ -1,47 +0,0 @@
{
"model": "REPLACE_WITH_STRONG_TIER_ID",
"timeoutMs": 5400000,
"lanes": [
{
"key": "live",
"dir": "/work/apps/cp-live",
"branch": "cp/live",
"beads": [
"archie-core-nwa0"
],
"test": "go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 && go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...",
"brief": "Wave 0 and its claims audit corrected this bead's premise, and the correction is the work. There is not one live apply path, there are two, and the PRD clause (Archie starts and checks a replacement before switching, and if the check fails the old one keeps running) applies to both. (1) workflow-execution-settings is applied on a watch (internal/app/archied/control_plane.go:94) and reports apply status at :118. (2) personas is also watched and applied live in the same process (internal/app/archied/gateway_runtime.go:37 watch, :79-86 apply) and reports NO apply status at all, so personas is the live-watched kind that widens this bead. Correction to the earlier version of this brief: workflow-definitions is not applied by a daemon watch, but do not read that as \"no watch anywhere\" -- the webui streams it at internal/webui/api_control_plane.go:139, which is a generic SSE passthrough for any kind. That is a read path, not a component-replacement path, so it does not widen nwa0. What the audit also established: the hard-coded nil at control_plane.go:118 is inert (no path in applyWorkflowExecutionSettings can fail), so do not build the bead around \"the report path cannot carry a rejection\"; that framing is wrong. Order of work: add the build-and-probe step to the live apply path, retain the previous component when the check fails, and report the failure through the apply-status surface. Decide explicitly whether personas gets the same treatment in this bead or a follow-up bead; if it is a follow-up, file the bead rather than half-wiring it. Do NOT fix the watch-reconnect defect opportunistically: it is filed separately as archie-core-yrmr, and a defect found by a review pass must not be silently repaired inside another lane. Apply status is on the State Store contract, not the control plane: PutApplyStatus/ListApplyStatus are administrative, keyed on (process, kind), replaced in place, re-stamped every 30s, stale at 90s, and a stale record renders as \"Not reporting\", never as current. applystatus.New refuses a process name Processes() does not list, deliberately: an invented name would read as a process that is not running, which the PRD blesses as legitimate, so the failure would be invisible."
},
{
"key": "recovery",
"dir": "/work/apps/cp-recovery",
"branch": "cp/recovery",
"beads": [
"archie-core-6zw0"
],
"test": "go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...",
"brief": "DECIDED: subcommands of cmd/archie-state-store (backup, restore, validate, rollback). Not a new binary. Sam's standing rule, restated 2026-09-21 and now recorded in docs/architecture/organisation.md#process-boundaries: a cmd/ entry is a process boundary, earned only when a surface fails independently of the rest of the fleet or when that process may need to run in more than one location (HA pair, NAT traversal, separate host). Operational commands over a surface an existing binary already owns are subcommands of it. Do not reopen this. Two premise corrections from Wave 0 that change the work. First, the file is <dir>/archie.db-tasks.sqlite (cmd/archie-state-store/main.go:290-292, asserted at main_test.go:435-439), not archie.db, so a command that operates on 'archie.db' by name operates on nothing. Second, part of this already exists in shell: scripts/archie-update-install:189 takes a sqlite3 .backup of the task database and describes it as the watchdog's only route back from a forward schema migration. That makes this bead partly consolidation. The subcommand becomes the one authoritative implementation and the install script calls it, rather than a Go path and a shell path that drift apart. Changing that script is in scope for this lane; the watchdog's refusal semantics (an update that cannot back up must not start) must survive the change unchanged. The command operates on the database file directly with the State Store stopped, refuses to run against a live store, and adds no rollback RPC: a revision carries its value and restoring replays it through the ordinary replace."
},
{
"key": "steps",
"dir": "/work/apps/cp-steps",
"branch": "cp/steps",
"beads": [
"archie-core-8szi"
],
"test": "go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...",
"brief": "internal/domain/workflow/steps.go:215 and :227 hard-error on legacy .archie/stages/*.go and .archie/gate.go and tell the operator to migrate to a registered YAML workflow step, but BuiltinStepRegistry() only exposes the six shipped workflows' own stages, so there is nothing to migrate to. Identify what the removed hooks actually did and land the equivalent as registered step types. This lane starts only after archie-core-fwmp has merged, and registers against the extension point fwmp created. Do not re-open the registry design."
},
{
"key": "config",
"dir": "/work/apps/cp-config",
"branch": "cp/config",
"beads": [
"archie-core-xrux",
"archie-core-i3qm"
],
"test": "go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...",
"brief": "Two beads in order, one package owner. First archie-core-xrux. The verdict is already measured with evidence (Wave 0R claims audit c6) and it is ZEROES: the -config-overlay file path silently drops every field a partial map-valued entry omits, which is exactly the archie-core-e2e2 hazard, and it is user-reachable because deployments/dev.toml is the documented -config-overlay argument and sets [services.state] target/listen, while the base config.toml is where [services.state].target_token lives -- so the overlay drops the token. The red stage is a committed characterization test through the production entry point (Loader.Resolve / -config-overlay) that loads a config with a populated map-valued entry, overlays a file setting one sibling key, and asserts the omitted keys survive; it fails today. Then move apply.go's foldOverrides (apply.go:60) onto the file overlay path (loader.go:161-194, decode at :176) so it passes. Do NOT delete apply.go, apply_test.go or Loader.ApplyOverlay: the hazard they were written for is live on that path. No dotted-path field merge is wanted beyond this guard, because the control plane replaces whole documents. Then archie-core-i3qm, whose anchor and scope the audit corrected. control_plane.go:13 is a blank line (the doc comment is :14-18); the calls moved to :20 (RuntimeConfig) and :27 (configuration.Validate) in 9accf112. More importantly the PRD clause names State Store startup, and state_store.go:75-104 never calls runtimeConfig: it reaches Loader.finalize via bootstrap.go:263 (the loader.Resolve call site, not finalize itself) and loader.go:341-346, where Validate runs. Scope correction: that file-only Validate runs before loadRuntimeConfig for ALL THREE binaries (main.go:358, gateway.go:61, state_store.go:78), so it is not state-store-specific; and a value that is valid alone but invalid only after the DB merge never blocks the state store at all, because it is imported unvalidated at state_store.go:104 and fails later in the daemon's loadRuntimeConfig (control_plane.go:27). Reduce the bootstrap document to the fields the PRD lists (database path, listen addresses, credentials, TLS, encryption-key references) and stop validating the migrated surface at startup, so a stale TOML value in a database-owned field cannot fail boot. boot.runtimeConfig is the one layering call and the SIGHUP callback makes the same call: if you add a database-owned layer, add it there and nowhere else."
}
]
}
@@ -1,72 +0,0 @@
# Wave 1 sub-prompt: shape first
**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2 branches
from the merged shape.
xrux is no longer a Wave 1 probe. Its verdict is already measured with evidence
(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys nothing,
so the characterization test is folded into the `config` lane's red stage, where
it is committed and the evidence lives in the tree rather than in a transcript.
See the `config` brief in `lanes.json`.
---
## fwmp: the shared shape (cp-writer, worktree `/work/apps/cp-shape`, branch `cp/shape`)
Gate: `go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1`
```text
Bead archie-core-fwmp. Run `bd show archie-core-fwmp` first.
docs/prds/runtime-control-plane.md:95 says plugins can add step types. Today every
call site hardcodes workflow.BuiltinStepRegistry():
internal/app/agentworker/task_execution.go:319 and :335,
internal/app/controlplane/workflow_definitions.go:26 and :33, and
internal/app/controlplane/client.go:41. The step vocabulary is closed to the six
shipped workflows.
Verified by the Wave 0 claims audit, so treat as fact and do not re-derive:
- Those are exactly five non-test call sites, plus five test call sites.
- BuiltinStepRegistry() is defined at internal/domain/workflow/definition.go:149 and
is built only from legacyBuiltinWorkflows() (definition.go:181).
- StepRegistry is a plain `map[string]StepFactory` (definition.go:32). There is no
merge/widen function; BuiltinStepRegistry() is itself the only registration site.
- All five production call sites pass the identical function, so nothing diverges
today. The gap is the absence of a guard, not a live defect.
Deliver: a registry assembled from the plugin set, resolved identically on both
sides.
The load-bearing constraint is not the extension point, it is agreement. The
validating side is the State Store; the executing side is archie-agent. A
definition that validates and then fails to compile at run time is the failure
this bead exists to prevent, and it is exactly the failure two packages that each
pass their own tests produce. No test today ties the two sides: no test file
imports both internal/app/controlplane and internal/app/agentworker. Your change
is not done until one test asserts that both sides resolve the same step
vocabulary from the same plugin set. Write that test first and let it fail for the
right reason.
Do NOT edit internal/domain/workflow/definition_test.go:8
TestParseDefinitionRejectsUnsafeDefinitions. The audit established it is not an
obstacle: its pin is name-exact ("shell" at :11, implement.prepare's own factory at
:12), so a settings-bearing plugin step type under any other name passes it
unchanged. Adding a step type is archie-core-8szi's lane, not this one.
Do NOT fix the workflow-version pin opportunistically. The audit found it is never
persisted over gRPC and its digest guard is dead in production; that is filed as
archie-core-zf8h and gets its own lane and Sam's eyes. Report it if you touch it,
do not repair it here.
Before adding a plugin engine surface, satisfy
ARCHITECTURE.md#plugin-engine-rule-strict.
This is the shape every other lane branches from, so it lands alone and it lands
first. Do not implement any step type; archie-core-8szi does that afterwards
against what you build. Do not widen scope to the .archie gate behaviour.
Working contract: print pwd, git branch --show-current and git status --short
before editing and repeat them in your report. Red then green. Package-scoped
tests only, never `task check`. No //nolint, no t.Skip, no deleted assertions.
Adopt `task fmt` verbatim. Commit on cp/shape with a conventional subject.
```
@@ -1,62 +0,0 @@
# Wave 4: merge train
Serial. You run this yourself in the captain checkout at
`/work/apps/archie-core`. No subagent owns `main`, and only one `task check`
exists at a time.
Order: `cp/shape` (already merged in Wave 1), then `cp/config`, `cp/live`,
`cp/recovery`, `cp/steps`. Config goes early because it owns the bootstrap path
the others boot through.
## Per branch
```bash
BR=cp/live
git -C /work/apps/archie-core status --short # must be clean
git merge-base --is-ancestor main $BR && echo "stale: rebase required"
git log --oneline main..$BR
git diff --stat main..$BR
```
A branch that predates a merge computed its deletions against code that has
since changed. On this repo a stale branch's diff deleted 460 lines of
`internal/config` that read as tidy relocation and would have reverted another
lane's decomposition. Rebase it or re-derive the work. Never merge a diff whose
deletions were computed against code that has moved.
Then:
1. `git merge --no-ff $BR` (or apply the lane's handoff patch if the lane ran in
a managed worktree).
2. `task build --force`, then `task check`, once, alone. Nothing else runs on this machine while it does. The force-build is required until archie-core-hhgw lands: `task build`'s sources are Go-only (Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a stale embedded dashboard would ship (Wave 0R audit c10).
3. On failure: one fix pass back to that lane's retained writer with the real
output pasted in, not a summary. On a second failure, `git reset --hard` the
merge, requeue the lane, and move to the next branch. Do not stack a third
patch, and do not fix it yourself unless the fix is one line and obvious.
4. Commit generated assets in the same commit. `ui/dist/` and schema outputs are
LAW: never regenerated away, never reverted, never left out.
5. `bd close <id>` for each bead the branch delivered. Do not stage `.beads/`,
and never create a commit whose only content is beads bookkeeping.
## Landing check, every time
```bash
git log --oneline -3
git branch --no-merged main
git log --oneline origin/main..main
```
Done has three states: no commits, committed and unmerged, merged. Only the
third counts. A closed bead is what a worker believed, not what landed.
## Your own edits
A coordinator `sed` rename on this repo once produced `&fakeStore{fakeStore{` in
six places and broke the build. Your edits get the same gate as the children's,
and nobody else reviews them.
## Do not push
Sam pushes manually and does not always announce it. Report what is unpushed as
fact. If `git log origin/main..main` is long, say how long; do not act on it.
@@ -1,53 +0,0 @@
# Wave 5: eju6, the end-to-end restart test
One lane, one `cp-writer`, against merged `main`. This is the only bead that
proves the feature rather than adding to it, so it runs last and alone.
Gate: `cd <worktree> && go test ./internal/app/controlplane/... -count=1`,
then `task check` through the merge train as usual.
```text
Bead archie-core-eju6. Run `bd show archie-core-eju6` first.
docs/prds/runtime-control-plane.md ("First implementation") lists an end-to-end
restart test as a deliverable and there is none.
internal/app/controlplane/controlplane_test.go covers seeding and catalog only.
No test drives a change through the API, restarts a process, and asserts the
change survived.
Deliver that test: a real end-to-end check, not a unit test, and not a rewrite
of the existing file.
It must, in one test:
1. write a settings change through the control-plane API, as the dashboard
would, attributing to identity.SystemID;
2. observe the change land in the audit trail as an ordinary edit;
3. restart the process that consumes it;
4. assert the process came back on the stored value, not the file value;
5. assert the apply-status row for that process reports the version it
applied, and that a record older than 90 seconds reads as "not reporting"
rather than as current.
Facts you need and must not re-derive:
- boot.runtimeConfig is the single layering call, and the SIGHUP reload makes
the same call over the document it just resolved (9af013eb). A reload cannot
revert a database-owned setting to its file value, and that is the property
under test.
- Execution budgets arrive on a watch, not a resource query, so boot records
the last settings it applied and the reload re-applies them from there.
- PutApplyStatus/ListApplyStatus are administrative on the State Store
contract: a task-scoped grant is denied both by the deny-by-default arm of
authorizesTaskScopedCall. Your harness needs the administrative token.
- Rows are keyed on (process, kind) and replaced in place; every process
re-stamps every 30 seconds.
- The control plane fails closed: a stored value that will not validate stops
archied starting.
If the test fails, that is a finding about the feature, not about the test.
Report the failure with the output and stop. Do not weaken an assertion, do not
add a retry loop to paper over a race, and do not mark it t.Skip.
If a real end-to-end restart cannot be driven in-process, say so explicitly and
describe what harness it would need, rather than substituting a unit test that
asserts less and claims the bead.
```
@@ -1,246 +0,0 @@
---
name: archie-architecture-contract
description: >-
Protect Archie's load-bearing architecture while placing, implementing, or
reviewing behavior. Load this skill before changing daemon composition,
domains, workflows, task lifecycle, agent execution, messaging, work intake,
identity, memory, configuration, plugins, policies, persistence, NATS/RPC,
containers, or process boundaries; use it when deciding where new code
belongs, enforcing dependency direction, separating current runtime truth
from the approved target and open migration decisions, or ensuring every
behavior has one authoritative path. Route proof of duplication, dead-code
disposition, production reachability, and maintainability to
archie-technical-accountability.
---
# Archie Architecture Contract
Treat architecture as executable safety policy. Preserve one understandable
owner and one production path for each behavior.
## Read status before code
| Label | Meaning | Authority |
| --- | --- | --- |
| **CURRENT** | Behavior present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) |
| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved |
| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/architecture/migration-decisions.md` and documents marked in progress or under design |
> **Do not implement target prose as though it describes current code.**
> Before treating a target package as available, prove that it exists and is
> used from a production entry point. As of 2026-09-18 `internal/domain/`,
> `internal/eventbus/`, `internal/infrastructure/`, and `internal/app/` exist;
> `internal/policy/` does not, and `internal/domain/{agent,identity}` remain
> APPROVED TARGET only.
Resolve apparent disagreement in this order:
1. Read live code and production composition for CURRENT behavior.
2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership.
3. Read the focused decision document for the selected behavior.
4. Read `docs/architecture/migration-decisions.md` for OPEN work.
5. Stop and use `archie-architecture-planning-campaign` if a required semantic
decision remains open.
Route to `archie-domain-reference` for glossary and
`archie-config-and-flags` for config enumeration.
Two skills this document routes to are parked outside this checkout, under
`/work/apps/archie-skills-parked/`: `archie-technical-accountability` and
`archie-architecture-planning-campaign`. If your session has not loaded them,
treat each routing target as a manual escalation step rather than a live skill.
Also: `cmd/archied/main.go` is a thin dispatcher; the wiring lives in
`internal/app/archied/`.
## Know the CURRENT system
Do not simplify these facts into the target model:
| Concern | CURRENT runtime truth on 2026-09-18 | Evidence |
| --- | --- | --- |
| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` |
| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` |
| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` |
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` |
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` |
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` |
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` |
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` |
| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` |
### Interpret the current lifecycle honestly
Use these CURRENT status values:
```text
queued, running, waiting_human, pr_open, merged,
parked, dead, rejected, closed_wont_do
```
The intended flow includes queue/claim, workflow stages, human wait/resume, PR
reconciliation, parking/retry/exhaustion, and crash recovery. Read
`internal/domain/workflow/task/task.go`, `internal/daemon/daemon.go`, and
`internal/domain/workflow/workflow.go` before changing a transition.
`Store.Transition(ctx, taskID, from, to, detail)` now guards on `from`
(`WHERE id=? AND status=?`, returning `store.ErrStaleTransition` on mismatch)
and runs the status update plus the transition-history insert in one
transaction (`internal/store/store.go`). The sentinel crosses the State Store
gRPC boundary via `mapError`/`unmapError` in
`internal/infrastructure/staterpc/values.go`; its canonical message string is
part of the wire contract. Earlier non-atomic behavior is the settled fix,
not an open design.
## Preserve the load-bearing invariants
| Invariant | Required action | Status and source |
| --- | --- | --- |
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` |
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` |
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` |
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/store/store.go` |
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` |
| Same-repository execution serializes by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
Run the mechanical plugin guard after changing any plugin or `*Engine`
interface:
```bash
go test ./internal/plugin -count=1
```
## Apply the APPROVED TARGET
Apply ownership rules to migration plans and new seams. Not CURRENT until
production wiring proves the cutover.
### Keep dependency direction inward
```text
domain and shared application contracts <- infrastructure implementations
^
|
application composition
```
1. Put cohesive behavior, vocabulary, state, commands, events, policies,
runtime settings, and required service interfaces with its owning domain.
2. Make infrastructure implement domain-required interfaces and translate
external representations.
3. Let only `internal/app` choose concrete implementations and connect domains.
4. Keep `cmd/*` limited to process input and invoking composition.
5. Use an owned command, event, or approved shared contract across domains.
6. Never let one domain mutate another domain's state or call its internals.
Sources: `docs/architecture/organisation.md`,
`docs/architecture/dependencies-and-contracts.md`.
### Separate interaction, admission, assistance, and execution
```text
channel-neutral Message -> Agent turn -> optional proposed work
-> Work Intake -> AcceptedWorkRequest -> Workflow selects version -> WorkflowExecution
```
- **Messaging** owns canonical messages, conversations, branches, channel correlation, delivery.
- **Agent** owns persistent assistant, continuity, specialization, memory.
- **Work Intake** owns admission, validation, routing, accepted-work-request handoff.
- **Workflow** owns versioned definitions, steps, executions, attempts, outcomes.
Do not equate external issue/message with WorkflowExecution; do not let Work
Intake create one directly.
Sources: `docs/architecture/migration-decisions.md`,
`docs/architecture/agent-system.md`, `docs/architecture/messaging-and-work-intake.md`.
### Separate identity, Agent, conversation, and memory
Use immutable `IdentityID` for target attribution. Keep Identity separate from
Agent. Four fixed memory scopes:
| Scope | Visibility |
| --- | --- |
| Global shared | Shared across Archie |
| Agent-wide | One Agent across users; private by default |
| User-wide | One user across authorized Agents |
| Agent-user relationship | Exactly one Agent and one user |
Do not use conversation branching as a fifth memory scope.
Sources: `docs/architecture/identity.md`, `docs/architecture/agent-system.md`,
`docs/architecture/migration-decisions.md`.
### Dissolve global runtime configuration
Treat `internal/config` as migration source inventory:
- move file/env/overlay/secret decoding to `internal/infrastructure/configuration`;
- let each domain or plugin own typed runtime settings;
- translate external DTOs in `internal/app`;
- never pass complete application config into a domain;
- classify each behavioral value as invariant, runtime setting, policy value,
derived value, or runtime state.
Source: `docs/architecture/configuration.md`.
## Place new behavior deliberately
| Behavior | Target owner/location | Decision gate |
| --- | --- | --- |
| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. |
| Persistent assistant behavior and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. |
| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. |
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. |
| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. |
| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. |
| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. |
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. |
| NATS, SQLite, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
| Deploy assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. |
## Confront known weak points
| Weak point on 2026-09-18 | Required response |
| --- | --- |
| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. |
| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. |
| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/store`: `Transition` guards on `status=?` and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. |
| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. |
| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. |
| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. |
| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. |
| Subprocess uses daemon user and host access. | Not a security boundary. |
| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. |
| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. |
| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. |
| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. |
## Control every architecture-affecting change
| Class | Action |
| --- | --- |
| Current-path repair | Stay inside current owner, preserve invariants. |
| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. |
| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until approved. |
Trace with evidence:
```bash
rg -n '<constructor>|<interface>|<method>' cmd internal
go list -deps ./cmd/archied | rg 'github.com/samcharles93/archie-core/internal/'
gopls references path/to/file.go:<line>:<column>
```
Use `gopls references` or another AST-aware reference query when interfaces,
embedding, generated symbols, or same-named methods make text search ambiguous.
Trace from `cmd/archied/main.go` into `internal/app/archied.Run()`; the wiring
itself is in `internal/app/archied/bootstrap.go`.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Architecture Contract"
short_description: "Protect Archie load-bearing architecture decisions"
default_prompt: "Use $archie-architecture-contract to place and review this change without violating current or target architecture."
@@ -1,251 +0,0 @@
---
name: archie-build-and-env
description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces.
---
# Build and verify the Archie environment
Recreate the environment as independently verified surfaces. Do not turn a
passing root-module command into a claim that the tools module, documentation
site, race detector, linter, or container images also passed.
All volatile observations are snapshots from **2026-09-18** (HEAD `2e1e1549`).
## Name the surfaces
| Term | Meaning here |
|---|---|
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
| Tools module | Independent nested Go module under `tools/`. |
| Docs | Markdown under `docs/`, read directly; no build, no renderer. |
| Cold cache | Dependency cache not yet containing required modules/packages. |
| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. |
No root `README*` or `CONTRIBUTING*` file exists. Begin with:
```bash
sed -n '1,240p' CLAUDE.md
ls docs/architecture/
task --list
```
## Inventory requirements before installing anything
```bash
go version
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
task --version; golangci-lint version; gofumpt -version
node --version; npm --version # UI only; docs need no Node toolchain
docker --version; docker compose version
git --version; gpg --version
```
Classify a missing command as an environment prerequisite. Bootstrap (verified
2026-09-19): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt v0.11.0, golangci-lint 2.13.2,
Node 24.x for the `ui/` frontend.
`task fmt` runs `go fix` and then `golangci-lint fmt`; `task lint` uses the
same binary and `.golangci.yml`, so its gofumpt, goimports, and gci rules have
one owner and the writer converges the checker. Standalone `gofumpt` remains
only for generated protobuf contracts in `tools/proto.sh`.
The three Yaegi secret-engine examples carry `//go:build ignore`. goimports
cannot type-check them and deletes a genuinely used `internal/secret` import,
so `.golangci.yml` excludes those exact files from the formatter set. Their
runtime loading remains covered by `internal/secret/engines_test.go`.
| Surface | Repository declaration | Installed snapshot | Interpretation |
|---|---|---|---|
| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. |
| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. |
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. |
| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. |
| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. |
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
## Prepare writable caches in a restricted sandbox
```bash
go env GOTMPDIR GOCACHE GOMODCACHE GOPATH
df -T /tmp
```
If any default is read-only:
```bash
export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp
export ARCHIE_GOCACHE=/tmp/archie-core-gocache
export ARCHIE_GOMODCACHE=/tmp/archie-core-gomodcache
export ARCHIE_GOPATH=/tmp/archie-core-gopath
export ARCHIE_LINT_CACHE=/tmp/archie-core-golangci
mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
```
Prefix Go commands:
```bash
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
go test ./internal/config/... -count=1
```
Populate cold cache only with network authorized:
```bash
env ... go mod download; env ... go -C tools mod download
```
## Recreate the root Go surface
```bash
test -f go.mod && test -f cmd/archied/main.go && test -f cmd/archie-agent/main.go
go list -m
go build -o /tmp/archie-core-archied ./cmd/archied
go build -o /tmp/archie-core-agent ./cmd/archie-agent
go test ./internal/config/... -count=1
go vet ./...
golangci-lint run ./...
```
## Understand exactly what Task runs
| Task | Exact effect |
|---|---|
| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. |
| `task vet` | `go vet ./...` in the runtime module. |
| `task lint` | `golangci-lint run ./...`. |
| `task build` | Builds both commands into `bin/`. |
| `task test` | `go test ./... -count=1` in the runtime module. |
| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. |
`task check` is the definitive gate but omits race tests, `task vuln`, and
`task docker-build`. Its docs step, `docs:check`, verifies committed generated
data and never renders anything: there is still no documentation build.
Two of its steps check committed artifacts rather than the build, so both fail
on work that is correct but unstaged, and both read as a broken generator:
- `proto:check` regenerates, then runs `git diff --exit-code -- internal/contracts`
and rejects untracked files there. After any `.proto` edit,
`git add internal/contracts proto` before the gate. The failure prints the
regenerated diff, which looks like generation produced something unexpected.
- `ui:check` compares `ui/dist` against a fresh build of `ui/src` and fails when
they differ. `task check` never rebuilds the bundle: run `task ui` after any
`ui/src` change and commit the result with that change.
Run only in an authorized writable worktree. For a read-only ordinary-source
preview, use `golangci-lint fmt --diff`.
## Verify the tools module separately
No `go.work`. Root `go test ./...` does not enter `tools/`.
```text
module github.com/samcharles93/archie-core/tools
replace github.com/samcharles93/archie-core => ../
```
```bash
go -C tools test -mod=readonly ./... -count=1
```
`-mod=readonly` is mandatory on every `go -C tools` command. The `replace`
forces the tools build list to satisfy the root module's requirements, so a
root dependency bump leaves tools stale, and a writable command repairs
`tools/go.mod` and `tools/go.sum` in place, dirtying the tree with an
unrelated diff. Pass the flag explicitly: a global `GOFLAGS=-mod=mod` in
`go env` beats the toolchain default. A failure here means run
`go -C tools mod tidy` and commit that on its own. `task check` runs this via
`task test:tools`.
Generate documentation to temp file:
```bash
go -C tools run -mod=readonly ./docsgen --repo-root .. --out /tmp/archie-core-contracts.json
cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
```
2026-09-18 run wrote 11 schemas. The committed output was stale since
`4b340d2b` and was regenerated the same day; `cmp` now passes. `task docs:check`
now runs inside `task check`, so this drift fails the gate instead of waiting to
be found by hand. `docsgen all` does not exist yet.
Prefer the task over the raw commands:
```bash
task docs:check # non-destructive; fails loudly and names the Go type
task docs:generate # rewrites the committed artifact; review the diff
```
## Documentation needs no build
`docs/` is Markdown read directly in the repository, an editor, or the forge's
file view. Nothing builds, renders, or publishes it.
The VitePress site (`docs/.vitepress/`, `docs/package.json`, the pnpm lockfile),
its landing page, and `.github/workflows/docs.yml` were removed on 2026-09-12 as
an unnecessary build step. Git no longer tracks any `docs/node_modules` entries.
Do not `pnpm install` under `docs/`; it has no package manifest. See
`docs/architecture/generated-documentation.md`, "Rendering and publishing".
Commit `4cb0577` cleaned up accidentally committed `.gotmp`; `.gotmp/` now ignored.
## Treat container setup as a networked, privileged surface
```bash
test -e .dockerignore || echo ".dockerignore is absent"
rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \
Dockerfile Dockerfile.archied docker-compose.yml
```
`.dockerignore` exists (421 bytes) and excludes `.git`, `.task`, `.claude`,
`.codex`, `.crew`, `.agents`, `.references`, `bin/`, `dist/`, `docs/`,
`node_modules/`, root-built `archied`/`archie-agent`, and local config. Both
Dockerfiles still run `COPY . .` on top of it. Floating inputs: Go builder tags
omit patch/digest; Ubuntu base images omit digests; agent installs multiple
`@latest` Go tools; Node from moving `setup_24.x` channel.
`task docker-build` needs registry/network and functioning Compose.
`task docker-up` starts the Compose-managed NATS service and binds ports
4222/8222. The host daemon and its Docker-socket access are outside Compose.
## Separate environment failures from code failures
| Signature | Classify and branch |
|---|---|
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. |
| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. |
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. |
| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. |
| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. |
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. |
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. |
| `Podman configuration ... read-only file system` | Container backend cannot initialize. |
| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. |
For hermetic test diagnosis:
```bash
env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/worktreerpc/... -count=1
```
## Use the complete validation matrix
| Evidence | Command | Current snapshot |
|---|---|---|
| Focused Go behavior | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. |
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. |
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. |
| Vet | `go vet ./...` | Passed on 2026-09-18. |
| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. |
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. |
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. |
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. |
| Container build | `task docker-build` | Not verified in restricted environment. |
| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. |
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Build and Environment"
short_description: "Recreate and verify the Archie toolchain"
default_prompt: "Use $archie-build-and-env to recreate a clean Archie development environment and verify every build surface."
@@ -1,230 +0,0 @@
---
name: archie-codebase-discovery
description: "Trace Archie behavior and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behavior, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects."
---
# Discover the Archie codebase
Use evidence from the current checkout to explain a behavior before changing it.
Volatile tool facts below were verified on **2026-09-18**.
**Composition roots**: `cmd/archied/main.go` (thin dispatcher) →
`internal/app/archied.Run()`, and `internal/app/agentworker` (invoked by
`cmd/archie-agent/main.go`). Do not treat `cmd/*` as the wiring site.
**Production wiring**: a path selected by a shipped entrypoint — not a
constructor, decoder, or passing unit test. **State owner**: component with
authority to validate and persist a state transition.
## Establish a reproducible baseline
```sh
go version; go env GOMOD GOWORK GOOS GOARCH
gopls version; golangci-lint version; staticcheck -version
```
As of 2026-09-18: Go 1.27.0, gopls 0.23.0, golangci-lint 2.13.2,
staticcheck 2026.2.1. Use `gopls call_hierarchy` (no `go tool callgraph`;
`go tool` lists only asm, cgo, compile, cover, fix, link, preprofile, vet).
Writable caches when defaults are read-only:
```sh
export GOCACHE="${TMPDIR:-/tmp}/archie-discovery-gocache"
export GOLANGCI_LINT_CACHE="${TMPDIR:-/tmp}/archie-discovery-lint"
export GOTMPDIR="${TMPDIR:-/tmp}"
export GOPROXY=off GOFLAGS=-mod=readonly
```
Module boundaries (root and `tools/` are separate):
```sh
find . -name go.mod -not -path './.git/*' -not -path './node_modules/*'
go list -m -f '{{.Path}} {{.GoVersion}}'
go -C tools list -mod=readonly -m -f '{{.Path}} {{.GoVersion}}'
```
## Build the behavior trace
Write: behavior, observable input, expected output, state that may change, modes.
| Step | Find | Required evidence |
|---:|---|---|
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration |
| 2 | Construction | Constructor and every direct struct literal |
| 3 | Contract | Interface, wire type, command, event, or public method crossed |
| 4 | Implementation | All type-valid implementations, selected per mode |
| 5 | State owner | Function validating transition, owning concurrency/transaction rules |
| 6 | Persistence | Store adapter, schema/key/document, serialization, reload/recovery |
| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack |
| 8 | Consumer | Callers and downstream readers |
| 9 | Tests | Unit, integration, contract, architecture, production-composition |
| 10 | Configuration | Decode, default, validation, normalization, composition-root consumption |
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps |
Start at these verified anchors:
| Concern | Current anchor |
|---|---|
| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` |
| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` |
| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` |
| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`); `internal/store/interface.go` holds compatibility aliases only |
| Production task persistence | `internal/store/`; `openProductionTaskStore` reached via `internal/app/archied/state_store.go` |
| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) |
| Chat and channels | `internal/gateway/`, `internal/channels/` |
| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` |
| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` |
## Use syntax, type, and call evidence
### Map packages before reading files
```sh
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/store
go list -json ./internal/store
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
```
### Resolve symbols with gopls
1-indexed `file:line:column`:
```sh
gopls symbols internal/domain/storecontract/storecontract.go
gopls definition cmd/archied/main.go:27:14
gopls references -d internal/domain/storecontract/storecontract.go:33:2
gopls implementation internal/domain/storecontract/storecontract.go:33:2
gopls call_hierarchy internal/domain/storecontract/storecontract.go:33:2
go doc ./internal/domain/storecontract.TaskStore
go test ./internal/store -list '.'
```
### Generate AST candidates for construction
```sh
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon .
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task .
```
Confirms candidates with `gopls definition` or `gopls references`. Pass
`-tests` to expose test-only construction.
## Run focused discovery recipes
### Find duplicate behavior paths
```sh
golangci-lint run --enable-only=dupl ./internal/...
rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal
```
Trace each candidate to entrypoint and state owner. `dupl` finds similar syntax,
not two different implementations of one responsibility.
### Find unused-but-compiled code
```sh
staticcheck -checks=U1000 ./internal/...
```
For every suspect: `gopls references -d`; search init, reflection/Yaegi, tags,
RPC subjects, plugin manifests, string dispatch; check build tags/OS files;
search both composition roots. `U1000` does not prove exported/reflection/wire
targets are dead.
### Find interface implementations
```sh
gopls implementation
rg -n 'var _ .*=' --glob '*.go' cmd internal
```
Trace which implementation the composition root selects for each mode.
### Find struct-field consumers
`gopls references -d` on field declaration, not common name. Trace assignments
and reads separately. Follow `ForTask`/`ToConfig` copies. Check JSON/TOML/YAML
tags. Compare production and `_test.go` references.
### Detect constructor bypasses
Run `scan-go-type-syntax.sh Type .`. Inspect struct literals outside owning
package. Compare validation/defaulting in constructors with direct literals.
Use `gopls references` on constructor and type.
### Prove package dependency direction
```sh
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
go list -deps -json <pattern>
```
### Find decoded-but-unused configuration
Prove: `file/key → decoder → default → validation → normalization/copy →
composition-root read → concrete component → observable behavior`.
```sh
rg -n 'toml:"|yaml:"|json:"' internal/config
rg -n 'Resolve|Overlay|Dir|finalize|ForTask|ToConfig' internal/infrastructure/configuration internal/app/archied
gopls references -d <exact-field>
```
Decoding lives in `internal/infrastructure/configuration`, not `internal/config`.
`configuration.New(log)` returns a `Loader`; the composition root in
`internal/app/archied/bootstrap.go` calls `Loader.Resolve` (with `Loader.Overlay`
and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or
`config.LoadDir`.
### Prove production composition
1. Start at `internal/app/archied/main.go` (`Run`), entered from
`cmd/archied/main.go`.
2. Record config condition per branch.
3. Follow concrete construction into `daemon.Daemon` and gateway start.
4. For container/NATS behavior, trace `cmd/archie-agent/main.go` into
`internal/app/agentworker` and `internal/infrastructure/agenttransport/nats`.
5. Trace both sides of every RPC/transport and error/timeout paths.
6. Read contract/architecture tests.
7. Confirm deploy inputs in Compose and CI.
### Trace SQLite persistence
Treat `internal/domain/storecontract` as the application contract and
`internal/store` as the production SQLite adapter behind it.
```sh
gopls implementation internal/domain/storecontract/storecontract.go:33:2
rg -n 'CREATE TABLE|CREATE INDEX|QueryContext|ExecContext|BeginTx' internal/store
```
## Reject false confidence
| Weak evidence | Why it fails | Required correction |
|---|---|---|
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition |
| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence |
| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture |
| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and production selection |
| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references |
| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain |
| Target PRD says it | Not necessarily current code | Cite current implementation and label gap |
## Produce the discovery handoff
1. **Behavior trace:** path:line, symbol, current responsibility per traversal step.
2. **Mode matrix:** mode/config branch → concrete implementation → state store
→ transport → consumer.
3. **State and authority:** owner, copies, persistence, transition rules, recovery.
4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs,
compatibility paths.
5. **Duplication/deprecation ledger:** each candidate, live/dead evidence,
replacement, objective removal gate.
6. **Current-to-target gap:** current fact, target PRD, migration implication.
7. **Unknowns:** exact command, output/blocker, next evidence needed.
Do not propose implementation until the trace answers: what entrypoint selects
this path, which component owns state, which parallel/older path the feature
replaces, which production modes and persisted data must remain compatible,
which evidence would falsify current understanding.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Codebase Discovery"
short_description: "Trace Archie behavior from entrypoint to production"
default_prompt: "Use $archie-codebase-discovery to trace this behavior through production wiring before proposing a change."
@@ -1,36 +0,0 @@
#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
printf '%s\n' "usage: $0 [go-package-pattern]" >&2
exit 2
fi
command -v go >/dev/null 2>&1 || {
printf '%s\n' "error: go is required" >&2
exit 127
}
pattern=${1:-./...}
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
export GOCACHE="$cache_root/go-build"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
module_path=$(go list -m -f '{{.Path}}')
go list -f '{{.ImportPath}}{{range .Imports}}{{printf "\t%s" .}}{{end}}' "$pattern" |
awk -F ' ' -v module="$module_path" '
{
from = $1
for (i = 2; i <= NF; i++) {
if ($i == module || index($i, module "/") == 1) {
printf "%s -> %s\n", from, $i
}
}
}
' |
LC_ALL=C sort -u
@@ -1,176 +0,0 @@
// Command scan-go-type-syntax reports syntax-level construction candidates for
// a named Go type. It deliberately uses only the standard library and never
// writes to the inspected tree.
package main
import (
"bufio"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
type finding struct {
path string
line int
column int
kind string
detail string
}
func main() {
includeTests := flag.Bool("tests", false, "include *_test.go files")
flag.Usage = func() {
fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [-tests] TypeName [root]\n", os.Args[0])
flag.PrintDefaults()
}
flag.Parse()
if flag.NArg() < 1 || flag.NArg() > 2 {
flag.Usage()
os.Exit(2)
}
typeName := flag.Arg(0)
root := "."
if flag.NArg() == 2 {
root = flag.Arg(1)
}
if !token.IsIdentifier(typeName) {
fmt.Fprintf(os.Stderr, "error: %q is not a Go identifier\n", typeName)
os.Exit(2)
}
results, err := scan(root, typeName, *includeTests)
if err != nil {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
os.Exit(1)
}
out := bufio.NewWriter(os.Stdout)
defer out.Flush()
fmt.Fprintln(out, "kind\tlocation\tdetail")
for _, result := range results {
fmt.Fprintf(out, "%s\t%s:%d:%d\t%s\n",
result.kind, result.path, result.line, result.column, result.detail)
}
}
func scan(root, typeName string, includeTests bool) ([]finding, error) {
fset := token.NewFileSet()
var results []finding
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() {
if path == root {
return nil
}
name := entry.Name()
if strings.HasPrefix(name, ".") || name == "node_modules" ||
name == "vendor" || name == "bin" {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(path) != ".go" {
return nil
}
if !includeTests && strings.HasSuffix(path, "_test.go") {
return nil
}
file, err := parser.ParseFile(fset, path, nil, 0)
if err != nil {
return fmt.Errorf("parse %s: %w", path, err)
}
ast.Inspect(file, func(node ast.Node) bool {
switch node := node.(type) {
case *ast.TypeSpec:
if node.Name.Name == typeName {
results = appendFinding(results, fset, node.Name.Pos(),
path, "declaration", "type "+node.Name.Name)
}
case *ast.CompositeLit:
if matchesType(node.Type, typeName) {
results = appendFinding(results, fset, node.Type.Pos(),
path, "literal", "direct composite literal of "+typeName)
}
case *ast.FuncDecl:
if returnsType(node.Type.Results, typeName) {
results = appendFinding(results, fset, node.Name.Pos(),
path, "returns-type", "func "+node.Name.Name)
}
}
return true
})
return nil
})
if err != nil {
return nil, err
}
sort.Slice(results, func(i, j int) bool {
left, right := results[i], results[j]
if left.path != right.path {
return left.path < right.path
}
if left.line != right.line {
return left.line < right.line
}
if left.column != right.column {
return left.column < right.column
}
return left.kind < right.kind
})
return results, nil
}
func appendFinding(results []finding, fset *token.FileSet, pos token.Pos, path, kind, detail string) []finding {
position := fset.Position(pos)
return append(results, finding{
path: filepath.ToSlash(path),
line: position.Line,
column: position.Column,
kind: kind,
detail: detail,
})
}
func returnsType(fields *ast.FieldList, typeName string) bool {
if fields == nil {
return false
}
for _, field := range fields.List {
if matchesType(field.Type, typeName) {
return true
}
}
return false
}
func matchesType(expr ast.Expr, typeName string) bool {
switch expr := expr.(type) {
case *ast.Ident:
return expr.Name == typeName
case *ast.SelectorExpr:
return expr.Sel.Name == typeName
case *ast.StarExpr:
return matchesType(expr.X, typeName)
case *ast.IndexExpr:
return matchesType(expr.X, typeName)
case *ast.IndexListExpr:
return matchesType(expr.X, typeName)
default:
return false
}
}
@@ -1,13 +0,0 @@
#!/bin/sh
set -eu
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
export GOCACHE="$cache_root/go-build"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
exec go run "$script_dir/scan-go-type-syntax.go" "$@"
@@ -1,61 +0,0 @@
#!/bin/sh
set -u
usage() {
printf '%s\n' "usage: $0 file.go:line:column" >&2
exit 2
}
[ "$#" -eq 1 ] || usage
position=$1
command -v go >/dev/null 2>&1 || {
printf '%s\n' "error: go is required" >&2
exit 127
}
command -v gopls >/dev/null 2>&1 || {
printf '%s\n' "error: gopls is required" >&2
exit 127
}
case "$position" in
*.go:[1-9]*:[1-9]*) ;;
*) usage ;;
esac
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/xdg" "$cache_root/tmp" || exit 1
export GOCACHE="$cache_root/go-build"
export XDG_CACHE_HOME="$cache_root/xdg"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
gomod=$(go env GOMOD)
if [ "$gomod" = "/dev/null" ] || [ -z "$gomod" ]; then
printf '%s\n' "error: run from inside a Go module" >&2
exit 1
fi
run_query() {
label=$1
shift
printf '\n== %s ==\n' "$label"
if output=$(gopls "$@" 2>&1); then
printf '%s\n' "$output"
return 0
else
printf '%s\n' "$output"
printf '%s\n' "(query is not applicable at this position, or failed)"
return 1
fi
}
successful=0
run_query "definition" definition "$position" && successful=$((successful + 1))
run_query "references (including declaration)" references -d "$position" && successful=$((successful + 1))
run_query "implementations" implementation "$position" && successful=$((successful + 1))
run_query "call hierarchy" call_hierarchy "$position" && successful=$((successful + 1))
[ "$successful" -gt 0 ]
@@ -1,263 +0,0 @@
---
name: archie-config-and-flags
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, deployments/*.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
---
# Trace Archie configuration and flags
Treat configuration as a dataflow, not as a struct inventory. Prove every
claimed setting has an input, normalization path, composition seam, and runtime
consumer.
Current evidence date: **2026-09-18** for the matrix below. Entries added later
carry their own date inline.
Use these status terms exactly:
| Status | Meaning |
| --- | --- |
| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. |
| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. |
| **test/library-only** | An API and tests exist, but no current binary selects it. |
| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. |
| **external-production-unknown** | The repository does not contain the deployed effective value. |
Never upgrade a status merely because decoding tests pass.
## Trace one setting before editing it
1. Find every external spelling, Go field, flag, environment name, example, and
deployment reference.
2. Identify the selected loader or flag set.
3. Read `finalize` and any consumer-side defaults.
4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess
env selection, container env construction, and identity overlays.
5. Find the production composition site and final behavior-changing read.
6. Find tests for decoding, defaulting, invalid input, production composition,
and mode parity.
7. Check `config.example.toml`, `deployments/*.toml`, `docker-compose.yml`, and
deployment environment passthrough.
8. Assign one status from the table above.
```bash
rg -n 'Resolve|Overlay|Dir|ForTask|ToConfig|flag\.' \
internal/infrastructure/configuration internal/config internal/app/archied cmd/archie-agent
rg -n 'FIELD_NAME|external_key|ENV_NAME' \
--glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' .
```
## Select the real input path
| Input path | Current behavior | Status |
| --- | --- | --- |
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired |
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. This is the only overlay: the dashboard runtime overlay and its SQLite store were deleted when the control plane took over settings writes. | production-wired |
| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable |
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example |
| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown |
Both TOML and YAML decoding are non-strict at the field level. Add explicit
compatibility and typo tests; never use "the file loaded" as evidence that a
key took effect.
A registered service client always resolves to a non-empty target, so
`Services.Get(name).Target != ""` proves nothing. `RegisterService` in
`internal/config/servicespec.go` supplies the fallback (`127.0.0.1:9090` for
the State Store, `127.0.0.1:8585` for the Gateway), which means a guard written
as "only dial when configured" dials always, and a test that sets no target
reaches for a real process on the developer's machine. Gate on an explicit
flag or on the dial succeeding, and give a binary its own
`-<service>-target` flag so tests can point it at a fake.
## Inventory CLI flags
### Public binaries
| Binary | Flag | Default and effect |
| --- | --- | --- |
| `archied` | `-config PATH` | Computed config path described above. |
| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in second TOML. |
| `archied` | `-once` | `false`; run one poll/process cycle and exit. |
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` also set. |
| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. |
| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. |
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. |
The standalone agent always reads its token from `NATS_TOKEN`; there is no
token flag.
### Internal codesearch helper
`archied workspace-codesearch` bypasses daemon configuration before normal flag
parsing:
| Subcommand | Required flags | Optional flags |
| --- | --- | --- |
| `build` | `--root`, `--index` | none |
| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` |
Do not expose these helper flags as daemon settings.
## Read the current wiring matrix
### Root daemon and capability settings
| Keys | Default, validation, and consumer | Status |
| --- | --- | --- |
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `db_path` is a prefix: tasks/events use `<db_path>-tasks.sqlite` and conversations use `<db_path>-conversations.sqlite`. | production-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired |
| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired |
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired |
| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalizes to empty. | production-wired |
| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired |
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalog. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
| `agent.mode` | Default `nats` when containers enabled, otherwise `inprocess`; validates `inprocess`, `subprocess`, or `nats`. | production-wired |
| `agent.command`, `agent.env` | Command defaults `archie-agent`; env entries must be nonblank names without `=`. | partially-wired |
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
| `nats.url`, `token_env` | Empty URL keeps SQLite path. Configured token variable must be non-empty. | production-wired |
| `containers.*` | See dedicated table below. | production-wired |
| `chat.*` | See channel table below. | production-wired |
| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired |
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired |
| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired |
| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired |
**Three shapes of an unwired field.** All three read as working from the file
alone, and only the first two are defects - so establish which shape you are
looking at before reporting one:
1. **not-consumed.** Decoded and normalized, but no production consumer uses the
effective value (`memory.provider` and `indexing.*` above; per-identity intake
was this shape until 2026-09-22, when the configuration was made to reject it
rather than accept it).
2. **not-projected.** A read exists, but at a layer that does not own the
effective copy, so editing the wrong layer does nothing. Direction matters as
much as presence: for most `[chat.*]` keys the stored resource outranks the
file, so writing a new file value is a no-op once a resource exists. A file
key in that position is a **seed**, not the contract.
3. **deliberately-not-projected.** File-only by design and therefore
indistinguishable from a dropped field to an auditor unless the projection
says so in a comment. `runtimeChatConfigFrom` reads
`Telegram.UpdateCheckCommand`/`UpdateInstallCommand` from `base` rather than
from the stored resource, on purpose. Check for that comment before filing a
defect.
The default `agent.command = "archie-agent"` is not verified subprocess
operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON
response on stdout; `cmd/archie-agent` is a long-running NATS worker.
### Repository settings
| Keys | Effective behavior | Status |
| --- | --- | --- |
| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired |
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired |
| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired |
| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired |
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired |
| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired |
| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired |
| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
### Container settings
| Key | Effective behavior |
| --- | --- |
| `enabled` | Requires non-empty `image`, `agent.mode = "nats"`, and non-empty `nats.url`. |
| `image` | Required only when enabled. |
| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. |
| `max_uptime` | Default `60m` only when enabled; caps container lifetime. |
| `volume_ttl` | Default `72h` only when enabled; negative rejected. |
| `pull_policy` | Default `missing` when enabled. Pool code recognizes `missing` and `always`; other strings silently skip pre-pull. |
| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. |
### Channel settings
| Keys | Effective behavior |
| --- | --- |
| `chat.models` | Optional interactive catalog; empty falls back to workflow model references. |
| `chat.telegram.token_env` | Empty disables Telegram; non-empty names env variable; empty value is fatal. |
| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. |
| `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status; install further enables approved installation. |
| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. |
| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. |
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
token and allowed-user list. Every other file setting is startup-only.
## Treat multi-identity as partially wired
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
type, and `SecretRef` token. `internal/app/archied` builds an identity forge
client and worktree manager.
Do not infer complete isolation:
- `internal/app/archied` resolves root forge client before all identity runners.
- Identity `name`, forge, repos, poll interval, bot user, bot email have
production reads. Identity bot email not defaulted despite comment.
- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and
`diff_cap_lines` decode but workflows still receive root `Config`.
- Identity polling reads root `dispatch`, `label`, and `bot_user`.
- Container task snapshots and provider maps come from root config; task RPC
servers are root-forge/root-worktree.
- Root-only concurrency lookup ignores identity repo `allow_concurrent`.
Classify multi-identity changes field by field. Never label aggregate
`IdentityConfig` production-wired.
## Preserve worker and secret boundaries
`Config.ForTask` creates a detached root snapshot: models, budgets, dispatch,
diff cap, notification, and forge host. `TaskConfig.ToConfig` reconstructs
only those fields. Forge tokens, provider values, NATS credential references,
repos, and infrastructure settings do not enter `TaskConfig`.
At top-level `[forge]`, prefer `token = {engine = "env", key = "NAME"}`. The
`token_env = "NAME"` form is converted only when structured reference is empty;
structured reference wins when both appear. This compatibility rule exists
because an earlier migration silently dropped deployed `token_env` values and
crash-looped the daemon. `finalize` does not apply that conversion inside each
identity: identity forges require explicit structured `token`.
| Source | Archied | Subprocess | Agent container / standalone worker |
| --- | --- | --- | --- |
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. |
| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. |
| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. |
| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. |
| `agent.env = ["X"]` | Names validated. | Copies present `X` from daemon env. | Not used by container construction. |
`internal/app/archied` creates `secret.NewRegistry`, which registers only the
`env` engine. Non-env `SecretRef` values are not production-wired.
The host supervisor or launch shell supplies daemon secrets. Compose supplies
no `archied` environment because the daemon is not a Compose service.
## Follow the approved target
Current code puts infrastructure paths, domain policy, channel settings,
secrets, execution settings, repository associations, and extension data in one
mutable `config.Config`. Treat this as a current load-bearing weakness, not a
pattern to copy.
`docs/architecture/configuration.md` is approved as of 2026-07-28:
- move file/env/secret/overlay loading to private
`internal/infrastructure/configuration` input boundary;
- translate inputs in `internal/app`;
- give each domain/plugin typed owned settings and validation;
- dissolve `internal/config` rather than rename the global model;
- split `Repo` and `IdentityConfig` by actual capability ownership.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Config and Flags"
short_description: "Trace Archie configuration from input to runtime"
default_prompt: "Use $archie-config-and-flags to trace this Archie setting or CLI flag from declaration through production wiring."
@@ -1,231 +0,0 @@
---
name: archie-debugging-playbook
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports SQLite state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
---
# Debug Archie from evidence
**current** = 2026-09-18 verified (HEAD `2e1e1549`); **fixed history** =
regression patterns; **open** = verified gap.
**Composition root**: `cmd/archied/main.go` → `internal/app/archied.Run()`;
wiring lives in `internal/app/archied/bootstrap.go`. **Core NATS
request/reply**: direct subject + reply inbox. **JetStream**: persisted stream
`ARCHIE_TASKS`. **State Store**: gRPC (`internal/infrastructure/staterpc`), not
NATS.
**Environment failure**: test/process cannot use host resource (listener, tmp,
Docker). **Code regression**: behavior fails where prerequisites available.
## Run the first-ten-minutes protocol
Do not begin with `task check` (mutates via `gofumpt -w .`/`go fix ./...`).
Compile, then run:
```bash
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^TestName$' -count=1 -v
```
Classify: compile-only, listener failure, read-only tmp, code regression.
- Behavioral assertion with the prerequisite available: code regression.
Use this symptom index:
| Symptom | First boundary | Go to |
|---|---|---|
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 |
| Embedded NATS panics before a test assertion | Listener permission | Test environment |
| `nats: no responders available for request` | Core NATS subscription | NATS request/reply |
| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply |
| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply |
| Config test passes but daemon ignores the field | Composition/wiring | Configuration |
| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration |
| Telegram reply hangs on the first token | Stream consumer | Streaming |
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
| Transition succeeds from the wrong state | Store semantics | SQLite/state |
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
| Search works but never becomes indexed | Missing production wiring | Optional features |
| Agent container cannot resolve `nats` | Docker network | Containers |
| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode |
## Separate test-environment failures from regressions
```bash
go version
go env GOTMPDIR GOCACHE GOPATH GOMODCACHE GOENV
```
Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP
listeners:
```bash
rg -n 'httptest\.NewServer|net\.Listen|RunRandClientPortServer|RunServer' \
--glob '*_test.go' cmd internal
```
Do not attribute go-git commit failures to GPG without checking the
repository-local mitigation. `worktree.Manager.setIdentity` pins
`commit.gpgsign=false`. Isolate ambient global config:
```bash
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1
```
## Confirm the skill-script regression stays fixed
The `TestRunWrapsExternalCommand` failure (`Run() = "\n"`) was a test bug, not
a product bug: `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`
passes `wrapped` as shell `$0`, so only `echo` ran. It failed from commit
`308c199` and **passes as of 2026-09-16**. Re-run it to confirm the fix has not
regressed; a failure now is a new defect, not this one.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
-run '^TestRunWrapsExternalCommand$' -count=1 -v
```
## Triage NATS request/reply and JetStream
| Surface | Subject or resource | Bound/current behavior |
|---|---|---|
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
| Per-stage agent request | `archie.agent.<task>.request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m |
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry 20s every 250ms |
| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only |
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m |
| Discovery dedup | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window 2m |
```bash
docker compose ps
docker compose logs --since=10m nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
Branch on `no responders`: container startup lag if responder appears within 20s;
inspect agent's network/environment if every task exhausts window; confirm
`registerTaskRPCServers` if only RPC calls time out.
**Fixed history:** auto-detection once put task containers on default bridge;
explicit `containers.network` plus warning logs now fence that path.
Check semantics: republishing same owner/repo/issue within 2m is dedup'd; reply
inbox auto-unsubscribes after one response; `Client.Fetch` must inspect
`batch.Error()`; an empty poll reports `eventbus.ErrNoMessage` rather than
`(nil, nil)`.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
go test ./internal/infrastructure/eventbus/nats -run 'TestPublishUniqueSuppressesDuplicateKeyOnWorkQueueStream' -count=1 -v
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
go test ./internal/agentexec -run '^TestToolSetHandler' -count=1 -v
```
## Trace configuration from source to behavior
Trace: `cmd/archied` (`internal/app/archied/bootstrap.go`) reads
`-config`/`-config-overlay` → `configuration.New(log)` + `Loader.Resolve`
decodes, `finalize` defaults/validates → secrets resolve → composition root
constructs service → Compose/subprocess/`containerEnv` propagate → consumer.
```bash
rg -n 'Loader\.(Resolve|Overlay|Dir)|configuration\.' internal/app/archied internal/infrastructure/configuration
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
go test ./internal/infrastructure/configuration \
-run 'Test(ResolveSelectsFileFormatsAndDirectories|LoadForgeTokenEnvBackwardCompat)' -count=1 -v
```
The `config.Load`/`config.LoadDir` helpers are gone; decoding is
`Loader`-based. A YAML field decoding correctly without a composition-root read
is a wiring gap, not a parser bug.
For environment failures:
- The host supervisor supplies the daemon environment; inspect its unit or
launch environment rather than Compose.
- `containerEnv` translates configured NATS token name into `NATS_TOKEN` and
forwards configured provider key variables.
- `SubprocessRunner` forwards default compatibility variables, configured
`[agent].env` names, and only the requested provider key.
- Top-level `[forge] token_env` is converted to an env `SecretRef` by
`finalize`; explicit `[forge.token]` wins.
Do not print secret values.
## Diagnose streaming, MCP, and Telegram
### Streaming
Must drain `stream.FullStream`, collect `core.StreamPartTextDelta`, check
`FinishReason`. `TextStream` is best-effort. **Fixed history:** consuming
`TextStream` while `FullStream` unread deadlocked every reply.
### MCP
Stdio framing is one compact JSON-RPC object per line. Stale
`internal/tools/mcp/types.go` comment mentions `Content-Length` — not the
implemented contract.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \
go test ./internal/tools/mcp \
-run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' -count=1 -v
```
Test helper and client share the same `readMessage`/`writeMessage` — can mirror
mistakes. With `npx`:
```bash
ARCHIE_TEST_DESKTOP_COMMANDER=1 env GOTMPDIR=/tmp \
GOCACHE=/tmp/archie-mcp-integration-gocache \
go test ./internal/tools/provider/mcp \
-run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
```
Gate: non-empty discovery with `start_process`, `interact_with_process`,
`read_process_output`.
### Telegram
Three command scopes in `internal/channels/telegram/commands.go`: default, all
private chats, all group chats. Narrower scope shadows default; state keyed by
bot token. Empty `allowed_user_ids` denies everyone.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
go test ./internal/channels/telegram \
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|SessionManagementCommandsArePublished)$' \
-count=1 -v
```
**Fixed history:** publishing only default left ~60 old Hermes commands visible.
## Diagnose state, events, containers, and optional features
### SQLite and transitions
`internal/store.Store.Transition` owns task state changes and transition
history: it guards on `from` (`WHERE id=? AND status=?`, returning
`store.ErrStaleTransition`) and writes status plus history in one transaction.
When state is surprising: read `TaskByID` before/after caller; trace every
`Transition`, `Requeue`, `RecoverStale`, `Update` — and remember the daemon
exposes these over the gRPC State Store, not NATS.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/store -count=1
```
### Events
DB sink buffer 256; SSE client buffers 64. Drop counter not read in production.
Dashboard gap can coexist with correct task state.
### Containers, worktrees, and subprocess mode
Container-mode: clones on host, mounts `/data/worktree`, writes `.git/task.json`,
dedicated `archie.taskrun.<id>` subscription. **Open:** container RPC is
root-identity-bound; `SubprocessRunner` expects stdin JSON protocol.
### Optional feature degradation
| Feature | Current failure behavior |
|---|---|
| Daemon plugins | Warn and skip |
| Invalid MCP config | Warn and continue |
| Skill catalog | Warn, continue without tool |
| Worktree augmentation | Log error, use startup registry |
| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` |
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Debugging Playbook"
short_description: "Diagnose Archie failures from symptoms"
default_prompt: "Use $archie-debugging-playbook to diagnose this Archie failure from symptoms and evidence."
@@ -1,265 +0,0 @@
---
name: archie-diagnostics-and-tooling
description: "Measure Archie codebase maintainability, Go package dependency shape, configuration consumption, production composition, test and delivery-gate drift, tracked-artifact hygiene, coverage, races, and runtime evidence. Load when establishing a dated baseline, finding large or complex functions, investigating duplicate or dead-path candidates, checking whether configuration reaches an entrypoint, comparing architecture before and after a refactor, or replacing an eyeballed quality claim with reproducible numbers."
---
# Measure Archie instead of eyeballing it
Collect evidence before judging quality. Keep collection read-only, save raw
output, state what each metric cannot prove.
Volatile facts and numeric snapshots below were verified on **2026-09-18**
(HEAD `2e1e1549`).
Route to `archie-codebase-discovery` for semantic traces,
`archie-config-and-flags` for config enumeration,
`archie-debugging-playbook` for live failures.
## Define the measurement terms
- **Baseline:** dated raw output tied to a commit, toolchain, command, and
environment.
- **Candidate:** a machine-found item requiring semantic confirmation.
- **Production composition:** concrete construction selected by a shipped
entrypoint. Principal: `cmd/archied/main.go` → `internal/app/archied.Run()`.
- **Fan-in:** number of packages in the same module that directly import a
package.
- **Fan-out:** number of packages in the same module that a package directly
imports.
- **Physical line:** a newline-delimited source line, including comments and
blanks.
- **Syntactic complexity:** this skill's approximation: one plus `if`, loop,
non-default case, communication clause, `&&`, and `||` nodes.
## Establish a reproducible snapshot
```sh
export LC_ALL=C
export GOCACHE=/tmp/archie-diagnostics-gocache
export GOTMPDIR=/tmp
export XDG_CACHE_HOME=/tmp/archie-diagnostics-xdg
export GOLANGCI_LINT_CACHE=/tmp/archie-diagnostics-lint
export GOPROXY=off
export GOFLAGS=-mod=readonly
skill=.agents/skills/archie-diagnostics-and-tooling
stamp=$(date -u +%Y%m%dT%H%M%SZ)
evidence_dir=/tmp/archie-diagnostics-"$stamp"
mkdir -p "$evidence_dir"
git rev-parse --verify HEAD >"$evidence_dir/revision.txt"
git status --short >>"$evidence_dir/revision.txt"
go version >"$evidence_dir/tools.txt"
gopls version >>"$evidence_dir/tools.txt"
golangci-lint version >>"$evidence_dir/tools.txt"
staticcheck -version >>"$evidence_dir/tools.txt"
go run "$skill/scripts/source-metrics.go" -root . >"$evidence_dir/source.tsv"
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
```
Both filesystem-walking scripts (`source-metrics.go`,
`config-use-candidates.go`) skip `.worktrees/`, which holds live git worktrees
nested inside the repo root. Each is a near-complete copy of the module, so
walking them multiplies every count by the number of checkout worktrees. If a
new nested-checkout convention appears, extend `excludedDirectory` in both;
`.git/info/exclude` does not help, because the scripts walk the filesystem
rather than `git ls-files`. `package-shape.sh` reads `go list`, so it is immune.
## Use the bundled reports
### Measure source shape
```sh
go run "$skill/scripts/source-metrics.go" -root . -top 30
```
Read its tab-separated schema:
| Record | Columns after record name |
|---|---|
| `META` | key, value |
| `METRIC` | module, metric, integer |
| `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines |
| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity |
The defaults (80 body lines, complexity 15) mirror numeric triage points in
`.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run configured
linters for authoritative findings:
```sh
golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/...
```
If a hotspot shrinks, verify that responsibility moved to a cohesive owner.
Moving the same work into unowned helpers is not improvement.
### Measure package shape
```sh
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-root.tsv" |
sort -nr -k1,1 -k2,2 |
sed -n '1,20p'
```
Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. High fan-in
signals change risk; high fan-out signals orchestration. The report contains
only direct, intra-module imports.
### Find configuration-consumption candidates
```sh
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
rg 'candidate-no-(selector-outside-config|entrypoint-selector)' "$evidence_dir/config.tsv"
```
Read each `CONFIG_FIELD` row as path, line, Type.Field, tags, same-name
definition count, config-package selectors, cmd selectors, other-production
selectors, test selectors, generated selectors, candidate status. The report
finds named fields with `toml`/`yaml`/`json` tags in `internal/config`, then
counts selectors with the same **spelling**. It is deliberately fast and not
type-aware.
Only `candidate-no-selector-outside-config` is a signal.
`candidate-no-entrypoint-selector` fires for ~180 of 196 rows because the
script looks for selectors only in `cmd/`, and most fields are read from the
composition root under `internal/app/archied`. Even the signal row has false
positives: a field consumed by **spelling** rather than by a Go selector
(`LegacyEnabled` via the reload allowlist map, `ReloadStatus.*` via JSON
marshalling) reports zero. Confirm each candidate by hand before calling a
field dead.
For every candidate: run `gopls references -d` on the exact field identifier;
trace decode → default → validation → normalization/copy → composition-root read
→ concrete component → observable behavior.
### Measure delivery and hygiene drift
```sh
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
```
Read: `SURFACE axis scope literal_count` as literal text evidence;
`HYGIENE metric count` as tracked-path candidates; `MODULE path` as discovered
Go module boundaries. The snapshot compares Task, GitHub CI, and
composition-root anchors under `internal/app/archied`.
Composition-root anchors must name the file that actually does the wiring.
`cmd/archied/main.go` is a thin dispatcher that routes to
`internal/app/archied`; anchoring on it yields a silent `0` for every row,
which reads as "no composition root" rather than "wrong file". A zero here is
evidence about the anchor, not about production.
Inspect hygiene candidates directly:
```sh
git ls-files |
rg '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$'
git ls-files -s | awk '$1=="120000" {print}'
```
## Investigate duplication and hidden dead paths
```sh
golangci-lint run --enable-only=dupl ./internal/...
```
```sh
staticcheck -checks=U1000 ./internal/...
```
On 2026-09-18, the focused `dupl` command reported zero issues. Two code paths
can implement the same responsibility with different syntax.
For every candidate: name the externally visible operation; search all
entrypoints and modes; use `gopls call_hierarchy`, `gopls references -d`, and
AST construction scan; check interfaces, registrations, reflection, build tags,
OS files, and wire names; identify what a new feature supersedes; record
production-only, test-only, compatibility, generated, and unreachable paths
separately.
As of 2026-09-18, `Taskfile.yml` defines no `deadcode` task and `go tool` lists
no dead-code analyzer.
## Collect test, race, coverage, and runtime evidence
```sh
go test ./internal/store -count=1 -coverprofile=/tmp/archie-store.cover
go tool cover -func=/tmp/archie-store.cover
go test -race ./internal/store -count=1
```
As of 2026-09-18, the package reported 78.6% statement coverage and passed its
race run.
```sh
docker compose logs nats >"$evidence_dir/nats.log"
journalctl --user -u archied >"$evidence_dir/archied.log"
curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt"
```
Run only when local Compose stack is in scope.
## Compare before and after
Predict exact deltas before changing code. Collect a second snapshot with the
same script revision, flags, environment, and toolchain:
```sh
after_dir=/tmp/archie-diagnostics-after
mkdir -p "$after_dir"
go run "$skill/scripts/source-metrics.go" -root . >"$after_dir/source.tsv"
go run "$skill/scripts/config-use-candidates.go" -root . >"$after_dir/config.tsv"
"$skill/scripts/package-shape.sh" . >"$after_dir/packages-root.tsv"
"$skill/scripts/delivery-snapshot.sh" >"$after_dir/delivery.tsv"
diff -u "$evidence_dir/source.tsv" "$after_dir/source.tsv"
diff -u "$evidence_dir/config.tsv" "$after_dir/config.tsv"
diff -u "$evidence_dir/packages-root.tsv" "$after_dir/packages-root.tsv"
diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv"
```
If output differs from prediction: confirm checkout, dirty state, script
revision, flags, toolchain; explain each delta; branch to semantic discovery
when a count cannot explain behavior. Reject a "better" metric that moved
duplication, hid a path, or weakened a gate.
## Dated current snapshot
The bundled scripts measured this checkout on 2026-09-18 (HEAD `2e1e1549`).
These are post-fix numbers: earlier runs of the same scripts reported roughly
3x these file and line counts because they walked `.worktrees/`.
| Observation | Unstable value |
|---|---:|
| Root production/test/generated Go files | 408 / 402 / 9 |
| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 |
| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 |
| Root internal packages / direct internal edges | 110 / 316 |
| Tagged config field rows | 194 |
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 |
| `.dockerignore` present | 1 |
`source-metrics.go` and `git ls-files` reconcile here: 408 + 9 generated
production files and 402 test files, plus the `tools` module's 5 / 2 / 0,
against 422 non-test and 403 test tracked files. The single extra file is an
untracked probe under `.local/issue-tracker/probes/`.
The scripts count themselves: the skill's own Go files contribute 640 of those
production lines. Editing a bundled script therefore moves
`production_physical_lines` on its own, so re-baseline after any script change
rather than reading the delta as a change in the product code.
The delivery snapshot found no Taskfile literals for race; docs now has 6 and
the `tools` module 7, both grown by wiring `task docs:check` into the gate;
GitHub `go gate` 4 and container publish 3; and non-zero literals for all five
composition-root anchors under `internal/app/archied`.
The focused test
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
failed on 2026-07-28 with `Run() = "\n"` and **passes** as of 2026-09-16.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Diagnostics and Tooling"
short_description: "Measure maintainability, wiring, and delivery drift"
default_prompt: "Use $archie-diagnostics-and-tooling to collect a dated, reproducible evidence baseline before changing Archie."
@@ -1,283 +0,0 @@
// Command config-use-candidates reports syntax-level selector evidence for
// tagged fields declared by internal/config. Results are candidates, not proof
// that a field is wired, live, or dead.
package main
import (
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"reflect"
"sort"
"strconv"
"strings"
)
type fieldDefinition struct {
path string
line int
typeName string
fieldName string
tags string
duplicates int
}
type referenceCounts struct {
config int
entrypoint int
production int
test int
generated int
}
func main() {
root := flag.String("root", ".", "repository root to inspect")
flag.Parse()
absoluteRoot, err := filepath.Abs(*root)
if err != nil {
fail(2, "resolve root: %v", err)
}
info, err := os.Stat(absoluteRoot)
if err != nil {
fail(2, "inspect root: %v", err)
}
if !info.IsDir() {
fail(2, "root is not a directory: %s", absoluteRoot)
}
fset := token.NewFileSet()
fields, err := readFieldDefinitions(absoluteRoot, fset)
if err != nil {
fail(1, "%v", err)
}
if len(fields) == 0 {
fail(1, "no tagged fields found under internal/config")
}
nameCounts := map[string]int{}
for _, field := range fields {
nameCounts[field.fieldName]++
}
for index := range fields {
fields[index].duplicates = nameCounts[fields[index].fieldName]
}
references := map[string]*referenceCounts{}
for name := range nameCounts {
references[name] = &referenceCounts{}
}
if err := countSelectors(absoluteRoot, fset, references); err != nil {
fail(1, "%v", err)
}
sort.Slice(fields, func(i, j int) bool {
if fields[i].typeName != fields[j].typeName {
return fields[i].typeName < fields[j].typeName
}
if fields[i].fieldName != fields[j].fieldName {
return fields[i].fieldName < fields[j].fieldName
}
if fields[i].path != fields[j].path {
return fields[i].path < fields[j].path
}
return fields[i].line < fields[j].line
})
fmt.Println("META\tschema\tarchie-config-use-candidates/v1")
fmt.Println("META\tmeaning\tselector-name counts are heuristic candidates; confirm exact fields with gopls references and production composition")
for _, field := range fields {
count := references[field.fieldName]
status := "candidate-selector-seen-in-entrypoint"
switch {
case count.production == 0 && count.entrypoint == 0:
status = "candidate-no-selector-outside-config"
case count.entrypoint == 0:
status = "candidate-no-entrypoint-selector"
}
fmt.Printf(
"CONFIG_FIELD\t%s\t%d\t%s.%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\t%s\n",
field.path,
field.line,
field.typeName,
field.fieldName,
field.tags,
field.duplicates,
count.config,
count.entrypoint,
count.production,
count.test,
count.generated,
status,
)
}
}
func readFieldDefinitions(root string, fset *token.FileSet) ([]fieldDefinition, error) {
configDir := filepath.Join(root, "internal", "config")
info, err := os.Stat(configDir)
if err != nil {
return nil, fmt.Errorf("inspect internal/config: %w", err)
}
if !info.IsDir() {
return nil, fmt.Errorf("internal/config is not a directory")
}
var fields []fieldDefinition
err = filepath.WalkDir(configDir, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" || strings.HasSuffix(entry.Name(), "_test.go") {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", path, err)
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
for _, declaration := range file.Decls {
general, ok := declaration.(*ast.GenDecl)
if !ok || general.Tok != token.TYPE {
continue
}
for _, specification := range general.Specs {
typeSpec, ok := specification.(*ast.TypeSpec)
if !ok {
continue
}
structType, ok := typeSpec.Type.(*ast.StructType)
if !ok {
continue
}
for _, field := range structType.Fields.List {
tags, ok := configTags(field.Tag)
if !ok {
continue
}
for _, name := range field.Names {
fields = append(fields, fieldDefinition{
path: relative,
line: fset.Position(name.Pos()).Line,
typeName: typeSpec.Name.Name,
fieldName: name.Name,
tags: tags,
})
}
}
}
}
return nil
})
return fields, err
}
func configTags(literal *ast.BasicLit) (string, bool) {
if literal == nil {
return "", false
}
raw, err := strconv.Unquote(literal.Value)
if err != nil {
return "", false
}
tag := reflect.StructTag(raw)
var parts []string
for _, key := range []string{"toml", "yaml", "json"} {
value, ok := tag.Lookup(key)
if !ok {
continue
}
parts = append(parts, key+"="+value)
}
return strings.Join(parts, ";"), len(parts) > 0
}
func countSelectors(root string, fset *token.FileSet, references map[string]*referenceCounts) error {
return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
if entry.IsDir() {
if relative != "." && excludedDirectory(relative, entry.Name()) {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(entry.Name()) != ".go" {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relative, err)
}
generated := ast.IsGenerated(file)
isTest := strings.HasSuffix(entry.Name(), "_test.go")
inConfig := strings.HasPrefix(relative, "internal/config/")
inEntrypoint := strings.HasPrefix(relative, "cmd/")
ast.Inspect(file, func(node ast.Node) bool {
selector, ok := node.(*ast.SelectorExpr)
if !ok {
return true
}
count := references[selector.Sel.Name]
if count == nil {
return true
}
switch {
case generated:
count.generated++
case isTest:
count.test++
case inConfig:
count.config++
case inEntrypoint:
count.entrypoint++
default:
count.production++
}
return true
})
return nil
})
}
// excludedDirectory reports whether a walked directory is outside the module.
//
// ".worktrees" holds live git worktrees of this same repository, nested inside
// the root. countSelectors walks the whole root, so without this every selector
// count is multiplied by the number of checkout worktrees.
func excludedDirectory(_, name string) bool {
switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp", ".worktrees":
return true
}
return false
}
func fail(code int, format string, arguments ...any) {
fmt.Fprintf(os.Stderr, "config-use-candidates: "+format+"\n", arguments...)
os.Exit(code)
}
@@ -1,95 +0,0 @@
#!/bin/sh
set -eu
if [ "$#" -ne 0 ]; then
printf '%s\n' "usage: delivery-snapshot.sh" >&2
exit 2
fi
for tool in git rg sed wc; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'delivery-snapshot: %s is required\n' "$tool" >&2
exit 127
}
done
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
if [ ! -f "$repo_root/go.mod" ] || [ ! -f "$repo_root/Taskfile.yml" ]; then
printf 'delivery-snapshot: expected Archie repository root at %s\n' "$repo_root" >&2
exit 2
fi
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-delivery-snapshot.XXXXXX")
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
cd "$repo_root"
printf '%s\n' "META schema archie-delivery-snapshot/v1"
scan_literal() {
axis=$1
scope=$2
pattern=$3
shift 3
result="$temporary/$axis"
if rg -n --no-heading --color never -e "$pattern" "$@" >"$result"; then
:
else
status=$?
if [ "$status" -ne 1 ]; then
printf 'delivery-snapshot: scan failed for %s\n' "$axis" >&2
exit "$status"
fi
fi
count=$(wc -l <"$result" | sed 's/[[:space:]]//g')
printf 'SURFACE\t%s\t%s\t%s\n' "$axis" "$scope" "$count"
}
scan_literal task_format taskfile 'gofumpt[[:space:]]+-w|go fix' Taskfile.yml
scan_literal task_vet taskfile 'go vet' Taskfile.yml
scan_literal task_build taskfile 'go build|task:[[:space:]]+build' Taskfile.yml
scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml
scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml
scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
scan_literal task_docs taskfile 'docsgen|docs:generate|docs:check' Taskfile.yml
# One CI surface: .github/workflows. The Gitea workflow was dropped in dd9bddc2
# ("ci: build and push images to GHCR, drop the Gitea workflow"), so scanning
# .gitea/workflows aborted the whole snapshot under `set -eu`.
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
scan_literal github_container_publish github-workflows 'docker build|docker push|docker/build-push-action|docker login' .github/workflows
# Composition root. cmd/archied/main.go is now a ~30-line dispatcher that only
# routes to internal/app/archied, so anchoring on it reported a silent zero for
# every row below -- which reads as "no composition root" rather than "wrong
# file". The wiring lives in internal/app/archied.
scan_literal production_config_resolve composition-root 'configuration\.New\(' internal/app/archied
scan_literal production_config_load composition-root 'loadConfig\(|loadRuntimeConfig\(' internal/app/archied
scan_literal production_sqlite_store composition-root 'openProductionTaskStore\(|openStateStore\(' internal/app/archied
scan_literal production_daemon composition-root '&daemon\.Daemon\{' internal/app/archied
scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' internal/app/archied
git ls-files >"$temporary/tracked"
tracked_total=$(wc -l <"$temporary/tracked" | sed 's/[[:space:]]//g')
tracked_node_modules=$(rg -c '(^|/)node_modules(/|$)' "$temporary/tracked" || true)
tracked_artifacts=$(rg -c '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' "$temporary/tracked" || true)
tracked_symlinks=$(git ls-files -s | awk '$1 == "120000" {count++} END {print count + 0}')
printf 'HYGIENE\ttracked_paths\t%s\n' "$tracked_total"
printf 'HYGIENE\ttracked_node_modules_paths\t%s\n' "${tracked_node_modules:-0}"
printf 'HYGIENE\ttracked_artifact_candidates\t%s\n' "${tracked_artifacts:-0}"
printf 'HYGIENE\ttracked_symlinks\t%s\n' "$tracked_symlinks"
if [ -f .dockerignore ]; then
printf '%s\n' "HYGIENE dockerignore_present 1"
else
printf '%s\n' "HYGIENE dockerignore_present 0"
fi
find . \
\( -path './.git' -o -path './.claude' -o -path './.references' -o -name node_modules -o -name .worktrees \) -prune -o \
-name go.mod -print |
LC_ALL=C sort |
while IFS= read -r module; do
printf 'MODULE\t%s\n' "$module"
done
@@ -1,86 +0,0 @@
#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
printf '%s\n' "usage: $0 [module-directory-relative-to-repo]" >&2
exit 2
fi
command -v go >/dev/null 2>&1 || {
printf '%s\n' "package-shape: go is required" >&2
exit 127
}
command -v awk >/dev/null 2>&1 || {
printf '%s\n' "package-shape: awk is required" >&2
exit 127
}
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
module_relative=${1:-.}
module_root="$repo_root/$module_relative"
edge_helper="$repo_root/.agents/skills/archie-codebase-discovery/scripts/package-edges.sh"
if [ ! -f "$module_root/go.mod" ]; then
printf 'package-shape: no go.mod at %s\n' "$module_root" >&2
exit 2
fi
if [ ! -x "$edge_helper" ]; then
printf 'package-shape: required sibling helper is missing or not executable: %s\n' "$edge_helper" >&2
exit 2
fi
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-package-shape.XXXXXX")
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
mkdir -p "$temporary/cache" "$temporary/build-tmp"
export GOCACHE="$temporary/cache"
export GOTMPDIR="$temporary/build-tmp"
export GOPROXY=off
export GOFLAGS="-mod=readonly -buildvcs=false"
export ARCHIE_DISCOVERY_CACHE="$temporary/discovery"
(
cd "$module_root"
go list ./... | LC_ALL=C sort
) >"$temporary/packages"
if (
cd "$module_root"
"$edge_helper" ./...
) >"$temporary/edges" 2>"$temporary/edge-stderr"; then
# The sibling helper sets its own GOFLAGS and can trigger a harmless,
# nondeterministic temporary filename when GOMODCACHE is read-only.
# Preserve the warning while normalizing only that filename suffix.
sed 's/\.info[0-9][0-9]*\.tmp/.info<TEMP>.tmp/' "$temporary/edge-stderr" >&2
else
status=$?
cat "$temporary/edge-stderr" >&2
exit "$status"
fi
(
cd "$module_root"
go list -m -f '{{.Path}}'
) >"$temporary/module"
module_path=$(sed -n '1p' "$temporary/module")
printf '%s\n' "META schema archie-package-shape/v1"
printf 'META\tmodule\t%s\n' "$module_path"
awk -F ' ' '
NR == FNR {
packages[$0] = 1
next
}
{
split($0, edge, " -> ")
outbound[edge[1]]++
inbound[edge[2]]++
}
END {
for (packageName in packages) {
printf "PACKAGE\t%s\t%d\t%d\n", packageName, inbound[packageName] + 0, outbound[packageName] + 0
}
}
' "$temporary/packages" "$temporary/edges" | LC_ALL=C sort
awk '{printf "EDGE\t%s\n", $0}' "$temporary/edges"
@@ -1,357 +0,0 @@
// Command source-metrics emits deterministic, syntax-derived Go source metrics.
// It never writes to the inspected tree and uses only the Go standard library.
package main
import (
"bytes"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
type counts struct {
productionFiles int
testFiles int
generatedFiles int
productionLines int
testLines int
generatedLines int
functions int
methods int
}
type packageCounts struct {
module string
path string
productionFiles int
testFiles int
generatedFiles int
productionLines int
testLines int
generatedLines int
}
type hotspot struct {
module string
path string
line int
symbol string
spanLines int
statements int
complexity int
}
func main() {
root := flag.String("root", ".", "repository root to inspect")
top := flag.Int("top", 30, "maximum hotspot rows; zero means all")
largeLines := flag.Int("large-lines", 80, "minimum body span for a hotspot")
complexity := flag.Int("complexity", 15, "minimum approximate syntactic complexity for a hotspot")
includeTests := flag.Bool("include-test-hotspots", false, "include test functions in hotspot rows")
flag.Parse()
if *top < 0 || *largeLines < 1 || *complexity < 1 {
fail(2, "top must be non-negative; thresholds must be positive")
}
absoluteRoot, err := filepath.Abs(*root)
if err != nil {
fail(2, "resolve root: %v", err)
}
info, err := os.Stat(absoluteRoot)
if err != nil {
fail(2, "inspect root: %v", err)
}
if !info.IsDir() {
fail(2, "root is not a directory: %s", absoluteRoot)
}
modules := map[string]*counts{}
packages := map[string]*packageCounts{}
var hotspots []hotspot
fset := token.NewFileSet()
err = filepath.WalkDir(absoluteRoot, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
relative, err := filepath.Rel(absoluteRoot, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
if entry.IsDir() {
if relative != "." && excludedDirectory(relative, entry.Name()) {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(entry.Name()) != ".go" {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relative, err)
}
module := moduleFor(relative)
moduleCounts := modules[module]
if moduleCounts == nil {
moduleCounts = &counts{}
modules[module] = moduleCounts
}
dir := filepath.ToSlash(filepath.Dir(relative))
packageKey := module + "\x00" + dir
pkg := packages[packageKey]
if pkg == nil {
pkg = &packageCounts{module: module, path: dir}
packages[packageKey] = pkg
}
lines := physicalLines(body)
generated := ast.IsGenerated(file)
isTest := strings.HasSuffix(entry.Name(), "_test.go")
switch {
case generated:
moduleCounts.generatedFiles++
moduleCounts.generatedLines += lines
pkg.generatedFiles++
pkg.generatedLines += lines
case isTest:
moduleCounts.testFiles++
moduleCounts.testLines += lines
pkg.testFiles++
pkg.testLines += lines
default:
moduleCounts.productionFiles++
moduleCounts.productionLines += lines
pkg.productionFiles++
pkg.productionLines += lines
}
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if !ok || function.Body == nil {
continue
}
if function.Recv == nil {
moduleCounts.functions++
} else {
moduleCounts.methods++
}
if generated || (isTest && !*includeTests) {
continue
}
start := fset.Position(function.Body.Lbrace).Line
end := fset.Position(function.Body.Rbrace).Line
row := hotspot{
module: module,
path: relative,
line: fset.Position(function.Pos()).Line,
symbol: symbolName(function),
spanLines: end - start + 1,
statements: statementNodes(function.Body),
complexity: syntacticComplexity(function.Body),
}
if row.spanLines >= *largeLines || row.complexity >= *complexity {
hotspots = append(hotspots, row)
}
}
return nil
})
if err != nil {
fail(1, "%v", err)
}
fmt.Println("META\tschema\tarchie-source-metrics/v1")
fmt.Printf("META\tthresholds\tlarge_lines=%d;syntactic_complexity=%d;top=%d\n", *largeLines, *complexity, *top)
moduleNames := sortedKeys(modules)
for _, module := range moduleNames {
value := modules[module]
emitMetric(module, "production_go_files", value.productionFiles)
emitMetric(module, "test_go_files", value.testFiles)
emitMetric(module, "generated_go_files", value.generatedFiles)
emitMetric(module, "production_physical_lines", value.productionLines)
emitMetric(module, "test_physical_lines", value.testLines)
emitMetric(module, "generated_physical_lines", value.generatedLines)
emitMetric(module, "functions", value.functions)
emitMetric(module, "methods", value.methods)
}
packageRows := make([]*packageCounts, 0, len(packages))
for _, row := range packages {
packageRows = append(packageRows, row)
}
sort.Slice(packageRows, func(i, j int) bool {
if packageRows[i].module != packageRows[j].module {
return packageRows[i].module < packageRows[j].module
}
return packageRows[i].path < packageRows[j].path
})
for _, row := range packageRows {
fmt.Printf(
"PACKAGE\t%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\n",
row.module,
row.path,
row.productionFiles,
row.testFiles,
row.generatedFiles,
row.productionLines,
row.testLines,
row.generatedLines,
)
}
sort.Slice(hotspots, func(i, j int) bool {
if hotspots[i].spanLines != hotspots[j].spanLines {
return hotspots[i].spanLines > hotspots[j].spanLines
}
if hotspots[i].complexity != hotspots[j].complexity {
return hotspots[i].complexity > hotspots[j].complexity
}
if hotspots[i].path != hotspots[j].path {
return hotspots[i].path < hotspots[j].path
}
if hotspots[i].line != hotspots[j].line {
return hotspots[i].line < hotspots[j].line
}
return hotspots[i].symbol < hotspots[j].symbol
})
if *top > 0 && len(hotspots) > *top {
hotspots = hotspots[:*top]
}
for _, row := range hotspots {
fmt.Printf(
"HOTSPOT\t%s\t%s\t%d\t%s\t%d\t%d\t%d\n",
row.module,
row.path,
row.line,
row.symbol,
row.spanLines,
row.statements,
row.complexity,
)
}
}
// excludedDirectory reports whether a walked directory is outside the module.
//
// ".worktrees" holds live git worktrees of this same repository, nested inside
// the root. Each is a near-complete copy of the module, so walking them
// multiplies every count by the number of checkout worktrees and floods the
// HOTSPOT and PACKAGE rows with duplicates of the same declarations.
func excludedDirectory(_, name string) bool {
switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp", ".worktrees":
return true
}
return false
}
func moduleFor(relative string) string {
if relative == "tools" || strings.HasPrefix(relative, "tools/") {
return "tools"
}
return "root"
}
func physicalLines(body []byte) int {
if len(body) == 0 {
return 0
}
lines := bytes.Count(body, []byte{'\n'})
if body[len(body)-1] != '\n' {
lines++
}
return lines
}
func symbolName(function *ast.FuncDecl) string {
if function.Recv == nil || len(function.Recv.List) == 0 {
return function.Name.Name
}
return receiverName(function.Recv.List[0].Type) + "." + function.Name.Name
}
func receiverName(expression ast.Expr) string {
switch value := expression.(type) {
case *ast.Ident:
return value.Name
case *ast.StarExpr:
return "*" + receiverName(value.X)
case *ast.IndexExpr:
return receiverName(value.X)
case *ast.IndexListExpr:
return receiverName(value.X)
default:
return "receiver"
}
}
func statementNodes(node ast.Node) int {
count := 0
ast.Inspect(node, func(candidate ast.Node) bool {
statement, ok := candidate.(ast.Stmt)
if !ok {
return true
}
switch statement.(type) {
case *ast.BlockStmt, *ast.EmptyStmt:
default:
count++
}
return true
})
return count
}
func syntacticComplexity(node ast.Node) int {
value := 1
ast.Inspect(node, func(candidate ast.Node) bool {
switch item := candidate.(type) {
case *ast.IfStmt, *ast.ForStmt, *ast.RangeStmt, *ast.CommClause:
value++
case *ast.CaseClause:
if len(item.List) > 0 {
value++
}
case *ast.BinaryExpr:
if item.Op == token.LAND || item.Op == token.LOR {
value++
}
}
return true
})
return value
}
func sortedKeys(values map[string]*counts) []string {
keys := make([]string, 0, len(values))
for key := range values {
keys = append(keys, key)
}
sort.Strings(keys)
return keys
}
func emitMetric(module, name string, value int) {
fmt.Printf("METRIC\t%s\t%s\t%d\n", module, name, value)
}
func fail(code int, format string, arguments ...any) {
fmt.Fprintf(os.Stderr, "source-metrics: "+format+"\n", arguments...)
os.Exit(code)
}
@@ -1,204 +0,0 @@
---
name: archie-docs-and-writing
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with `CLAUDE.md`, `docs/architecture`, `docs/prds`, `docs/archive`, or generated contracts; changing `tools/docsgen`; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
---
# Maintain Archie documentation
Write one durable record for each decision or behavior. Separate what runs now
from what Archie has approved as its destination.
Route to `archie-architecture-planning-campaign` for ownership/boundary
decisions (parked outside this checkout, under
`/work/apps/archie-skills-parked/`),
`archie-architecture-contract` for invariants,
`archie-codebase-discovery` for live entry points,
`archie-failure-archaeology` for incidents,
`archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate`
for runtime/operations facts.
## Use the authority vocabulary
Define a **record of authority** as the one canonical location whose owner may
change a claim.
| State | Meaning | Permitted wording |
|---|---|---|
| `CURRENT` | Verified behavior in checked-out code, tests, composition, or executable config | "Currently does" |
| `APPROVED TARGET` | Normative destination approved in architecture index | "Must become"; never "currently does" |
| `OPEN` | Investigation, candidate, or unresolved decision | "Candidate", "unknown", or "requires decision" |
| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | "Previously did" |
| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit |
| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give re-check command |
When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the
migration delta.
## Use the repository authority map
Verified on 2026-09-18:
| Location | Role | Discipline |
|---|---|---|
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior |
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it |
| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names |
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review |
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence |
| `CHANGELOG.md` | Release stream and packaged runtime input | One file holds every release; `internal/releaseannounce` parses version headings |
| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
| `docs/` | Repository documentation only | Nothing builds, renders, or publishes it; Markdown is the artifact |
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18.
## Choose one destination
1. State the reader's question.
2. Identify the owner of the behavior or decision.
3. Find the existing record of authority.
4. Extend that record or link to it. Do not make a second canonical table.
5. If no owner exists, route the ownership decision through the architecture campaign.
6. If the fact is generated, change the owned source definition and generator.
7. If the fact is external, date it and name the exact observation command.
| Content | Destination |
|---|---|
| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` |
| New capability with no settled design yet (CLAUDE.md's "write a decisive doc before coding") | New `docs/prds/<capability>.md` — use the PRD template in `references/templates.md`, which folds in a multi-agent execution breakdown so the sub-issues can be picked up without re-deriving the design |
| Focused domain or requirement decision | Matching `docs/architecture/*.md` file |
| Unresolved migration question | `docs/architecture/migration-decisions.md` |
| Contributor protocol that must load before work | `CLAUDE.md` |
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
| Repository documentation prose | `docs/`, linking back to authority with repository-relative paths |
| Shipped release behavior | Matching component changelog; keep `CHANGELOG.md` as two-component index |
| Superseded design retained for context | `docs/archive/`, with historical status |
| Incident or rejected approach | `archie-failure-archaeology`'s chronology |
Do not duplicate a package map across `CLAUDE.md`, a PRD, and
the site. Name the authoritative map and link to it.
## Write for future change
Every architecture, feature, or migration record must answer:
- **Responsibility:** What cohesive job exists?
- **Owner:** Which domain, application boundary, or infrastructure adapter owns
its meaning and mutable state?
- **Boundaries:** What is explicitly inside and outside?
- **Consumers:** Which entry points, interfaces, commands, events, config, and
processes depend on it?
- **Invariants:** What must remain true, and where is each enforced?
- **Superseded path:** Which older mechanism becomes redundant?
- **Deletion gate:** What observable proof permits removal?
- **Evidence:** Which symbols, tests, commands, and runtime observations support
the record?
- **Rollback:** How can behavior and data return safely?
- **Unresolved questions:** What remains `OPEN`?
Name one owner for every mutable record. A new path is incomplete until the
document says whether each older path remains, delegates, migrates, or is
deleted.
## Cite evidence without freezing line numbers
Prefer: repository-relative path plus exact Go symbol, test name, config key,
workflow job/step, or Markdown heading; a relative Markdown link to the record
of authority; the command that re-discovers the evidence.
Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`.
Distinguish evidence strength:
1. Runtime composition and executable behavior.
2. Tests that exercise the relevant production seam.
3. Approved target decision.
4. Comments and summaries corroborated by the first three.
5. Historical or external notes, explicitly dated.
## Maintain component changelogs
Keep every release's notes in `CHANGELOG.md`; a release is one version, and
the components' entries are labelled sections inside it.
`Dockerfile.archied` copies it to `/usr/share/archie/`, and
`internal/releaseannounce.changelogSection` parses a version heading.
Version-heading format is settled as of 2026-09-18: the changelog uses
`## [1.27.0]` with no `v` prefix, `changelogSection` searches for
`## [<version>]`, and `.github/workflows/deploy.yml` gates each release tag with
`grep -q "^## \[$ver\]" CHANGELOG.md`. The earlier
`vX.Y.Z`-vs-`X.Y.Z` contradiction involved `.gitea/workflows/deploy.yml`, which
was dropped (`dd9bddc2 ci: build and push images to GHCR, drop the Gitea
workflow`), so that question is `HISTORICAL`, not `OPEN`. The remaining guard is
the CI shell gate plus `internal/releaseannounce`'s announcer tests
(`TestAnnouncerReportsMissingReleaseSectionWithoutAdvancingState`); the old
`cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` no longer exists.
## Maintain generated contracts
Current behavior, verified 2026-09-18:
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
- Separate Go module replacing root module with `../`.
- Accepts `--repo-root` and `--out`, plus a `check` subcommand that compares
against the committed artifact without writing. No implemented `data`,
`asyncapi`, or `all` subcommands.
- `currentContractTypes` publishes three top-level contracts and collects
referenced schemas into one JSON object.
- Default output is `docs/data/generated/contracts.json`.
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test -mod=readonly ./docsgen -count=1
task docs:check # fails loudly, and names the Go type behind each mismatch
```
`docsgen check` and the `docs:generate`/`docs:check` tasks are implemented, and
`task check` runs `docs:check` — generated drift is gated. `docsgen data`,
`docsgen asyncapi`, and `docsgen all` remain `APPROVED TARGET`.
The check is deliberately non-destructive: it generates into a temporary
directory, so a failing gate never rewrites the artifact it judges. Fix a
failure with `task docs:generate` and commit the result with the code change
that shifted the contract surface.
## Store documentation as repository Markdown
`docs/` is Markdown read directly in the repository, an editor, or the forge's
file view. Nothing builds, renders, or publishes it. The VitePress site, its
package manifest and lockfile, its landing page, and
`.github/workflows/docs.yml` were removed on 2026-09-12 as an unnecessary build
step; the publishing surface is an open decision
(`docs/architecture/generated-documentation.md`, "Rendering and publishing").
| Surface | Current state |
|---|---|
| Content | Markdown under `docs/`, including `docs/data/generated/contracts.json` |
| Links | Repository-relative (`../architecture/organisation.md`); no root-absolute links |
| Build | None. There is no site, no dev server, no link checker, no Pages deploy |
| Nav | `docs/prds/01-project-management.md` is the index; there is no site nav |
Because no build validates links, check them yourself or with a one-off script —
nothing catches a dead link for you:
```bash
# every relative markdown link target that does not resolve
grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u
```
### Enforce source-artifact hygiene
Git tracks no `node_modules` entries (verified 2026-09-12; the 237 `docs/`
symlinks recorded on 2026-07-28 are gone) and no VitePress output. A future
renderer must not reintroduce committed installs or build output.
```bash
git ls-files | grep -c node_modules # expect 0
ls docs/package.json docs/pnpm-lock.yaml 2>&1 # expect: No such file
ls .github/workflows/ # expect deploy.yml only
```
Historical mentions of VitePress in `docs/architecture/` are deliberate — they
record what was removed. A grep for the word alone is not a failure signal.
Never stage dependency installs, renderer output, generator scratch files,
credentials, absolute paths, wall-clock data, or machine-specific values.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Docs and Writing"
short_description: "Maintain authoritative Archie documentation"
default_prompt: "Use $archie-docs-and-writing to write or update an authoritative Archie design, migration, incident, ownership, or operations document."
@@ -1,485 +0,0 @@
# Archie durable-writing templates
Use one template at a time. Replace every angle-bracket prompt. Remove unused
sections. Keep facts, decisions, and open questions visibly separate.
## Contents
- [Architecture decision record](#architecture-decision-record)
- [Migration plan and parity matrix](#migration-plan-and-parity-matrix)
- [Incident or dead-end record](#incident-or-dead-end-record)
- [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record)
- [Operational runbook](#operational-runbook)
- [Documentation change review](#documentation-change-review)
- [PRD: open capability design with multi-agent execution](#prd-open-capability-design-with-multi-agent-execution)
## Architecture decision record
````markdown
# <Decision title>
**Status:** Proposed | Approved | Superseded by <link>
**Date:** YYYY-MM-DD
**Owner:** <domain or application boundary>
**Record of authority:** <this document or existing focused document>
**Change-control reference:** <issue/review identifier>
## Decision
<One unambiguous normative statement.>
## Problem and scope
<Describe the problem, the included behavior, and explicit non-goals.>
## Current evidence
| Claim | Evidence |
|---|---|
| <CURRENT behavior> | `<path>` — `<symbol/test/config key>` |
## Constraints and invariants
- <Invariant and where it is enforced>
## Consumers and boundaries
| Consumer | Contract used | Failure effect |
|---|---|---|
| <entry point/package/process> | <interface/command/event/data> | <effect> |
## Options considered
| Option | Benefits | Costs and risks | Evidence | Result |
|---|---|---|---|---|
| <option> | <benefit> | <cost> | <measurement/source> | Accepted / Rejected |
## Consequences
<State new responsibilities, dependency direction, state ownership, and
operational effects.>
## Supersession and deletion
- Superseded path: `<path/symbol>` or none
- Compatibility owner: <owner or none>
- Deletion gate: <observable proof>
- Architecture test: <test or OPEN>
## Rollback
<State how code, behavior, and data return safely.>
## Open questions
| Question | Owner | Evidence required | Decision deadline/gate |
|---|---|---|---|
| <OPEN question> | <owner> | <measurement> | <gate> |
## Validation
- `<exact command>` — expected <observable result>
````
## Migration plan and parity matrix
````markdown
# <Capability> migration plan
**Status:** Proposed | Approved | In progress | Complete
**Date:** YYYY-MM-DD
**Owner:** <domain>
**Source authority:** <approved target decision>
**Current baseline:** <code paths and runtime composition>
## Outcome
<Describe the final single authoritative path and what becomes easier to
change.>
## Current-path inventory
| Operation | Entry point | Owner today | State/data touched | Consumers | Disposition |
|---|---|---|---|---|---|
| <operation> | `<path.Symbol>` | <owner/none> | <state> | <consumers> | Keep / Adapt / Merge / Delete |
## Parity matrix
| Behavior | Current evidence | Target owner/path | Required parity | Test or observation | Status |
|---|---|---|---|---|---|
| <behavior> | `<test/symbol/log>` | <target> | <exact result> | `<command>` | OPEN |
Include success, validation failure, retry, cancellation, crash recovery,
authorization, persistence, event emission, and shutdown where applicable.
## Dependency and data movement
| From | To | Adapter/backfill | Consistency rule | Rollback |
|---|---|---|---|---|
| <source> | <target> | <mechanism> | <invariant> | <method> |
## Slices and gates
### Slice 1 — <small vertical outcome>
- Change: <bounded change>
- Expected evidence: <number/result predicted before implementation>
- Command: `<exact command>`
- Pass: <observable result>
- Branch if not: <diagnostic route>
- Legacy path after slice: Active / Delegating / Read-only / Removable
<Repeat for each independently reviewable slice.>
## Cutover
1. <Prepare compatibility/data>
2. <Change production composition>
3. <Observe explicit health/parity signals>
4. <Disable legacy entry>
5. <Delete only after the deletion gate>
## Deletion gates
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
|---|---|---|---|---|
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
## Rollback and stop conditions
- Roll back when: <condition>
- Restore: <code/config/data sequence>
- Preserve for diagnosis: <artifacts>
## Remaining open decisions
| Decision | Owner | Evidence needed | Blocks |
|---|---|---|---|
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
````
## Incident or dead-end record
````markdown
# <Symptom or rejected approach>
**Status:** Resolved | Mitigated | Rejected | Reopened
**Observed:** YYYY-MM-DD
**Last verified:** YYYY-MM-DD
**Owner:** <capability>
**Related changes:** <commit/issue/PR identifiers>
## Symptom and impact
<State the observable failure, affected path, and cost. Do not begin with the
proposed fix.>
## Reproduction
```text
<exact non-secret command or event sequence>
```
Expected: <result>
Observed: <result>
## Investigation chronology
| Time/order | Hypothesis | Prediction | Evidence | Result |
|---|---|---|---|---|
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
## Root cause
<Name the owning code path and causal mechanism. Separate cause from trigger.>
## Attempted or rejected fixes
| Fix | Why plausible | Evidence against it | Status |
|---|---|---|---|
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
## Resolution and invariant
- Resolution: <what changed>
- Preserved invariant: <what must not regress>
- Regression test: `<test name/path>`
- Operational signal: <log/metric/state>
## Reopen condition
<State the evidence that would justify revisiting the settled result.>
````
## Feature ownership and deprecation record
````markdown
# <Feature/capability> ownership
**Status:** Current | Migrating | Deprecated | Removed
**Date:** YYYY-MM-DD
**Behavior owner:** <domain>
**State owner:** <domain/repository>
**Composition owner:** <application boundary>
## Responsibility and non-responsibilities
- Owns: <cohesive behavior>
- Does not own: <adjacent concerns>
## Complete path
| Layer | Path/symbol | Responsibility |
|---|---|---|
| Entry | `<path.Symbol>` | <role> |
| Domain | `<path.Symbol>` | <role> |
| State | `<path.Symbol>` | <role> |
| Adapter | `<path.Symbol>` | <role> |
| Composition | `<path.Symbol>` | <role> |
## Consumers
| Consumer | Contract | Configuration | Test evidence |
|---|---|---|---|
| <consumer> | <interface/event/data> | <key or none> | `<test>` |
## Invariants and failures
| Invariant | Enforcement | Failure behavior | Test |
|---|---|---|---|
| <invariant> | `<path.Symbol>` | <result> | `<test>` |
## Duplicate and superseded paths
| Path | Same operation? | Disposition | Deletion gate |
|---|---|---|---|
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
## Change checklist
- [ ] Trace every entry point and consumer.
- [ ] Decide whether the feature deprecates earlier work.
- [ ] Keep one owner for mutable state.
- [ ] Add failure-path and architecture tests.
- [ ] Prove the replacement before deleting the old path.
- [ ] Update generated reference from owned definitions.
````
## Operational runbook
````markdown
# Operate <service/capability>
**Status:** Current
**Last verified:** YYYY-MM-DD
**Environment:** <local/staging/production>
**Owner:** <operator/capability>
**External sources:** <host/config/dashboard; no secrets>
## Purpose and safety boundary
<State what this runbook operates and what requires separate authorization.>
## Preconditions
- <access/tool/config precondition>
- Secret names only; never secret values
## Start or change
1. Run `<exact command>`.
2. Expect `<observable output/state>` within `<bounded interval>`.
3. If `<alternate result>`, stop and route to `<diagnostic branch>`.
## Health and outputs
| Signal | Location/command | Healthy result | Unhealthy branch |
|---|---|---|---|
| <signal> | `<command/path>` | <result> | <action> |
## Rollback
1. <Restore previous code/config/data>
2. Run `<health command>`.
3. Preserve <logs/artifacts> for incident review.
## Known failure modes
| Symptom | First measurement | Likely seam | Next runbook |
|---|---|---|---|
| <symptom> | `<command>` | <boundary> | <sibling skill/doc> |
## Provenance
- External fact observed by <who/how> on YYYY-MM-DD.
- Re-check: `<one-line command>`
````
## Documentation change review
````markdown
# Documentation review: <scope>
**Date:** YYYY-MM-DD
**Reviewer:** <name/session>
**Changed authority:** <path or none>
## Classification
| Claim/change | State | Owner | Evidence |
|---|---|---|---|
| <claim> | CURRENT / APPROVED TARGET / OPEN / HISTORICAL / GENERATED / EXTERNAL | <owner> | `<path.Symbol/test/command>` |
## Findings
| Severity | Location | Problem | Evidence | Required correction |
|---|---|---|---|---|
| Blocking / Important / Minor | <heading/path> | <problem> | <evidence> | <fix> |
## Authority and duplication checks
- [ ] One record of authority owns each claim.
- [ ] Current and target behavior are separated.
- [ ] Open questions remain visibly open.
- [ ] Historical material is not used normatively.
- [ ] Generated output was not hand-edited.
- [ ] Symbols and headings replace durable line-number citations.
## Maintainability checks
- [ ] Responsibility, owner, boundaries, consumers, and invariants are explicit.
- [ ] Superseded paths and deletion gates are named.
- [ ] Evidence, rollback, and unresolved questions are actionable.
- [ ] A zero-context engineer can locate the complete feature path.
## Validation evidence
| Command | Expected | Observed |
|---|---|---|
| `<exact command>` | <result> | <result> |
## Residual uncertainty
<List unverified external facts, unavailable environments, or still-open
decisions. Never convert them into implied acceptance.>
````
## PRD: open capability design with multi-agent execution
For `docs/prds/*.md` — CLAUDE.md's "no settled design exists" doc. The point
of this template is that a cheaper/faster model can implement straight from
it without re-deriving architecture: every decision the epic left open gets
made here, not deferred again, and every file an implementer touches is
named before any bead is picked up. `docs/prds/image-capability-contract.md`
is the worked example this template was extracted from — read it once for
the shape before writing a new PRD from a blank page.
The three failure modes this template exists to prevent:
- **Deferred decisions posing as scope.** "Hosted provider implementation is
a separate bead" is not a design decision, it's a missing one. If an open
question blocks an implementer, decide it here, in the PRD — not "this bead
will decide it later," which is how the same question gets re-opened by
every bead that touches it.
- **Assumed gaps.** Before writing a section for "what's missing," grep for
it. `image-capability-contract.md`'s delivery section exists mostly because
the pipeline it needed already shipped for video — the section reports
that, instead of specifying new plumbing nothing required.
- **Task lists a model can't execute standalone.** A subtask is not "wire the
delivery path"; it's the file, the interface it must satisfy, and the
existing call site that already proves the pattern (`internal/tools/minimax/tool.go`,
not "a tool like the video one").
````markdown
# <Capability> capability design
Epic: `<bd id>` / GitHub `#<epic number>` ("<epic title>").
<One paragraph: what shipped already and is settled (link its section
below), what this document newly decides, and what stays explicitly
out of scope. If a prior narrower doc already covers part of this
capability, say so and extend it — do not start a second document for
the same epic.>
## Problem
<What's missing today, with the exact "grep and found nothing" evidence,
not an assertion.>
## Design
<The settled contract/type shape. Code blocks over prose where a type
signature says more than describing it would.>
## <Sub-feature N> (`#<issue>`)
One section per sibling bead the epic lists as separate scope. Each one:
- **Decision, not a deferral.** If the epic or a prior doc left this open,
decide it here and say why in one paragraph, citing what's actually in
the tree (a similar client already in the codebase, an existing config
convention, an interface already proven by another feature). "Decide and
record which at that bead's own design-doc step" is the sentence this
template exists to stop someone from writing twice.
- **Call site**, named exactly: `<package/file>`, the function/type it adds
or extends, and the existing analogous call site it follows (never "a
handler like the others" — name the actual one).
- **Reuse check.** Grep before specifying new plumbing. State what already
exists and what's actually new, the way a delivery pipeline already
proven by one media type doesn't need re-inventing for a second.
- **Error/failure mapping**, as a table, when the sub-feature crosses a
provider/backend boundary: condition → contract error, so an implementer
never invents a new sentinel mid-way through.
- **Testing.** What's fakeable vs. what needs a real backend, and which
gate (`task check` vs. a documented manual smoke command) each belongs to.
## Call site inventory
| concern | file | change |
|---|---|---|
| <concern> | `<path>` | done (`#<issue>`) / new (`#<issue>`) / none — already handles this |
Every file any sub-feature touches, old or new, in one table — so an
implementer greps this instead of re-deriving it, and a reviewer can tell
at a glance whether a PR touched something the design didn't name.
## Execution: multi-agent team breakdown
One row per sub-feature section above. This is what turns the design into
something a `/council`-style review or a cheaper/faster implementer model
can run against directly instead of needing the full design re-explained.
| sub-feature | issue | implementer scope | suggested council lenses | why |
|---|---|---|---|---|
| <name> | `#<issue>` | <the call-site inventory rows this bead owns> | `lens-<key>`, `lens-<key>` | <one clause: what that lens actually catches for this slice — e.g. lens-contract for a new provider error-mapping table, lens-operator for a backend-down failure path, lens-deletionist when the section's whole point is "don't rebuild what exists", lens-boundary for a new domain/infra split, lens-maintainer for a new user-facing state machine> |
Pick lenses from the five in `.claude/workflows/council.js`
(`boundary`, `contract`, `deletionist`, `operator`, `maintainer`) by what the
slice actually risks getting wrong, not all five by default — a
generate-and-poll HTTP client mostly risks failure-mode gaps
(`lens-operator`), not domain-boundary violations. Run `/council` with
`--lenses <picked>` once the implementation is gate-clean, before opening
the PR for human review, same as any other open-decision residue at the
end of a session.
An implementer working one row needs only: this doc's matching sub-feature
section, the call-site inventory, and the linked issue's acceptance
criteria. It should not need the rest of the epic's history — that's the
signal the PRD is thorough enough to hand to a faster/cheaper model.
## File and link the beads
For each sub-feature issue already filed against the epic (or newly filed
if the epic didn't pre-file its sub-issues):
- Issue body links back to this doc's matching section by heading, not by
restating the design — `bd update <id> --description` and, if the issue
also lives on the forge, keep both current (check whether this repo's
sync command actually propagates a description edit before trusting it
updated both; direct edit on both sides is the fallback).
- Issue keeps its own acceptance criteria as the authoritative "done"
check — the PRD section is how, the issue's criteria are whether.
- Add the suggested lenses from the Execution table as a line on the issue
itself, so picking it up needs no round-trip back to this doc to know
which `/council` lenses to run before it's done.
````
@@ -1,242 +0,0 @@
---
name: archie-domain-reference
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for database API mechanics, general code tracing, config enumeration, debugging, or operations."
---
# Archie Domain Reference
Use one meaning for each noun. Keep external-system words at adapters, keep
domain meaning with its owner, and mark migration state explicitly.
## Classify every statement
As of 2026-09-18, Archie is partway through the domain migration: some approved
target packages now exist and are production-wired (`internal/domain/messaging`,
`internal/domain/workflow`, `internal/domain/workintake`, `internal/app`,
`internal/eventbus`, `internal/infrastructure`), while others remain target-only
(`internal/domain/agent`, `internal/domain/identity`, `internal/policy`). Never
blend the two.
| Label | Meaning | Evidence rule |
| --- | --- | --- |
| **CURRENT** | Behavior present in live code and tests | Cite defining type/function and production caller or test. |
| **APPROVED TARGET** | Normative rule in approved foundation document | Cite exact PRD. Do not claim implemented. |
| **OPEN/CANDIDATE** | Deferred API, owner, package, migration, or behavior | Preserve open question. |
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology. |
Start design notes with status sentences:
```text
CURRENT: task.Task persists one mutable Stage string.
APPROVED TARGET: WorkflowExecution records StepExecution history.
OPEN: the exact schema and Go API for that history.
```
Read status markers:
```bash
sed -n '1,180p' docs/prds/01-project-management.md
rg -n '^\*\*Status:\*\*|^## Decisions still required' docs/architecture
```
## Use the canonical actor vocabulary
| Term | Archie meaning | State and owner |
| --- | --- | --- |
| **Identity** | Durable actor reference for ownership, attribution, routing, commands, events, audit. | **APPROVED TARGET:** `internal/domain/identity`. **CURRENT:** configured names and empty strings act as identifiers. |
| **User** | Person represented as `user` kind of Identity. | **APPROVED TARGET:** Identity domain. |
| **Agent** | Persistent assistant with acting IdentityID, specialization, instructions, capability context, memory. | **CONFIRMED TARGET:** Agent and Identity separate aggregates; `internal/domain/agent` confirmed in `migration-decisions.md`. |
| **Model invocation** | One call through LLM provider/runtime. Replaceable execution machinery. | **CURRENT:** runtime packages. **TARGET:** infrastructure behind Agent-owned behavior. |
| **System identity** | One permanent actor for startup, migration, supervision, rollback. | **APPROVED TARGET:** a real IdentityID. |
Apply: record acting Agent identity and initiating user identity separately;
never authorize because two mutable strings match; never rename Agent when only
model/provider/display name changes; never pool two Agents' memory.
```bash
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' internal/config internal/daemon internal/store internal/gateway
```
## Use the canonical interaction vocabulary
| Term | Archie meaning | State and owner |
| --- | --- | --- |
| **Channel** | External interaction source (Telegram, email, webhook, forge). | **CURRENT:** `internal/channels` extends `gateway.Gateway`. **TARGET:** infrastructure adapter for Messaging. |
| **Adapter** | Boundary code translating external payloads into owned contracts. | **TARGET RULE:** infrastructure implements domain-owned interfaces. |
| **Gateway** | Current technical interface/router and package — not approved domain vocabulary. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`. |
| **ChannelBindingID** | Stable reference connecting Agent to channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. |
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **CURRENT:** `internal/domain/messaging.Message`/`MessageID`; `gateway.MessageEvent` is a richer event type beside it. |
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET, partly current:** `internal/domain/messaging.Conversation`/`ConversationID` exist; the gateway session store still lacks canonical Agent/user IDs. |
| **Conversation branch** | Child conversation from one immutable parent message. | **CONFIRMED TARGET.** No current implementation. |
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET, current package:** `internal/domain/workintake` exists. |
| **Accepted work request** | Channel-neutral handoff after Work Intake accepts proposed outcome. | **TARGET HANDOFF:** Agent System consumes it, selects Workflow version, creates WorkflowExecution. |
Do not equate an inbound Message with work. An Agent may answer, use
capabilities, retain information, or propose work without creating a
WorkflowExecution.
Target flow:
```text
external payload -> channel adapter -> canonical Message and Conversation
-> selected Agent turn -> optional proposed work -> Work Intake admission
-> accepted work request -> Agent System selects Workflow version -> WorkflowExecution
```
Do not describe current `/spawn` as this target. It directly creates a
`task.Task` with synthetic forge issue number.
```bash
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/store internal/app/archied
```
## Use the canonical execution vocabulary
| Term | Archie meaning | Current representation |
| --- | --- | --- |
| **Workflow** | Reusable, versioned definition. | `workflow.Workflow` is named `[]Stage` without durable version model. |
| **WorkflowExecution** | One durable execution of one Workflow version. | `task.Task` is migration baseline. |
| **WorkflowStep** | One defined operation. | `workflow.Stage` is closest definition. |
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `task.Task.Stage` is one mutable string. |
| **Attempt** | Retry within same WorkflowExecution. | `task.Task.Attempt`/`RetryCount` must become explicit attempt history. |
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate TaskID, Attempt, Stage, protocol version. |
Use `WorkflowExecution` in domain contracts, architecture, generated reference.
Retain `task` only for Task build tool, forge product nouns in adapters,
informal prose.
### Interpret the current lifecycle exactly
**CURRENT** `task.Task` states:
```text
queued -> running
running -> waiting_human | pr_open | merged | parked | closed_wont_do
waiting_human -> queued | closed_wont_do
parked -> queued | dead
pr_open -> merged | rejected
running after crash -> queued
```
Do not claim enforced. `Store.Transition` now guards on `from`
(`WHERE id=? AND status=?` → `store.ErrStaleTransition`) and writes status plus
history in one transaction; the sentinel crosses the State Store gRPC boundary.
See `internal/store/store.go`.
```bash
rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/domain/workflow internal/gateway
```
## Keep memory scope separate from conversation scope
| Scope | Address and visibility |
| --- | --- |
| **Global shared** | Intentionally visible across Archie. |
| **Agent-wide** | Owned by one Agent, private by default even across users. |
| **User-wide** | One user across authorized Agents. |
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID. |
Conversation branch is not a fifth memory scope. Scope mechanics **OPEN** beyond
these constraints.
Current `MemoryProvider` initializes with session ID, contains no explicit
AgentID, User IdentityID, or scope parameter. Built-in provider separates
`MEMORY.md` and `USER.md` under one directory — not the four-scope target model.
```bash
rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|AgentID|IdentityID|Scope' internal/memory
```
## Distinguish extension terms
| Term | Meaning |
| --- | --- |
| **Plugin** | Removable module with identity, metadata, compatibility, lifecycle. Generic `plugin.Plugin` must remain metadata-only. |
| **Capability family** | One cohesive typed behavior owned by its domain or approved manager/registry. |
| **Engine** | Typed, lifecycle-managed capability family with owning Registry or Manager. |
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. Must not become service locator. |
Give plugin only narrow typed registrars and explicitly supplied contracts.
```bash
go test ./internal/plugin -run 'Test(EngineFamilyInspectionRejectsInvalidShapes|PluginInterfaceExists)' -count=1
```
## Distinguish ownership and boundary terms
| Term | Archie-specific rule |
| --- | --- |
| **Domain** | Own one cohesive responsibility: vocabulary, state, rules, operations, commands, events, policies, runtime settings, required service contracts. |
| **Command** | Request an action. Receiving domain owns contract and decides result. |
| **Domain event** | Record something that happened. Publishing domain owns schema. |
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` exists and is production-wired. |
| **Observability event** | `internal/events.Event` projection input. Bounded in-process bus may drop. Not authoritative state. |
| **Policy** | Typed rule evaluated through shared mechanics. Consuming domain owns vocabulary. |
| **Infrastructure** | Implements domain-owned ports, translates DBs, brokers, SDKs, files, containers. |
| **Application composition** | Chooses implementations, translates config, connects contracts, orders startup/shutdown. Current and target: `internal/app`; `cmd/*` stays process-input-only. |
As of 2026-09-18, `internal/domain`, `internal/eventbus`,
`internal/infrastructure`, and `internal/app` exist; only `internal/policy`
does not. `internal/domain/agent` and `internal/domain/identity` are still
target-only.
```bash
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
```
## Distinguish forge, repository, workspace, gate, and agent boundaries
| Term | Owns | Must not own |
| --- | --- | --- |
| **Forge** | External code-host ops: issues, comments, labels, PRs, reactions. | Workflow lifecycle, canonical identity, work admission. |
| **Repository** | External source repo identity and repo-specific policy. | Mutable execution workspace or WorkflowExecution identity. |
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, cleanup for one execution. | Agent/domain identity or forge issue lifecycle. |
| **Gate** | Deterministic evidence and constraints over execution. | Prompt advice model may waive. |
| **Agent execution boundary** | Versioned, validated data entering/leaving one unprivileged stage. | Daemon internals, forge tokens, direct git, workflow orchestration. |
Model never runs git directly. Worktree operations are daemon-owned.
## Map current names before adding or migrating behavior
| Current name/path | Target meaning | Migration warning |
| --- | --- | --- |
| `config.IdentityConfig.Name` | Canonical IdentityID plus separate bindings | Do not preserve mutable display name as ID. |
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Not Conversation or Agent identity. |
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | Currently service bundle, not Identity aggregate. |
| `gateway.MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; `internal/domain/messaging.Message` is the target. |
| gateway session context | Conversation metadata | Add canonical Agent/user/binding ownership. |
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference in adapter. |
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System creates execution. |
| `store.Task` | WorkflowExecution | Preserve every field intentionally; the type now lives at `internal/domain/workflow/task.Task`. |
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before parity. |
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
| `task.Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove global config/service bag. |
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops acceptable for observability, not state. |
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only. |
| NATS/RPC/store/forge/worktree | Infrastructure adapters | Process boundaries don't decide domain ownership. |
`migration-decisions.md` leaves memory, tools, workspaces, gates, storage,
events, web UI, containers, RPC, release management, scheduling pending.
## Recognize terminology-driven bugs
| Incorrect shortcut | Resulting bug |
| --- | --- |
| "A forge issue is a Task" | Chat needs synthetic issues; uniqueness/dedup stay forge-shaped. |
| "Agent and Identity are same config object" | Model/persona changes alter attribution; mutable string equality becomes access control. |
| "Every Message is work" | Conversational turns forced through durable workflow lifecycle. |
| "Accepted request is already a WorkflowExecution" | Intake bypasses version selection and constructs invalid state. |
| "Stage is StepExecution" | Overwriting one string destroys step outcomes and audit history. |
| "NATS retry is another Attempt" | Transport availability changes domain retry counts. |
| "Event bus owns events" | Broker subjects become domain vocabulary; meaning drifts by consumer. |
| "Branch is a memory scope" | Returning to parent hides/duplicates durable learning. |
| "Engine means another generic plugin hook" | Capability ownership becomes untyped; plugins gain service-locator access. |
| "Configuration owns the feature" | Cross-concern config becomes de facto domain. |
Reject in review: a second parallel model without bounded cutover; status string
copied into consumer; mutable display name as durable ID; service bag passed
into domain/plugin/WorkflowStep; lifecycle state written by adapter/UI/transport;
domain importing concrete persistence/NATS/forge SDK/container/config DTO types;
test proving only new path while old production path remains active.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Domain Reference"
short_description: "Use Archie terminology without boundary mistakes"
default_prompt: "Use $archie-domain-reference to classify these Archie concepts and map current code terms to their approved target owners."
@@ -1,230 +0,0 @@
---
name: archie-failure-archaeology
description: "Reconstruct archie-core failures, dead ends, reversals, rejected fixes, and branch-only repairs from read-only git history and live call sites. Use when a symptom resembles a past production outage, deadlock, retry loop, protocol mismatch, configuration regression, worktree/cache fault, unsafe cleanup, linter semantic change, artifact leak, or recurring baseline repair; also use before reviving an old approach, declaring a fix reverted, or deciding whether a repair is current, settled, conditional, superseded, open, or merely a candidate."
---
# Archie failure archaeology
Stop the project from paying twice for the same lesson. Reconstruct what
happened from checked-out code, tests, configuration, and commit graph.
Treat commit prose as a lead, not proof. Preserve uncertainty.
All volatile observations are dated **2026-09-18** (HEAD `2e1e1549`); the merge-shape
section under Step 4 is dated **2026-09-20** (HEAD `1b0133d7`).
Route to `archie-debugging-playbook` for active symptoms,
`archie-codebase-discovery` for deep caller tracing.
## Use the status taxonomy exactly
| Status | Meaning |
|---|---|
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. |
| `current` | The checked-out authoritative path still contains the behavior or contradiction. |
| `open` | The defect is evidenced, but no accepted and integrated resolution. |
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or assembly. |
| `superseded` | A mechanism was intentionally replaced. |
| `candidate` | A branch, proposal, or partial implementation may help but is not accepted. |
Never use `settled` to mean "a fix commit exists."
## Run the archaeology workflow
### 1. Freeze the observation point
```sh
git rev-parse HEAD
git status --short
git log -1 --date=iso-strict --format='%H %ad %s'
git branch -a --no-color --no-merged HEAD
```
### 2. Name the exact symptom
Capture: first wrong observable result; last confirmed-good boundary; process
mode; active config and deployment assembly; whether deterministic,
load-dependent, or production-only.
### 3. Trace current behavior before history
```sh
rg -n '<symptom|symbol|setting|error>' cmd internal config*.toml docker-compose.yml docs
git log --all --date=iso-strict --format='%H %ad %s' -- <affected-paths>
git blame -L <start>,<end> -- <live-file>
```
### 4. Prove the historical transition
```sh
git show --no-ext-diff --format=fuller --stat <commit>
git show --no-ext-diff -U80 <commit> -- <affected-paths>
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <commit>
git branch -a --contains <commit>
```
#### `--is-ancestor` is blind to squash and rebase merges
`git merge-base --is-ancestor` answers a topology question: is this exact commit
object an ancestor. **Squash and merge** always mints a new commit, and **Rebase
and merge** mints new ones whenever the branch had to be replayed, so both
orphan the SHA a branch holds. `git branch -a --contains` and
`git branch -r --no-merged` are blind in the same way.
As of **2026-09-20** (`origin/main` `1b0133d7`) this repository squash-merges —
the last fifteen merged pull requests are all squashes, so the raw check is a
false negative for every one of them. It was sound for everything merged up to
**2026-09-18**, which used merge commits.
Use `scripts/on-main.sh`, which keeps `--is-ancestor` as the offline fast path
and otherwise asks the GitHub API, where merge state is recorded independently
of the commit graph:
```sh
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <ref> [base-ref]
```
`<base-ref>` defaults to `origin/main`; name `gitea/main` or `HEAD` when that is
the trunk you mean, and `git fetch` first so the fast path is not stale.
| Exit | Meaning |
|---|---|
| `0` | Ancestor of `<base-ref>`, or recorded in a merged pull request — landed |
| `1` | On GitHub, in no merged pull request — not landed |
| `2` | Bad ref, no `gh`, offline, never pushed — **undetermined, not a negative** |
Branch on the code explicitly; `if on-main.sh <ref>; then` folds `2` into "not
landed", which is the error this helper exists to prevent. It answers "did *this
ref* land", not "did this work land" — a change reimplemented on another branch
still reads `not-landed` for the original commit.
Read parent version when failure is semantic:
```sh
git show <commit>^:<path>
git show <commit>:<path>
```
Require all six fields in an incident packet:
| Field | Required content |
|---|---|
| Symptom | Operator, user, test, or protocol observation |
| Attempted solution | What was tried before or during the failure |
| Root cause | The violated contract or mistaken assumption |
| Evidence | Commit, live path, test, trace, or production observation |
| Current status | One taxonomy value, dated when volatile |
| Settled rule | A constraint future work must preserve |
### 5. Reproduce narrowly, then route
```sh
env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/<package> -run '^TestName$' -count=1 -v
```
If current behavior differs from chronicle, update the packet.
## Match symptoms to known incidents
| Symptom | Start with |
|---|---|
| `nats: no responders available for request` only from agent containers | Container network incident |
| Daemon crash-loops after config/schema work | SecretRef compatibility and Compose passthrough incidents |
| Stream shows empty cursor or first token, then hangs | FullStream/TextStream incident |
| MCP unit tests pass but real SDK server hangs | MCP framing and mirrored-peer incident |
| Telegram shows old commands after menu update | Telegram server-side scope incident |
| Tool discovery deadlocks, aliases mutate, or bad plugin hides rest | Tool-registry adversarial findings |
| Hidden `<memory>` content appears at end of truncated stream | Scrubber `Flush` leak |
| Broad lint cleanup compiles poorly while tests pass | Autofix, `nilerr`, and `308c199` incidents |
| Reused worktree is stale, half-prepared, or coupled to expired objects | Worktree/askpass/cache history |
| Repeated `fix: baseline gate repair` commits or parked tasks cycle | Baseline, no-op, and retry-loop incidents |
| CI cannot resolve `/work/apps/...` | Local module replacement incident |
| Build caches or dependency trees appear in diff | `.gotmp` and `node_modules` incidents |
| `diff_cap_lines = 0` still behaves as 400 | Diff-cap zero contradiction |
## Chronicle: work intake and retry loops
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changed the Compose profile to `assignee`; that file was deleted (`cbb7929e`) and survives as `deployments/docker-nats-stack.toml`, which sets `trigger = "assignee"`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrollment. |
| Baseline-red park storm, 2026-07-23 onward | Task parks on gate failure that existed before its feature work. | Parking/retrying cannot change pre-existing failure; auto-repair mixes repository repair into feature scope. | `b2482af` made `StageBaselineGate` launch builder instead of parking. Nine repair commits in history. **Status:** `current` mitigation and architecture weak point. | Measure untouched baseline first. Track baseline repair as explicit change. |
| Passed build with zero changes, 2026-07-23 | Commit-push reports "no changes," parks, retries, repeats. | "Passed with no changes" lacked terminal domain outcome. | `62c0df1` introduced no-op detection; `2bf42bd` set `Outcome`. `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as explicit terminal result. |
| Infinite parked-task retry, 2026-07-23 | Removing parked label repeatedly requeues with no terminal bound. | Retry count not durable or capped. | `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, explicit bound, terminal state, and operator-visible reason. |
## Chronicle: runtime and peer contracts
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Container network auto-detection, 2026-07-27 | Every container task returns `nats: no responders`. | `selfNetwork` inspected hostnamed container, silently fell back to default bridge. | `37cf089` records incident, adds `containers.network`; `2ac306b` pins `archie-core_default`. **Status:** `conditional`. | Make cross-container network membership explicit in deployment. |
| SecretRef schema crash-loop, 2026-07-27 | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; a later `308c199` removed the `Forge.TokenEnv` declaration while `finalize` still referenced it. | **Status: `settled`** as of 2026-09-18 — `config.Forge.TokenEnv` is declared (`internal/config/config.go`) and `configuration/defaults.go` converts it to an env `SecretRef` when the structured token is empty. | Preserve decoded compatibility until deployed files migrated and rejection of stale keys observable. |
| Compose secret omission, 2026-07-27 | Config names valid env var, container sees it empty. | Compose forwards only listed environment entries. | `22fc0ef`, `d0624b7`. **Status:** `conditional`. | Trace every secret from config key to host value to Compose passthrough to process lookup. |
| FullStream/TextStream deadlock, 2026-07-27 | Streamed Telegram reply renders empty cursor, typing never clears. | ai-sdk makes `FullStream` authoritative and backpressured; `TextStream` is best-effort. | `6a0bd27`. **Status:** `settled` with regression-test gap. | Drain authoritative stream through close. |
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not. | MCP stdio uses newline-delimited JSON. Test subprocess called same helpers, mirroring the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`. **Status:** `settled`. | For wire contracts, test raw canonical frames and independently implemented peer. |
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, DMs show ~60 old Hermes commands. | Telegram chooses most specific scope; older scopes survive redeploys. | `cec0f3e` adds menu and deny-by-default; `576c7f5` publishes all three scopes. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. |
| NATS fetch error looked like empty queue, 2026-07-27 | Consumer receives zero messages, treats JetStream failure as "no work." | Batch error state not checked after channel closed. | `0d09a2e` repro; `78a9145` merged through `21ceef0`. **Status:** `settled`. | Check terminal iterator/batch error state even when data channel is empty. |
## Chronicle: implementation and tooling traps
| Incident and date | Symptom | Root cause | Status |
|---|---|---|---|
| Tool registry passed first implementation but held eight defects, 2026-07-26 | Availability can deadlock; schemas mutate after registration; discovery stops at first bad source; literal extraction wrong. | Callbacks ran under `RLock`, copies shallow/shared, parsing partial, matching broad, discovery fail-fast. | `9f6c36c` lists all eight fixes. **Settled.** Never call extension code under registry lock. Clone nested data. Parse complete grammar. Isolate discovery failures. |
| Memory scrubber `Flush` leak, 2026-07-26 | Stream ending inside `...secret</mem` emits buffered hidden memory to visible response. | Pending bytes did not retain whether captured inside `<memory>` block. | `b4aaaf0`. **Settled.** Test every streaming state at EOF. Flush is security boundary. |
| Linter autofix shadowing, 2026-07-28 | 24-file "style" pass stops compiling. | `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside conditional, shadowing context. | `9b44bac`. **Settled.** Treat autofix output as authored behavior. |
| All eleven `nilerr` findings semantic false positives, 2026-07-28 | Mechanical "fixes" would return Go errors while tests pass, breaking model correction, chat, NATS envelopes, clean shutdown, indexing. | Linter cannot see failures carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19`. **Settled.** Review semantic channels one site at a time. |
| Broad checkpoint hid unresolved merge conflict, 2026-07-27 | Literal conflict marker reached committed source. | Unrelated surfaces combined without whole-diff conflict scan. | `4429ae5`. **Settled.** Keep commits cohesive. |
### Preserve the eight tool-registry review lessons
| Defect fixed in `9f6c36c` | Required review question |
|---|---|
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while lock is held? |
| `Register` stored caller references | Can caller mutate registered state afterward? |
| `Clone` copied nested schema maps/slices shallowly | Is every mutable layer detached? |
| `stringLit` mishandled escapes/backticks | Does parsing follow Go literal semantics? |
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected? |
| `Discover` aborted on first error | Can one bad extension hide healthy extensions? |
| `isRegisterCall` matched too broadly | Is the exact receiver/call shape proven? |
| `schemaLit` accepted only string values | Are booleans, integers, arrays, nested maps preserved? |
## Chronicle: worktree and repository state reversals
| Step and date | Symptom | Root cause | Settled rule |
|---|---|---|---|
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. | Existence did not prove freshness or completed preparation. Later replaced `.git` readiness with sentinel. | Define completed-state marker and revalidate remote/base/branch state on reuse. |
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked setup; go-git `Add(All)` doesn't honor exclude. | Orchestration metadata needs to be outside tracked worktree by construction. | Put sentinel at `.git/archie-prepared`. |
| Askpass rewritten each call, 2026-07-24 | Token-emitting shell script rewritten for every git command. | Comment wasn't invariant; no test checked mtime. Later removed shell git and askpass entirely. | Prefer in-process credentials. |
| Bare object cache, 2026-07-24 | `--reference-if-able --dissociate` plus TTL to accelerate clones. | go-git has no `--dissociate` equivalent; expiring cache would corrupt active worktrees. | Never accept clone acceleration making task correctness depend on expiring cache. |
| Shell git replaced by go-git, 2026-07-28 | Port exposed host GPG inheritance, sentinel tracking, merge-base diff semantics. | RPC handlers used `context.Background`, making in-process clones unbounded. | Audit every adapter and cancellation boundary after replacing killable subprocess with in-process I/O. |
## Chronicle: cleanup, artifacts, and contradictory policy
| Incident and date | Symptom | Root cause | Status | Settled rule |
|---|---|---|---|---|
| Tracked `.gotmp`, 2026-07-27 | Build-cache binaries, generated `_testmain.go`, `.git-askpass` appear in commits. | Workaround path not ignored before use. | `4cb0577` removes artifacts and adds `.gotmp/` to `.gitignore`. **Settled.** | Put caches outside repo or ignore before first command. |
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at that time; the VitePress site was removed (`84b32694`) and `git ls-files | grep -c node_modules` is now **0**. **Settled.** | Track lockfiles, never installed trees. |
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | The focused skillscript test **passes** as of 2026-09-16. **Settled.** | No commit is "cleanup" for gating purposes. |
| `diff_cap_lines = 0` contradiction, introduced at project start | Operators set zero expecting unlimited, but decoded config becomes 400. | `finalize` converts zero to default 400; same sentinel means both "unset" and "unlimited." | **Current/open** contradiction. | Never overload zero value with both defaulting and explicit policy. |
## Keep unmerged work as dated candidates
As of **2026-09-18**, the six `fix/4x` and `feat/5x`/`feat/75` candidate
branches recorded here on 2026-07-28 no longer exist on either remote —
`git branch -r --no-merged HEAD` reports only `gitea/main` (and the Dolt helper
ref). Treat their concerns as `superseded` unless a live branch re-raises one.
| Former candidate branch | Claimed concern |
|---|---|
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` |
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable |
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically |
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors |
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage |
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes |
Verify candidate state:
```sh
git branch -r --no-merged HEAD
git log -1 --date=iso-strict --format='%H %ad %s' <branch>
git diff --stat HEAD...<branch>
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <branch> HEAD
```
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Failure Archaeology"
short_description: "Avoid repeating Archie failure history"
default_prompt: "Use $archie-failure-archaeology to trace this symptom through Archies proven incidents before proposing a fix."
@@ -1,113 +0,0 @@
#!/bin/sh
# on-main.sh -- did this ref land on the trunk, even when it was squash- or
# rebase-merged?
#
# `git merge-base --is-ancestor` answers a topology question: is this exact
# commit object an ancestor. GitHub's "Squash and merge" always mints a new
# commit, and "Rebase and merge" mints new commits whenever the branch had to
# be replayed, so both orphan the SHA your branch holds. The raw check then
# reports a landed repair as never-landed, and `git branch -a --contains` is
# blind in exactly the same way.
#
# This wrapper keeps `--is-ancestor` as the offline fast path and falls back to
# the GitHub API, which records merge state independently of the commit graph.
#
# usage: on-main.sh [-q] <ref> [base-ref]
#
# <ref> commit, tag, or branch to test
# [base-ref] trunk to test against (default: origin/main)
# -q print nothing; report through the exit code only
#
# exit 0 landed on <base-ref>, by ancestry or by a merged pull request
# exit 1 not landed: known to GitHub, but in no merged pull request
# exit 2 undetermined: bad ref, no gh, offline, or never pushed to GitHub
# exit 127 git is missing
#
# exit 2 is not a negative. Branch on the code explicitly; `if on-main.sh <ref>`
# folds it into "not landed", which is the error this helper exists to prevent.
set -eu
quiet=0
while [ "$#" -gt 0 ]; do
case "$1" in
-q | --quiet)
quiet=1
shift
;;
--)
shift
break
;;
-*)
printf 'on-main: unknown option %s\n' "$1" >&2
printf '%s\n' 'usage: on-main.sh [-q] <ref> [base-ref]' >&2
exit 2
;;
*)
break
;;
esac
done
if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
printf '%s\n' 'usage: on-main.sh [-q] <ref> [base-ref]' >&2
exit 2
fi
ref=$1
base=${2:-origin/main}
say() {
[ "$quiet" -eq 1 ] || printf '%s\n' "$1"
}
command -v git >/dev/null 2>&1 || {
printf '%s\n' 'on-main: git is required' >&2
exit 127
}
sha=$(git rev-parse --verify --quiet "${ref}^{commit}") || {
say "undetermined: $ref does not resolve to a commit in this repository"
exit 2
}
git rev-parse --verify --quiet "${base}^{commit}" >/dev/null 2>&1 || {
say "undetermined: base ref $base does not resolve; fetch it, or name the trunk explicitly"
exit 2
}
if git merge-base --is-ancestor "$sha" "$base" 2>/dev/null; then
say "landed: $sha is an ancestor of $base (topology)"
exit 0
fi
# Not an ancestor. The SHA may still have landed if GitHub rewrote it at merge
# time, so ask the service that recorded the merge rather than the commit graph.
command -v gh >/dev/null 2>&1 || {
say "undetermined: $sha is not an ancestor of $base, and gh is absent, so a squash or rebase merge cannot be ruled out"
exit 2
}
merged=$(
gh api "repos/{owner}/{repo}/commits/$sha/pulls" \
--jq '[.[] | select(.merged_at != null)] | length' 2>/dev/null
) || {
say "undetermined: $sha is not an ancestor of $base, and GitHub could not answer for it (offline, unauthenticated, or never pushed)"
exit 2
}
case "$merged" in
'' | *[!0-9]*)
say "undetermined: GitHub returned an unreadable answer for $sha"
exit 2
;;
0)
say "not-landed: $sha is not an ancestor of $base and belongs to no merged pull request"
exit 1
;;
*)
say "landed: $sha is not an ancestor of $base, but GitHub records it in $merged merged pull request(s) -- a squash or rebase merge rewrote the SHA"
exit 0
;;
esac
@@ -1,229 +0,0 @@
---
name: archie-run-and-operate
description: "Run and observe Archie safely with a host daemon and the repository's Docker Compose NATS service. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the image pipeline, or planning an operational rollback without changing architecture."
---
# Run and operate Archie
Use this runbook to operate the implementation that exists on **2026-09-18**
(HEAD `2e1e1549`). Treat source and tests as current; treat `docs/archive/` as
history.
## Define the process shapes
| Term | Meaning here |
|---|---|
| `archied` | Resident orchestrator. Owns config, forge credentials, SQLite stores, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
| `archie-agent` | Long-running NATS worker. Consumes per-stage `archie.agent.>` requests and full-task `archie.taskrun.>` requests. Not a stdin/stdout worker. |
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
| State path prefix | `db_path`: the configured prefix. Task/event state uses `<db_path>-tasks.sqlite`; conversation state uses `<db_path>-conversations.sqlite`. |
## Apply the operational safety boundary
Assume every daemon start can change local and external state.
- Obtain explicit authority for config, forge identity, repositories, NATS
account, Docker host, and deployment host before starting.
- Never use production tokens for a smoke test.
- Do not call `archied -once` as a dry run. It accepts invitations, verifies
push access, polls the forge, enqueues/labels work, reconciles PRs, processes
tasks, and then exits.
- Do not expose the dashboard publicly. It has no authentication, and
`POST /api/tasks/clear` deletes terminal task records.
- Do not print secret values. Record environment-variable **names**, config
checksums, image digests, and paths instead.
- Stop with `Ctrl-C`, `SIGTERM`, or Compose. Do not use `SIGKILL` unless graceful
shutdown has demonstrably failed.
There is no config-only or dry-run flag.
## Know the command surfaces
### `archied`
| Flag | Exact behavior |
|---|---|
| `-config <path>` | Load base TOML. Default: `$XDG_CONFIG_HOME/archie/config.toml`, or `~/.config/archie/config.toml`. |
| `-config-overlay <path>` | Decode a second TOML file into the base config before defaults and validation. |
| `-once` | Run startup plus one poll/process cycle, then exit. This changes state. |
| `-requeue <task-id>` | Requeue a parked/waiting task, then exit unless `-once` is also set. This changes state. |
### `archie-agent`
| Flag or environment | Exact behavior |
|---|---|
| `-nats-url <url>` | Select NATS; falls back to `NATS_URL`. One of them is required. |
| `-consumer <name>` | Set the durable JetStream consumer name; default `archie-agent`. |
| `NATS_TOKEN` | Optional NATS token read directly by the worker. |
Both linked binaries may also display Go's `-quickchecks` flag from
`testing/quick`; it is not an Archie operations control.
## Select the execution mode deliberately
| Config shape | What runs | Operational status on 2026-09-18 |
|---|---|---|
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from SQLite, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. |
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin, one response on stdout. | **Open/broken with default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. |
| `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` runs the workflow; each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** Launch and supervise a worker separately. |
| `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, sends the whole workflow on `archie.taskrun.<id>`. | **Host daemon + Compose NATS path.** `deployments/docker-nats-stack.toml` demonstrates it. |
## Run a local foreground daemon
```bash
task build
task --list
./bin/archied -h
./bin/archie-agent -h
```
Choose an explicitly approved config:
```bash
ARCHIE_CONFIG=/absolute/path/to/config.toml
test -r "$ARCHIE_CONFIG"
./bin/archied -config "$ARCHIE_CONFIG"
```
Expect JSON logs on stderr. Require: `nats connected` when `[nats]` configured;
`workflow registry built`; `memory manager started`; `web ui listening` unless
`web.listen = "off"`; gateway-start messages for configured channels;
`archied running` after startup verification. Absence of `archied running` means
startup did not complete. The daemon has no HTTP health endpoint.
Stop with `Ctrl-C`. The signal cancels active work, waits for dispatch
goroutines, stops capability and memory managers, removes Archie-labelled
containers, closes NATS, and closes the SQLite stores.
## Run a standalone NATS worker
```bash
NATS_URL=nats://127.0.0.1:4222 ./bin/archie-agent
```
Require both `nats connected` and `archie-agent ready`. Stop with `Ctrl-C`.
Do not use this to test subprocess mode.
## Run the repository Compose stack
| Repository command | Actual scope |
|---|---|
| `task docker-build` | Build only the `agent` image from `Dockerfile`. |
| `task docker-up` | Start the Compose-managed NATS service. The profiled agent entry is not started. |
| `task docker-logs` | Follow the NATS service logs. |
| `task docker-down` | Run `docker compose down`. Does not request volume deletion. |
Prefer the narrow start:
```bash
docker compose up -d nats
```
Read-only observations:
```bash
docker compose ps
docker compose logs --tail=200 nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
```bash
curl -fsS http://127.0.0.1:8484/api/summary
curl -fsS http://127.0.0.1:8484/api/tasks
```
Wait for the NATS healthcheck, then start `archied` on the host. Require the
configured host supervisor to report it running and verify the dashboard API
as the daemon readiness gate.
Stop with:
```bash
task docker-down
```
Never add `-v` during routine shutdown. The Compose `agent` service is a
build-profile image definition, not a long-running service. Actual task workers
are spawned by the host `archied` process through `/var/run/docker.sock`.
## Locate output and durable state
| Output or state | Current destination |
|---|---|
| Daemon logs | JSON on host stderr; the configured host supervisor captures them. |
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. |
| Tasks and events | SQLite database at `<db_path>-tasks.sqlite`; default `~/.local/share/archie/archie.db-tasks.sqlite`. |
| Chat sessions and messages | SQLite database at `<db_path>-conversations.sqlite`. |
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written under `.git/` so the agent's commit cannot sweep it onto the task branch. |
| Built-in memory | `<work_dir>/memory/MEMORY.md` and `<work_dir>/memory/USER.md`. |
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus hashed `release-announcements-*.json`. |
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction found in daemon composition root. |
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. |
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, etc., mounted below `/data/cache`. No code sets tool cache env vars to those mount paths. |
| NATS data | Compose declares `nats_data:/data`; NATS command does not set a store directory. |
Compose runs NATS only; `archied` and all configured state paths remain on the
host. The host daemon talks to the local Docker socket directly and bind-mounts
each task worktree into the agent container it creates.
## Understand NATS and container observation
The `ARCHIE_TASKS` JetStream stream uses file storage and work-queue retention
for `archie.task.>` and `archie.agent.>`.
| Plane | Subjects and behavior |
|---|---|
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-min ack wait, max 3 deliveries. |
| Per-stage requests | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-min ack wait, max 3 deliveries; response address in `X-Archie-Reply`. |
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/.git/task.json` and creates dedicated subscription; shared worker uses queue group `archie-taskrun-workers`. |
| Privileged RPC | Store operations go to the gRPC State Store (`internal/infrastructure/staterpc`, task-scoped grants); forge and worktree operations return to `archied` over core NATS subjects in `internal/forgerpc` and `internal/worktreerpc`. |
Set `containers.network` explicitly. `deployments/docker-nats-stack.toml` uses
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
workers join Docker's default bridge and cannot resolve `nats`. Initial
`ErrNoResponders` is retried for 20s at 250ms intervals.
If `nats.token_env` is configured, `archied` refuses startup when that variable
is empty. It injects the resolved value as `NATS_TOKEN` into task containers.
It forwards only configured provider-key variables.
## Fence current operational limitations
Open limitations until code/tests prove otherwise:
- `subprocess` + default `archie-agent` is protocol-incompatible.
- A deployed overlay previously using legacy `token_env` still converts: the
structured `forge.token` secret reference wins when both are present and
`config.Forge.TokenEnv` is otherwise converted by
`internal/infrastructure/configuration/defaults.go`.
- Container RPC uses root forge/worktree for every identity.
- Container orphan recovery lacks daemon-instance label.
- `max_uptime` only bounds `Pool.Acquire` create/start; no lifetime timer.
- Container workflow builds `TaskContext` without event bus.
- SSE clients drop when channel full; replay at most 200 events.
- Dashboard unauthenticated, includes mutating clear endpoint.
## Understand deployment and rollback seams
`.github/workflows/deploy.yml` gates on the release tags, then builds/pushes
`archied:latest` and `archie-agent:latest` plus a versioned
`linux/amd64` distribution zip attached to a GitHub Release. It injects
component versions into labels/metadata and runs the quality gate before the
Docker builds. The Gitea workflow that used to be the production build path was
dropped (`dd9bddc2`); `deployments/*.toml` are the supported profiles.
Before promotion: record running image IDs/digests; config checksums (no
secrets); task counts via safe GET; establish a SQLite backup procedure.
No complete rollback command exists, no versioned image tags. Restoring a binary
does not undo forge changes, task transitions, or data-format changes.
## Treat carina facts as unverified external state
Repository guidance (2026-09-18): two instances on `carina` with distinct
`bot_user` values. No live process list, config, image digest, service manager,
or deployment was verified. Do not invent SSH, systemd, or service commands.
@@ -1,4 +0,0 @@
interface:
display_name: "Run and Operate Archie"
short_description: "Run Archie safely and locate its operational state"
default_prompt: "Use $archie-run-and-operate to start Archie locally, inspect its runtime state, and stop it safely."
-89
View File
@@ -1,89 +0,0 @@
# Dolt database (managed by Dolt, not git)
dolt/
embeddeddolt/
proxieddb/
# Runtime files
bd.sock
bd.sock.startlock
sync-state.json
last-touched
.exclusive-lock
# Daemon runtime (lock, log, pid)
daemon.*
# Push state (runtime, per-machine)
push-state.json
# Lock files (various runtime locks)
*.lock
# Credential key (encryption key for federation peer auth — never commit)
.beads-credential-key
# Local version tracking (prevents upgrade notification spam after git ops)
.local_version
proxied_server_client_info.json
# Worktree redirect file (contains relative path to main repo's .beads/)
# Must not be committed as paths would be wrong in other clones
redirect
# Sync state (local-only, per-machine)
# These files are machine-specific and should not be shared across clones
.sync.lock
# Workspace operation gate (internal/workspacegate): physical-root gate
# files live beside the guarded root inside .beads (e.g. dolt.gate.lock)
*.gate.lock*
export-state/
export-state.json
last_pull
# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
ephemeral.sqlite3
ephemeral.sqlite3-journal
ephemeral.sqlite3-wal
ephemeral.sqlite3-shm
# Dolt server management (auto-started by bd)
dolt-server.pid
dolt-server.log
dolt-server.lock
dolt-server.port
dolt-server.activity
# Debug-mode pprof artifacts (written when dolt.debug: true in config.yaml)
dolt-pprof/
# Corrupt backup directories (created by bd doctor --fix recovery)
*.corrupt.backup/
# issues.jsonl is deliberately TRACKED (see export.git-add in config.yaml).
# Dolt remains the authoritative store and GitHub the external issue surface;
# the tracked export exists so issue state is readable and recoverable from a
# plain git clone, without a Dolt server. Removing it from this file is what
# tracks it -- do NOT add a "!issues.jsonl" negation, which would override the
# fork protection in .git/info/exclude (see the note at the end of this file).
#
# Backups stay local: they are point-in-time copies of the same data.
backup/
# Per-project environment file (Dolt connection config, GH#2520)
.env
# Legacy files (from pre-Dolt versions)
*.db
*.db?*
*.db-journal
*.db-wal
*.db-shm
db.sqlite
bd.db
# NOTE: Do NOT add negation patterns here.
# They would override fork protection in .git/info/exclude.
# Config files (metadata.json, config.yaml) are tracked by git by default
# since no pattern above ignores them.
# config.yaml
-81
View File
@@ -1,81 +0,0 @@
# Beads - AI-Native Issue Tracking
Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
## What is Beads?
Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
## Quick Start
### Essential Commands
```bash
# Create new issues
bd create "Add user authentication"
# View all issues
bd list
# View issue details
bd show <issue-id>
# Update issue status
bd update <issue-id> --claim
bd update <issue-id> --status done
# Sync with Dolt remote
bd dolt push
```
### Working with Issues
Issues in Beads are:
- **Git-native**: Stored in Dolt database with version control and branching
- **AI-friendly**: CLI-first design works perfectly with AI coding agents
- **Branch-aware**: Issues can follow your branch workflow
- **Sync-ready**: Uses Dolt remotes for backup and team sharing
## Why Beads?
✨ **AI-Native Design**
- Built specifically for AI-assisted development workflows
- CLI-first interface works seamlessly with AI coding agents
- No context switching to web UIs
🚀 **Developer Focused**
- Issues live in your repo, right next to your code
- Works offline, syncs when you push
- Fast, lightweight, and stays out of your way
🔧 **Git Integration**
- Dolt-native sync via bd dolt push / bd dolt pull
- Branch-aware issue tracking
- Dolt-native three-way merge resolution
## Get Started with Beads
Try Beads in your own projects:
```bash
# Install Beads
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Initialize in your repo
bd init
# Create your first issue
bd create "Try out Beads"
```
## Learn More
- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
- **Quick Start Guide**: Run `bd quickstart`
- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
---
*Beads: Issue tracking that moves at the speed of thought* ⚡
-80
View File
@@ -1,80 +0,0 @@
# Beads Configuration File
# This file configures default behavior for all bd commands in this repository
# All settings can also be set via environment variables (BD_* prefix)
# or overridden with command-line flags
# Issue prefix for this repository (used by bd init)
# If not set, bd init will auto-detect from directory name
# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
# issue-prefix: ""
# Use no-db mode: JSONL-only, no Dolt database
# When true, .beads/issues.jsonl is the only local store
# no-db: false
# Enable JSON output by default
# json: false
# Feedback title formatting for mutating commands (create/update/close/dep/edit)
# 0 = hide titles, N > 0 = truncate to N characters
# output:
# title-length: 255
# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
# actor: ""
# Optional JSONL sidecar for explicit agent/tool interaction audit records.
# Issue history is always recorded in the database and is visible with
# bd history <id> --events; this only controls .beads/interactions.jsonl.
# audit:
# enabled: false
# Export events (audit trail) to .beads/events.jsonl on each flush/sync
# When enabled, new events are appended incrementally using a high-water mark.
# Use 'bd export --events' to trigger manually regardless of this setting.
# events-export: false
# Multi-repo configuration (experimental - bd-307)
# Allows hydrating from multiple repositories and routing writes to the correct database
# repos:
# primary: "." # Primary repo (where this database lives)
# additional: # Additional repos to hydrate from (read-only)
# - ~/beads-planning # Personal planning repo
# - ~/work-planning # Work planning repo
# Dolt-native backup (periodic backup for off-machine recovery)
# This is full database backup only. Cross-machine sync uses Dolt remotes.
# backup:
# enabled: false # Disable auto-backup entirely
# interval: 15m # Minimum time between auto-backups
# git-push: false # Disable git push (backup locally only)
# git-repo: "" # Separate git repo for backups (default: project repo)
# Optional JSONL auto-export for viewers, interchange, and issue-level migration.
# Disabled by default; enable only when an integration needs fresh .beads/issues.jsonl.
# Use relative paths under .beads/ for JSONL import/export filenames.
export:
auto: false
path: issues.jsonl
interval: 60s
# issues.jsonl/interactions.jsonl are .gitignore'd local-only files --
# Dolt (synced via sync.remote) is the source of truth. Leave auto off
# and git-add off; do not re-track these in git.
git-add: false
import:
path: issues.jsonl
# Integration settings (access with 'bd config get/set')
# Non-secret keys (stored in the database):
# - jira.url, jira.project
# - linear.team_id
# - github.org, github.repo
#
# Secret keys (stored in this file but prefer env vars to avoid git exposure):
# - linear.api_key → use LINEAR_API_KEY env var instead
# - github.token → use GITHUB_TOKEN env var instead
sync.remote: "git+https://github.com/samcharles93/archie-core.git"
dolt:
shared-server: false
auto-commit: "on"
audit:
enabled: true
-33
View File
@@ -1,33 +0,0 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
_bd_used_perl=0
if command -v timeout >/dev/null 2>&1; then
timeout "$_bd_timeout" bd hooks run post-checkout "$@"
_bd_exit=$?
elif command -v gtimeout >/dev/null 2>&1; then
gtimeout "$_bd_timeout" bd hooks run post-checkout "$@"
_bd_exit=$?
elif command -v perl >/dev/null 2>&1; then
_bd_used_perl=1
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run post-checkout "$@"
_bd_exit=$?
else
echo >&2 "beads: hook 'post-checkout' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
bd hooks run post-checkout "$@"
_bd_exit=$?
fi
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ $_bd_exit -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
_bd_exit=0
fi
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
fi
# --- END BEADS INTEGRATION v1.2.2 ---
-33
View File
@@ -1,33 +0,0 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
_bd_used_perl=0
if command -v timeout >/dev/null 2>&1; then
timeout "$_bd_timeout" bd hooks run post-merge "$@"
_bd_exit=$?
elif command -v gtimeout >/dev/null 2>&1; then
gtimeout "$_bd_timeout" bd hooks run post-merge "$@"
_bd_exit=$?
elif command -v perl >/dev/null 2>&1; then
_bd_used_perl=1
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run post-merge "$@"
_bd_exit=$?
else
echo >&2 "beads: hook 'post-merge' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
bd hooks run post-merge "$@"
_bd_exit=$?
fi
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ $_bd_exit -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
_bd_exit=0
fi
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
fi
# --- END BEADS INTEGRATION v1.2.2 ---
-33
View File
@@ -1,33 +0,0 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
_bd_used_perl=0
if command -v timeout >/dev/null 2>&1; then
timeout "$_bd_timeout" bd hooks run pre-commit "$@"
_bd_exit=$?
elif command -v gtimeout >/dev/null 2>&1; then
gtimeout "$_bd_timeout" bd hooks run pre-commit "$@"
_bd_exit=$?
elif command -v perl >/dev/null 2>&1; then
_bd_used_perl=1
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run pre-commit "$@"
_bd_exit=$?
else
echo >&2 "beads: hook 'pre-commit' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
bd hooks run pre-commit "$@"
_bd_exit=$?
fi
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ $_bd_exit -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
_bd_exit=0
fi
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
fi
# --- END BEADS INTEGRATION v1.2.2 ---
-33
View File
@@ -1,33 +0,0 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
_bd_used_perl=0
if command -v timeout >/dev/null 2>&1; then
timeout "$_bd_timeout" bd hooks run pre-push "$@"
_bd_exit=$?
elif command -v gtimeout >/dev/null 2>&1; then
gtimeout "$_bd_timeout" bd hooks run pre-push "$@"
_bd_exit=$?
elif command -v perl >/dev/null 2>&1; then
_bd_used_perl=1
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run pre-push "$@"
_bd_exit=$?
else
echo >&2 "beads: hook 'pre-push' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
bd hooks run pre-push "$@"
_bd_exit=$?
fi
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ $_bd_exit -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
_bd_exit=0
fi
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
fi
# --- END BEADS INTEGRATION v1.2.2 ---
-33
View File
@@ -1,33 +0,0 @@
#!/usr/bin/env sh
# --- BEGIN BEADS INTEGRATION v1.2.2 ---
# This section is managed by beads. Do not remove these markers.
if command -v bd >/dev/null 2>&1; then
export BD_GIT_HOOK=1
_bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
_bd_used_perl=0
if command -v timeout >/dev/null 2>&1; then
timeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
_bd_exit=$?
elif command -v gtimeout >/dev/null 2>&1; then
gtimeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
_bd_exit=$?
elif command -v perl >/dev/null 2>&1; then
_bd_used_perl=1
perl -e 'alarm shift; exec @ARGV' "$_bd_timeout" bd hooks run prepare-commit-msg "$@"
_bd_exit=$?
else
echo >&2 "beads: hook 'prepare-commit-msg' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
bd hooks run prepare-commit-msg "$@"
_bd_exit=$?
fi
if [ $_bd_exit -eq 124 ] || { [ $_bd_used_perl -eq 1 ] && [ $_bd_exit -eq 142 ]; }; then
echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
_bd_exit=0
fi
if [ $_bd_exit -eq 3 ]; then
echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
_bd_exit=0
fi
if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi
fi
# --- END BEADS INTEGRATION v1.2.2 ---
-8
View File
@@ -1,8 +0,0 @@
{
"database": "dolt",
"backend": "dolt",
"dolt_mode": "embedded",
"dolt_database": "archie_core",
"project_id": "e8a66150-1f5f-42d2-8653-dcf8463cef74",
"last_bd_version": "1.2.2"
}
+6 -1
View File
@@ -10,7 +10,12 @@
bin/
dist/
docs/
node_modules/
tmp/
.playwright-mcp/
# A trailing-slash pattern matches only the context root, so this is written to
# match a node_modules at any depth: ui/node_modules alone is 200MB and the
# agent image compiles Go, which needs none of it.
**/node_modules/
# Stray host-built binaries committed at the repo root.
/archied
+61
View File
@@ -0,0 +1,61 @@
# Every 15 minutes, checks how the release installed on the canary host is
# running, judged over the window counted from its install (-window, default
# 24h; CANARY_WINDOW overrides it). If a hard check fails, the canary goes
# back to the stable release straight away. If the release stays healthy for
# the window, it's promoted to stable. A rollback fails the run, so it shows
# up red.
name: canary
on:
schedule:
- cron: "*/15 * * * *"
workflow_dispatch:
concurrency:
group: canary
permissions:
contents: read
packages: write
jobs:
judge:
if: vars.CANARY_URL != ''
runs-on: self-hosted
steps:
# Full history with tags: a rollback compares the migrations between
# the stable and failed release tags.
- name: Checkout
uses: actions/checkout@v4
with:
ref: main
fetch-depth: 0
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version-file: go.mod
# The self-hosted runner keeps the Go caches on disk between jobs, and
# archiving them for the Actions cache takes minutes.
cache: false
- name: Build archied
# The check never serves the dashboard, so the build leaves it out.
run: go build -tags no_ui -o "$RUNNER_TEMP/archied" ./cmd/archied
# Promotion retags stable and the images' latest in the registry.
- name: Log in to the Gitea registry
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
- name: Judge the canary
env:
ARCHIE_CANARY_TOKEN: ${{ secrets.CANARY_TOKEN }}
CANARY_WINDOW: ${{ vars.CANARY_WINDOW }}
run: |
window_args=()
if [ -n "$CANARY_WINDOW" ]; then
window_args=(-window "$CANARY_WINDOW")
fi
"$RUNNER_TEMP/archied" release canary check -dashboard "${{ vars.CANARY_URL }}" \
"${window_args[@]}" \
-latest git.catlow.cloud/sam/archied,git.catlow.cloud/sam/archie-agent
+210 -129
View File
@@ -1,25 +1,26 @@
# Builds and pushes the archied and archie-agent images to GHCR on every
# merge to main. Mirrors .gitea/workflows/deploy.yml, which remains the
# production build path against git.catlow.cloud until that's cut over.
# Builds and pushes the archied and archie-agent images to the Gitea
# registry on every merge to main, and publishes the distribution zip as a
# release on this repository. Gitea Actions reads this .github/workflows/
# directory.
name: deploy
on:
push:
branches: [main]
tags: ["archied/v*", "archie/v*", "v*"]
tags: ["v*"]
# Rapid successive pushes to main (a release commit right after its
# preceding fix, say) previously queued a full gate+build for each one,
# several minutes apiece, with no caching -- so a burst of pushes left
# three deploys racing in parallel for the same runner capacity. Only the
# last one's images matter (both jobs push :latest), so cancel a
# last one's images matter (each job pushes its image tags), so cancel a
# superseded run rather than let it fight for resources it can't use.
#
# Keyed on the commit, not github.ref: `git push --follow-tags` pushes
# main plus both archied/v* and archie/v* tags in one go, and all three
# refs point at the same commit -- on.push matches branches and tags
# both, so a single release push otherwise fires three redundant builds
# of identical content that a ref-keyed group can't see as the same work.
# Keyed on the commit, not github.ref: a release push lands main and its
# tag in one go, both pointing at the same commit -- on.push matches
# branches and tags both, so a single release push otherwise fires
# redundant builds of identical content that a ref-keyed group can't see
# as the same work.
concurrency:
group: deploy-${{ github.sha }}
cancel-in-progress: true
@@ -30,7 +31,7 @@ permissions:
jobs:
gate:
runs-on: ubuntu-latest
runs-on: self-hosted
outputs:
archied_version: ${{ steps.release_tag.outputs.archied_version }}
steps:
@@ -46,7 +47,7 @@ jobs:
- name: Resolve archied tag at HEAD
id: release_tag
run: |
version="$(git tag --points-at HEAD --list 'archied/v*' --list 'v*' | sed -e 's|^archied/v||' -e 's|^v||' | sort -V | tail -1)"
version="$(git tag --points-at HEAD --list 'v*' | sed -e 's|^v||' | sort -V | tail -1)"
echo "archied_version=$version" >> "$GITHUB_OUTPUT"
if [ -n "$version" ]; then
echo "archied release at HEAD: $version"
@@ -58,6 +59,13 @@ jobs:
uses: actions/setup-go@v5
with:
go-version-file: go.mod
# The self-hosted runner keeps the Go caches on disk between jobs, and
# archiving them for the Actions cache takes minutes.
cache: false
- uses: pnpm/action-setup@v4
with:
package_json_file: ui/package.json
- name: Set up Node
uses: actions/setup-node@v4
@@ -66,8 +74,9 @@ jobs:
- name: Install quality tools
run: |
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(cat .golangci-version)
go install mvdan.cc/gofumpt@v0.11.0
go install github.com/go-task/task/v3/cmd/task@v3.48.0
- name: Install protobuf tools
run: bash tools/proto.sh install
@@ -78,33 +87,32 @@ jobs:
git branch main origin/main
fi
- name: Install ripgrep
run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ripgrep
# ripgrep and the unprivileged-userns sysctl are provisioned on the host.
# A self-hosted runner should not need sudo, and installing a package on
# every run is not the gate's job.
- name: Verify unprivileged user namespaces
run: unshare --user --map-root-user --net true
# The gate's uncached `go test ./...` runs the Docker-backed tests that
# -short skips, and those start a container from alpine:3. A fresh runner
# has no such image, so the suite failed on "No such image: alpine:3".
- name: Pull test container images
run: docker pull alpine:3
# One definition of the gate, in the Taskfile. TEST_FLAGS is the one
# difference: the release runs the whole suite, uncached and including
# the Docker-backed tests -short skips. The diff after it asserts
# `task fmt` changed nothing.
- name: Quality gate
run: |
go fix ./...
golangci-lint fmt
task check TEST_FLAGS=-count=1
git diff --exit-code
bash tools/proto.sh lint
bash tools/proto.sh check
go vet ./...
golangci-lint run ./...
go build ./...
go test ./... -count=1
- name: Vulnerability scan
run: |
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...
# The dashboard suite runs in CI too, or it only ever runs when
# someone remembers to; the Go steps above never touch it.
- name: Dashboard tests
run: |
npm ci --prefix ui || npm install --prefix ui
npm test --prefix ui
- name: Release tags must match changelogs
run: |
set -e
@@ -119,33 +127,21 @@ jobs:
fail=1
}
;;
archied/v* | archie/v*)
# Legacy per-component tags. History is not re-tagged, and the
# merged CHANGELOG.md carries every component's versions, so the
# section is found there rather than in a component file.
ver="${tag#*/v}"
echo " legacy tag $tag -> looking for [$ver] in CHANGELOG.md"
grep -q "^## \\[$ver\\]" CHANGELOG.md || {
echo " FAIL: CHANGELOG.md has no [$ver] section"
fail=1
}
;;
esac
done
if [ $fail -ne 0 ]; then
echo
echo "A release tag points at this commit but its changelog does not"
echo "describe that version. Run: task release:prepare VERSION=<ver>"
echo "edit the generated notes, then: task release VERSION=<ver>"
echo "describe that version. Cut releases with the release workflow."
exit 1
fi
if ! git tag --points-at HEAD | grep -qE '^(v[0-9]|archied/v|archie/v)' ; then
echo "::warning ::No release tags at HEAD, so this build publishes :latest for a commit that is not a release. It is stamped dev+<sha> and tagged sha-<sha> so it stays traceable and restorable, but it supersedes the previous release's :latest stamping until the next release is cut."
if ! git tag --points-at HEAD | grep -qE '^v[0-9]' ; then
echo "This commit isn't a release, so the images are published as :edge and sha-<sha>; :latest keeps naming the newest promoted release."
fi
build-and-push:
archied-image:
needs: gate
runs-on: ubuntu-latest
runs-on: self-hosted
steps:
- name: Checkout
uses: actions/checkout@v4
@@ -153,11 +149,8 @@ jobs:
fetch-depth: 0
# Deliberately NOT `github.sha`. On a tag push that is the ref's OBJECT id,
# and every release tag in this repo is annotated — measured, 80 of 80
# `archied/v*` and `archie/v*` tags are tag objects — so it names something
# that cannot be checked out. `archied/v1.36.0` is an instance: it points at
# 6720bc42 (a tag object) and dereferences to commit c25f8d39. The producer
# is right to create annotated tags; the consumer stops guessing.
# and every release tag in this repo is annotated, so it names a tag object
# that cannot be checked out. Dereference it to the commit.
- name: Resolve the commit this ref points at
id: commit
run: |
@@ -168,40 +161,45 @@ jobs:
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GHCR
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
- name: Log in to the Gitea registry
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
- name: Resolve component versions
id: versions
run: |
GATEWAY_TAG="$(git tag --points-at HEAD --list 'archied/v*' | sort -V | tail -1)"
RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"
# One release stream: a `v*` tag covers the whole release, so it names
# both components' versions. Legacy per-component tags still win where
# they exist, because history is not re-tagged.
# One release stream: a `v*` tag names both components' versions.
RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"
GATEWAY_VERSION="${GATEWAY_TAG#archied/}"
RUNTIME_VERSION="${RUNTIME_TAG#archie/}"
[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="${RELEASE_TAG#v}"
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="${RELEASE_TAG#v}"
# Not a bare `dev`. A literal dev tells an operator nothing about which
# build they are running, and it is what made a release's stamping look
# transient: the next commit to main republished :latest as `dev`. The
# commit is appended so a main build is identifiable and is visibly not
# a release. (On an untagged push GITHUB_SHA IS the commit — the tag
# case is handled by the dereference above.)
GATEWAY_VERSION="${RELEASE_TAG#v}"
RUNTIME_VERSION="${RELEASE_TAG#v}"
# `dev+<sha>` is what a build that is NOT a release reports, and it is
# honest now that such a build no longer publishes :latest: the version
# names the commit it came from, and the sha-<sha> tag makes it
# restorable. Before, this same string reached :latest minutes after a
# release and made the release's own stamping read as dev
# (archie-core-i5nb). (On an untagged push GITHUB_SHA IS the commit —
# the tag case is handled by the dereference above.)
[ -n "$GATEWAY_VERSION" ] || GATEWAY_VERSION="dev+${GITHUB_SHA:0:12}"
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="dev+${GITHUB_SHA:0:12}"
# Keep the raw tag presence separate from the version fallback: a
# LEGACY gateway-only release (archied/v* and no archie/v*) must not
# rebuild the runtime image as dev. A one-stream `v*` release is not
# gateway-only -- one version covers the runtime too -- so it does
# rebuild it, and release_tag is what tells the two apart.
echo "gateway_tag=$GATEWAY_TAG" >> "$GITHUB_OUTPUT"
echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"
echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
echo "gateway=$GATEWAY_VERSION" >> "$GITHUB_OUTPUT"
echo "runtime=$RUNTIME_VERSION" >> "$GITHUB_OUTPUT"
# :latest names the newest PROMOTED release, so a release publishes
# :v<version> and canary promotion moves :latest to it. A push to
# main publishes :edge (mutable, newest main) and sha-<sha>
# (immutable), so an ordinary commit never overwrites a release's
# stamping.
#
# `if` blocks rather than `[ -n "$X" ] && echo`: the latter returns
# non-zero when the test fails, and these steps run under `set -e`.
{
echo "archied_tags<<EOF"
if [ -n "$RELEASE_TAG" ]; then
echo "git.catlow.cloud/sam/archied:$RELEASE_TAG"
fi
echo "git.catlow.cloud/sam/archied:edge"
echo "git.catlow.cloud/sam/archied:sha-${{ steps.commit.outputs.sha }}"
echo "EOF"
} >> "$GITHUB_OUTPUT"
- name: Build and push archied
uses: docker/build-push-action@v6
@@ -209,41 +207,72 @@ jobs:
context: .
file: Dockerfile.archied
push: true
tags: |
ghcr.io/samcharles93/archied:latest
ghcr.io/samcharles93/archied:sha-${{ steps.commit.outputs.sha }}
tags: ${{ steps.versions.outputs.archied_tags }}
build-args: |
GATEWAY_VERSION=${{ steps.versions.outputs.gateway }}
RUNTIME_VERSION=${{ steps.versions.outputs.runtime }}
cache-from: type=gha,scope=archied
cache-to: type=gha,mode=max,scope=archied
agent-image:
outputs:
agent_digest: ${{ steps.agent.outputs.digest }}
needs: gate
runs-on: self-hosted
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
# Annotated tags: dereference to the commit, as archied-image does.
- name: Resolve the commit this ref points at
id: commit
run: |
sha="$(git rev-parse "${GITHUB_REF}^{commit}")"
echo "sha=$sha" >> "$GITHUB_OUTPUT"
echo "short=${sha:0:12}" >> "$GITHUB_OUTPUT"
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to the Gitea registry
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
- name: Resolve runtime version
id: versions
run: |
RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"
RUNTIME_VERSION="${RELEASE_TAG#v}"
echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
echo "runtime=$RUNTIME_VERSION" >> "$GITHUB_OUTPUT"
- name: Build and push archie-agent
if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''
id: agent
if: steps.versions.outputs.release_tag != ''
uses: docker/build-push-action@v6
with:
context: .
file: Dockerfile
push: true
tags: |
ghcr.io/samcharles93/archie-agent:latest
ghcr.io/samcharles93/archie-agent:sha-${{ steps.commit.outputs.sha }}
git.catlow.cloud/sam/archie-agent:${{ steps.versions.outputs.release_tag }}
git.catlow.cloud/sam/archie-agent:sha-${{ steps.commit.outputs.sha }}
build-args: |
RUNTIME_VERSION=${{ steps.versions.outputs.runtime }}
cache-from: type=gha,scope=archie-agent
cache-to: type=gha,mode=max,scope=archie-agent
# Packages every host-run binary (archied, archie-gateway,
# archie-state-store, archie-ui, archie-messaging, archie-playbooks) as a
# archie-state-store, archie-ui, archie-messaging) as a
# linux/amd64 zip for a
# non-Docker install. Independent of build-and-push: it never touches the
# archied/archie-agent image jobs, and a gateway-only release (no
# archie/v* tag) still produces this zip -- it's keyed to the archied tag
# alone. archie-agent is deliberately excluded: it only ever runs inside
# the Docker image build-and-push already publishes, never as a host
# binary (archie-core-8cda.4.7.1).
# non-Docker install, plus archie-agent: it has no unit, but a Kit run
# mounts it from archied's directory, so a host without it parks them.
# It waits only for the agent image, whose digest
# release.json pins.
dist-zip:
needs: gate
needs: [gate, agent-image]
# Not gated on github.ref. A release is pushed as main plus both tags at
# one SHA, the concurrency group below collapses those into a single run,
# and the survivor is whichever ref happened to start last -- for
@@ -252,11 +281,7 @@ jobs:
# the ref that won the race, and skip only when there is genuinely no
# archied tag at HEAD.
if: needs.gate.outputs.archied_version != ''
runs-on: ubuntu-latest
# Least privilege: the workflow default is contents:read, and only this
# job needs to write, to create the Release and attach the zip to it.
permissions:
contents: write
runs-on: self-hosted
steps:
- name: Checkout
uses: actions/checkout@v4
@@ -265,6 +290,25 @@ jobs:
uses: actions/setup-go@v5
with:
go-version-file: go.mod
# The self-hosted runner keeps the Go caches on disk between jobs, and
# archiving them for the Actions cache takes minutes.
cache: false
- uses: pnpm/action-setup@v4
with:
package_json_file: ui/package.json
- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: "24"
# archied and archie-ui embed the dashboard.
- name: Build the dashboard
working-directory: ui
run: |
pnpm install --frozen-lockfile
pnpm run build
- name: Resolve archied version
id: version
@@ -288,9 +332,12 @@ jobs:
# ran on with a dead Telegram bot and no error anywhere
# (archie-core-1c01). TestDistZipShipsEveryHostCommand fails if this
# list and the copy list below stop matching the commands in cmd/.
ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }}"
ldflags="-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/app/agentworker.version=${{ steps.version.outputs.version }}"
mkdir -p dist
for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do
# Units first, then the binaries that run beside them without one.
# The agentworker stamp only lands in archie-agent; the linker
# ignores -X for a symbol a binary does not import.
for cmd in $(jq -r '.required_topology.units[], .required_topology.binaries[]?' release.json); do
go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd"
done
@@ -300,8 +347,13 @@ jobs:
set -e
name="archie-core-archied-v${{ steps.version.outputs.version }}-linux-amd64"
mkdir -p "$name"
cp dist/archied dist/archie-gateway dist/archie-state-store dist/archie-ui dist/archie-messaging dist/archie-playbooks "$name/"
for cmd in $(jq -r '.required_topology.units[], .required_topology.binaries[]?' release.json); do
cp "dist/$cmd" "$name/"
done
cp deployments/INSTRUCTIONS.md CHANGELOG.md "$name/"
digest='${{ needs.agent-image.outputs.agent_digest }}'
test -n "$digest"
jq --arg image "git.catlow.cloud/sam/archie-agent@$digest" '. + {agent_image: $image}' release.json > "$name/release.json"
# README.md doesn't exist yet in this repo; include it once it does
# rather than fail the release on its absence.
[ -f README.md ] && cp README.md "$name/"
@@ -315,29 +367,36 @@ jobs:
path: ${{ steps.zip.outputs.name }}.zip
retention-days: 90
# A Release is what an operator can actually download from; the
# artifact above is reachable only from the run's page, behind an
# Actions login, and expires after 90 days. Until this step existed the
# zip was produced and then stranded -- the only Release on this repo
# (archied/v1.22.0) was created by hand and carries no asset at all.
#
# Attached to the *archied* tag because the zip is named and versioned
# for archied, and `--follow-tags` pushes both tags at one commit.
# --generate-notes is deliberately not used: the changelog section is
# the release's own reviewed prose, and the tag/changelog gate above
# already guarantees it describes this version.
- name: Publish GitHub Release with the distribution zip
# Installs and updates take a release from the signed artifact in the
# registry, so this is what publishes it: the statement signed with
# RELEASE_SIGNING_KEY and the zip, tagged v<version> and next. stable
# moves only when canary.yml promotes it.
- name: Log in to the Gitea registry
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
- name: Publish the signed release
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ARCHIE_RELEASE_SEED: ${{ secrets.RELEASE_SIGNING_KEY }}
run: |
set -e
tag="archied/v${{ steps.version.outputs.version }}"
version="${{ steps.version.outputs.version }}"
# The release body is this version's changelog section, not the whole
# file: from its "## [x.y.z]" heading to the next "## [" heading.
# Extracting rather than inlining keeps the changelog the single
# source of truth, and the tag/changelog gate above has already
# proven that section exists.
prerelease=false
case "$version" in *-*) prerelease=true ;; esac
./dist/archied release publish -source git.catlow.cloud/sam/archie \
-version "$version" -prerelease="$prerelease" \
-zip "${{ steps.zip.outputs.name }}.zip" \
-agent-image "git.catlow.cloud/sam/archie-agent@${{ needs.agent-image.outputs.agent_digest }}" \
-changelog "https://git.catlow.cloud/sam/archie/releases/tag/v$version"
# The release page carries this version's changelog section, the
# release's own reviewed prose; the signed statement links to it.
- name: Publish the Gitea release notes
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: |
set -e
tag="v${{ steps.version.outputs.version }}"
version="${{ steps.version.outputs.version }}"
notes="$(mktemp)"
awk -v hdr="## [$version]" '
index($0, hdr) == 1 { printing = 1 }
@@ -348,15 +407,37 @@ jobs:
echo "no [$version] section extracted from CHANGELOG.md" >&2
exit 1
fi
# Idempotent: --clobber replaces the asset and leaves the notes
# alone, so a re-run of this job (a retried or superseded deploy)
# cannot fail on an existing Release or duplicate the zip.
if gh release view "$tag" >/dev/null 2>&1; then
gh release upload "$tag" "${{ steps.zip.outputs.name }}.zip" --clobber
else
gh release create "$tag" \
--title "archied v$version" \
--notes-file "$notes" \
"${{ steps.zip.outputs.name }}.zip"
fi
echo "published $tag with ${{ steps.zip.outputs.name }}.zip"
api="https://git.catlow.cloud/api/v1"
repo="sam/archie"
auth="Authorization: token $DEPLOY_TOKEN"
# Idempotent: a re-run replaces the release on the tag.
curl -sf -X DELETE -H "$auth" "$api/repos/$repo/releases/tags/$tag" >/dev/null || true
curl -sf -X POST -H "$auth" -H "Content-Type: application/json" \
-d "$(jq -n --arg tag "$tag" --arg name "Archie v$version" --arg body "$(cat "$notes")" \
'{tag_name: $tag, name: $name, body: $body, draft: false, prerelease: false}')" \
"$api/repos/$repo/releases" >/dev/null
echo "published release notes for $tag"
# The canary host follows the `next` channel. canary.yml then judges the
# release installed on the canary and decides whether it is promoted to
# stable or the canary is rolled back. The start is queue-safe: a release
# published while the canary still judges a newer one is queued behind
# it and picked up by the next check, so the running window isn't
# restarted under a different release.
- name: Install the release on the canary
if: vars.CANARY_URL != ''
env:
ARCHIE_CANARY_TOKEN: ${{ secrets.CANARY_TOKEN }}
run: ./dist/archied release canary start -dashboard "${{ vars.CANARY_URL }}" -version "${{ steps.version.outputs.version }}"
# A Gitea package belongs to its owner, not a repository, so the ones this
# workflow publishes are linked here. Linking is per package and a no-op
# once done, so an already linked package is not an error.
- name: Link the packages to this repository
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: |
for name in archied archie-agent archie; do
curl -sS -o /dev/null -X POST -H "Authorization: token $DEPLOY_TOKEN" \
"https://git.catlow.cloud/api/v1/packages/sam/container/$name/-/link/archie" || true
done
-48
View File
@@ -1,48 +0,0 @@
name: docs
# Verification only. Deployment happens from the Ansible control node
# (vectislabs.automation docs_site role against nebula), so there is nothing
# for CI to publish. What CI is for here is catching a docs change that will
# not build before it reaches a deploy.
on:
push:
branches: [main]
paths:
- "docs/**"
- "mkdocs.yml"
- ".github/workflows/docs.yml"
pull_request:
paths:
- "docs/**"
- "mkdocs.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
# No `cache: pip` here: this repository is Go and has no
# requirements.txt or pyproject.toml for setup-python to hash. Asking for
# a pip cache makes the step fail outright with "No file ... matched to
# [**/requirements.txt or **/pyproject.toml]", so every docs-touching PR
# failed before `mkdocs build --strict` ever ran -- which also meant the
# strict link/config check silently stopped guarding anything.
- uses: actions/setup-python@v6
with:
python-version: "3.13"
- run: pip install mkdocs-material
# --strict fails on a broken internal link or an unknown config key. A
# docs site that silently ships dead links is worse than one that refuses
# to ship.
- run: mkdocs build --strict
+55
View File
@@ -0,0 +1,55 @@
# Promotes the release the canary is running right now, without waiting out
# the judging window: the canary's signals must show no hard failure and no
# relative breach, otherwise the run refuses and fails. Dispatch it with the
# version the canary runs (`archied release canary status` shows it).
name: promote
on:
workflow_dispatch:
inputs:
version:
description: "release the canary is expected to run; must match what it runs"
required: true
type: string
concurrency:
group: promote
cancel-in-progress: true
permissions:
contents: read
packages: write
jobs:
promote:
if: vars.CANARY_URL != ''
runs-on: self-hosted
steps:
- name: Checkout
uses: actions/checkout@v4
with:
ref: main
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version-file: go.mod
# The self-hosted runner keeps the Go caches on disk between jobs, and
# archiving them for the Actions cache takes minutes.
cache: false
- name: Build archied
# The promote never serves the dashboard, so the build leaves it out.
run: go build -tags no_ui -o "$RUNNER_TEMP/archied" ./cmd/archied
# Promotion retags stable and the images' latest in the registry.
- name: Log in to the Gitea registry
run: echo "${{ secrets.DEPLOY_TOKEN }}" | docker login git.catlow.cloud -u "${{ github.actor }}" --password-stdin
- name: Promote the canary's release
env:
ARCHIE_CANARY_TOKEN: ${{ secrets.CANARY_TOKEN }}
run: |
"$RUNNER_TEMP/archied" release canary promote -dashboard "${{ vars.CANARY_URL }}" \
-version "${{ inputs.version }}" \
-latest git.catlow.cloud/sam/archied,git.catlow.cloud/sam/archie-agent
+13 -7
View File
@@ -14,30 +14,36 @@ concurrency:
jobs:
check:
runs-on: ubuntu-latest
runs-on: archie-quality
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# ripgrep and the unprivileged-userns sysctl are provisioned on the host.
# A self-hosted runner should not need sudo, and installing a package on
# every run is not the gate's job.
- name: Verify unprivileged user namespaces
run: unshare --user --map-root-user --net true
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- uses: pnpm/action-setup@v4
with:
package_json_file: ui/package.json
- uses: actions/setup-node@v4
with:
node-version: "24"
cache: npm
cache-dependency-path: ui/package-lock.json
- name: Install quality tools
run: |
go install github.com/go-task/task/v3/cmd/task@v3.48.0
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(cat .golangci-version)
go install mvdan.cc/gofumpt@v0.11.0
bash tools/proto.sh install
sudo apt-get update
sudo apt-get install -y --no-install-recommends ripgrep
- name: Ensure contract baseline ref
run: |
@@ -47,5 +53,5 @@ jobs:
- name: Run definitive gate
run: |
task check
task --concurrency 1 check
git diff --exit-code
+65
View File
@@ -0,0 +1,65 @@
# Cuts a release from main: [Unreleased] in CHANGELOG.md becomes the version's
# section, then the commit and its tag are pushed together. The tag push starts
# deploy.yml, which publishes the release to `next` for the canary.
name: release
on:
workflow_dispatch:
inputs:
release:
description: "major, minor, patch, or an exact version such as 1.57.0"
required: true
default: minor
concurrency:
group: release
permissions:
contents: write
jobs:
cut:
runs-on: self-hosted
steps:
# A mirror carries its own Actions secrets. An empty token checks out
# fine and fails at the push instead, which reads as a broken release.
- name: Check DEPLOY_TOKEN is configured
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: |
if [ -z "$DEPLOY_TOKEN" ]; then
echo "::error::DEPLOY_TOKEN is not set for this repository, so the release cannot push its commit and tag. Set the secret here, or dispatch the release from the Gitea primary."
exit 1
fi
# DEPLOY_TOKEN rather than the job token: a push made with the job token
# doesn't start workflows, and the tag push must start deploy.yml.
- name: Checkout
uses: actions/checkout@v4
with:
ref: main
fetch-depth: 0
token: ${{ secrets.DEPLOY_TOKEN }}
- name: Set up Go
uses: actions/setup-go@v5
with:
go-version-file: go.mod
# The self-hosted runner keeps the Go caches on disk between jobs, and
# archiving them for the Actions cache takes minutes.
cache: false
- name: Install Task
run: go install github.com/go-task/task/v3/cmd/task@v3.48.0
- name: Cut the release
env:
RELEASE: ${{ inputs.release }}
run: |
git config user.name "Sam Catlow"
git config user.email "sam@catlow.tech"
task release RELEASE="$RELEASE"
# Atomic: a commit without its tag would build images stamped dev.
- name: Push the release
run: git push --atomic origin main "$(git describe --exact-match --match 'v*' HEAD)"
+5 -13
View File
@@ -7,7 +7,6 @@
.env
task.json
.hermes-carina/
config.production.toml
.gotmp/
@@ -26,22 +25,14 @@ config.production.toml
/ui/node_modules/
/ui/.vite/
/ui/*.tsbuildinfo
# ui/dist IS committed: the Go build must not need a Node toolchain.
/ui/dist/
# air live-reload
/.air/
/tmp/
# Beads / Dolt files (added by bd init)
.dolt/
.beads-credential-key
.beads/proxieddb/
*.gate.lock*
# Impeccable design-tool scratch/critique snapshots (usable by $impeccable polish, never committed)
.impeccable/
.serena/
.beads/issues.jsonl
.beads/interactions.jsonl
.mcp.json
# gh CLI state (~/.local/state/gh) mistakenly created inside the tree
@@ -49,10 +40,11 @@ config.production.toml
__pycache__/
*.pyc
# MkDocs build output (task docs:site)
/site/
# Locally-trusted development certificates (mkcert and friends). The private
# key is generated per machine and must never be committed.
*.pem
*.key
# Local symlink to the archipelago marketplace repo
/archipelago
.agents-run/
+1
View File
@@ -0,0 +1 @@
v2.14.0
+30 -6
View File
@@ -29,6 +29,7 @@ linters:
- nestif
# Architecture
- depguard
- importas
- interfacebloat
@@ -61,6 +62,34 @@ linters:
- usetesting
settings:
# Each service links only its own composition: services reach each other
# through their gRPC contracts, never another service's packages.
depguard:
rules:
gateway-service:
files: ["**/internal/app/archiegateway/**"]
deny:
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "the web UI is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "reach the State Store through its contract"}
state-store-service:
files: ["**/internal/app/statestore/**"]
deny:
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "the web UI is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/gateway", desc: "the Gateway is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "the Gateway is another service"}
- {pkg: "github.com/nats-io", desc: "the State Store serves gRPC only"}
shared:
files: ["**/internal/app/servicekit/**", "**/internal/app/chattask/**"]
deny:
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "shared code must not pull in a service"}
cyclop:
max-complexity: 15
dupl:
@@ -91,6 +120,7 @@ linters:
sloglint:
no-mixed-args: true
key-naming-case: snake
context: scope
exclusions:
generated: lax
@@ -142,12 +172,6 @@ formatters:
custom-order: true
exclusions:
generated: strict
# These Yaegi programs sit behind //go:build ignore, so a formatter cannot
# type-check them: rewriting their imports deletes the genuinely used
# internal/secret import and the interpreter can no longer load them.
# Excluded from every formatter so adding one cannot reintroduce that.
paths:
- ^examples/secret-engines/(age|sops|vault)\.go$
issues:
# 0 = report everything. The defaults (50 per linter, 3 per message)
+4
View File
@@ -0,0 +1,4 @@
# Generated output: only its generator writes it, and the gate byte-checks it.
docs/data/generated/
internal/contracts/
ui/dist/
+928
View File
@@ -5,6 +5,934 @@ release's per-component sections are labelled beneath its heading.
## [Unreleased]
## [1.61.2] - 2026-11-07
### archied
- archied no longer gets killed by the systemd watchdog when a restart or update leaves many tasks to resume. Each resumed task used to cost a full queue poll before the next was picked up, so a dozen of them outlasted the 30-second watchdog; an update that hit this was rolled back.
## [1.61.1] - 2026-11-07
### archie-gateway
- An image or voice attachment that arrives as a link is now checked against what the link serves, the same as an uploaded one. A link whose content is not the declared type, or that cannot be read, is refused.
### archie-ui
- A workflow created on the canvas now saves the agent it runs as, so it runs instead of parking with "declares no identity to run as".
### archie-state-store
- A workflow that no longer validates after an upgrade (for example it names a step type that was removed) is repaired at startup instead of breaking every workflow. A shipped workflow is restored from this release's copy; a workflow you created is removed and logged, and its earlier revision stays in the resource history. Valid workflows you created or edited are kept.
## [1.61.0] - 2026-11-07
### archied
- A `workflow.handoff` now finishes its run and starts a separate, linked run of the next workflow on the same issue, instead of continuing as another attempt. The task page links each run to the one before and after it; attempts count only retries of one run.
- A task no longer fails to prepare its worktree with "some refs were not updated" after a tag or branch moves on the forge.
### archie-ui
- The task page no longer flashes its loading state on every live update while a task runs.
### archie-state-store
- The extension catalogue lists and installs again. Its default signing key has changed; an instance that set its own catalogue signing key in Extension settings keeps using that key.
## [1.60.0] - 2026-11-02
### archied
- Curators can list a repository's open issues and file new ones with the `issue_list` and `issue_create` tools, which reach the forge through the daemon. A curator files only when its definition declares `issue_create`; the shipped self-intake example runs in dry run with `issue_list` for deduplication. Listing every open issue needs the forge extensions from the archipelago release after 1.2.0.
## [1.59.0] - 2026-11-02
### archied
- Forge extensions can open issues: the forge surface gains `CreateIssue` alongside list, comment and close, and the bundled Gitea and GitHub extensions implement it.
## [1.58.1] - 2026-11-01
### archied
- The systemd watchdog now also watches the task intake loop, and its warning names the loop that stalled.
- archied no longer restarts about a minute after it starts. Under systemd, the watchdog never saw a poll pass and killed it on every start since 1.56.0.
## [1.58.0] - 2026-11-01
### archied
- Running `install.sh` over an install whose services are already running now restarts them, so they run the new binaries.
## [1.57.0] - 2026-10-31
### archied
- A release reaches `stable` only after it has run on a canary for a day and passed: `archied release publish` now publishes to `next` alone, `archied release canary start|check` installs a release on a canary and judges it from the canary's dashboard, promoting it or rolling the canary back, and `archied release promote` moves `stable` by hand. Promotion refuses a prerelease and a release older than the one `stable` names. The `archied` and `archie-agent` images are published as `:v<version>`, and `:latest` moves only when a release is promoted.
## [1.56.0] - 2026-10-31
### archied
- **Install once by hand.** Releases are now signed and published to `git.catlow.cloud/sam/archie`. A host on 1.55.0 or earlier still looks for releases on GitHub, so it finds this one only by running the new installer once: `curl -fsSL https://offloaded.dev/install.sh | bash`. Updates after that come from Settings → Status as before.
- Releases are signed. Updates and `install.sh` refuse a release the release key did not sign, a zip that is not the one signed, and a channel moved back to an older release. Where releases and the extension catalogue come from is a setting (update settings and extension settings, or `[distribution]` in `config.toml` for a new instance), and `archied release keygen` and `archied release publish` publish signed releases to your own registry.
- Organisations: forge connections, schedules, alerts, chat channels and audit are per organisation. A member acts in the organisation they select, the setup checklist follows it, and the instance's own forge is its root connection.
- Workflows are edited as a draft and reach the running workflow only when published. Build a workflow with Archie from the canvas: chat writes the draft into the editor for review, and the editor locks while it does.
- Schedules run from the State Store with run history, fire into their own organisation, and can trigger workflows. Daemon maintenance runs as built-in schedules.
- A parked task links to the page that fixes its blocker (repository, credential, model or forge extension), and a parked task can be retried on the current workflow definition.
- Shipped workflows run as a seeded agent identity with narrow grants instead of the root identity. Credential services are granted to dashboard identities from pickers, and personal API tokens have a name, a lifetime and a last-used time.
- An org-scoped audit page with filters, a live tail, export and a retention setting; recorded access denials are kept for a set time and listed on their own page.
- Instructions replace SOUL: instance, organisation, workflow and repository instructions are layered into every agent stage.
- Chat docks at the bottom of every page and stays open across navigation. Tool calls show where they happened in a reply, with arguments (secrets masked) and durations, and `ask_questions` asks several questions at once.
- Run more than one instance side by side: `ARCHIE_INSTANCE` names an instance, and the installer installs and updates a named one.
- Pull request reviews submit REQUEST_CHANGES on blocking findings, list findings outside the diff in the review body, and repost without inline comments when the forge refuses their placement.
- A workflow installs a repository's declared tooling before its gate, and tasks clone from a shared per-repository mirror.
- Traces: services, model and tool calls and task containers export OpenTelemetry spans, and log lines carry the trace id.
- Telegram runs as an archipelago channel extension, enabled from the Extensions page.
- The Extensions page groups the marketplace by surface, is searchable, shows install state, and offers an update only when the catalogue has one.
- The dashboard is rebuilt on shared components: a new Archie mark, a theme that follows the OS, task logs as a table, and layouts that fit a phone.
### archie-agent
- Released with archied 1.56.0; task containers export trace spans and install a repository's declared tooling before its gate.
## [1.55.0] - 2026-10-16
### archied
- Personas are gone: the Personas settings page, the chat Personality selector and `/personality`. A selected persona never changed what the model was told; SOUL (Settings → SOUL) is the one place to set Archie's identity and style. Stored persona settings are deleted on upgrade.
- The shipped SOUL describes Archie as the assistant for an event-driven automation system rather than a coding assistant. A SOUL you have saved is kept as it is.
## [1.54.3] - 2026-10-16
### archied
- Chat can help write a workflow: it reads your workflows and the step catalog, writes a definition, and checks it the same way saving does, fixing what the check reports. It does not save; paste the YAML it gives you into the editor's YAML view and save there.
## [1.54.2] - 2026-10-16
### archied
- Tool calls from Gemini models (Interactions API) receive their arguments intact. Any tool that takes arguments, such as `dashboard_navigate` in chat, failed with "invalid character '{' after top-level value".
### archie-agent
- Agent steps on Gemini models (Interactions API) pass tools their arguments intact instead of failing to decode them.
## [1.54.1] - 2026-10-16
### archied
- Update checks, `archied update install` and `install.sh` find releases at `github.com/samcharles93/archie-releases`, so a host can update again. A host on 1.54.0 or earlier still looks in the old place and has to be upgraded to 1.54.1 by hand once.
## [1.54.0] - 2026-10-16
**Upgrade note:** services now authenticate each other with TLS certificates from your own CA instead of shared tokens. Before upgrading a host whose services listen on anything but loopback (any host running agent containers), issue a certificate per service (`archied`, `archie-gateway`, `archie-messaging`, `archie-state-store`, `archie-ui`, each with its name as the DNS SAN and both server and client auth), add `[tls] ca_file` and `cert_dir` to `config.toml`, and remove every `target_token`, the `*_TOKEN` service variables and the `--token`/`--*-token` flags, including archie-ui's `-token` and `-token-file`. A unit that still passes a removed flag fails to start. See `config.example.toml`.
### archied
- Services authenticate each other with mutual TLS. Each process presents `<cert_dir>/<service>.pem`, peers must chain to `ca_file`, and a caller is identified by its certificate rather than by what it claims. Renewed certificates are picked up without a restart. Without `[tls]`, services listen on and dial loopback only. The harness setup terminal requires `[tls]`.
- Every gRPC service caps the streams a connection holds, times out stalled handshakes, releases a dead client's streams, and drains for at most 10 seconds on shutdown. Messaging exits when its listener fails instead of staying up without delivering.
- The dashboard has user accounts. First run opens browser setup for the organisation, workspace and first administrator; people then sign in with a password, a passkey or your identity provider, and account administration lives under Access. The shared dashboard token is gone; reach the dashboard remotely through an HTTPS reverse proxy.
- `archied update install` updates a host in one transaction: it verifies the release, stages every binary, pulls the agent image by digest and backs up the database, then restarts the services in order and rolls everything back if archied is not healthy for two minutes.
- Each workflow runs as the identity it declares, checked on every attempt along with the identity that started it. A workflow that declares none is refused, a called workflow runs as its caller's declared identity, and shipped workflows run as the instance root.
- Test-run a workflow draft before saving it, with forge and push writes suppressed and recorded per step. The History tab lists a workflow's revisions, diffs them as YAML and on the canvas, restores one into the editor, and shows which revision each run used.
- Start a task from the dashboard. The dashboard home shows activity and setup, and a running task has a read-only Sandbox tab that follows its container.
- The topbar's Jump to is a command palette, settings lists open as accordions that wait for a new item to be saved, and history restores land as a draft applied from the save bar.
- Labels, hints, alerts and empty states say what is wrong and what to do, without tutorial or marketing prose.
- Org isolation is tighter: harness secrets, identity writes, principals, playbook dispatch and model selections in chat stay in the caller's org, instance settings are written by the system org only, and creating a source or reloading a channel is authorized against the target.
- Binding dispatch claims its capture and enqueues the task atomically, so a capture cannot start two runs, and the run-time workflow check sees the binding event's signature and address.
- Service-unhealthy alerts count their grace from the last report and also cover a service that went silent, and a restart no longer clears an alert still inside its grace. An invalid stored access policy raises an alert until it validates.
- A failed cancel of a called workflow no longer leaves the caller running, retention spares captures still waiting to be dispatched, and EDA playbooks load and report at start instead of on first dispatch.
- Chat model selection works again for provider models.
### archie-agent
- Each run acts as its workflow's declared identity.
- A task snapshot carries only the model limits its aliases resolve to.
- A build step's "no changes" result comes from its writable stages and clears once a commit lands.
- Test runs suppress forge and push writes and record what they would have done.
- The default persona is a reporting-focused identity prompt, without the one-question limit in chat.
## [1.53.0] - 2026-10-11
### archied
- Every organisation's data is its own. Chats, tasks, events, transitions, steps, tool calls, run statistics, event sources, event types, mappings, bindings and agent memory are read and written in the org that owns them, and a request can no longer write into another org. Rows written before orgs existed move to their owner's org on upgrade.
- An instance admin decides what each org may reach: the models it can use, and whether it may register providers under its own credentials. Org Settings gains a Models tab and instance Models gains Org access. The system org is never restricted; another org uses nothing until it is granted.
- Models are addressed by alias. Aliases replace model roles, one resolver serves every purpose (agent steps, implement, PR review, MCP sampling, chat, embedding, transcription), and an unknown alias fails instead of falling back to a default. The step editor and the chat picker offer aliases, and a workflow naming one that does not exist is refused when saved.
- Chat sessions belong to one org; a chat resolves its models in the caller's org and is billed to it, and a task run from chat posts its outcome back to that chat.
- Add a member by provider subject, or by email as a placeholder that the first sign-in the provider vouches for claims.
- The workflow canvas authors parallel branches as lanes, adds a switch step that runs the case matching a reference, and edits a call's interface. A step shows its role, its number and its run trace.
- The workflows list shows each workflow's running count and latest run result, the canvas reveals its data-edge handles on hover, and restoring a version asks for confirmation.
- Store packages can auto-update: a package given the policy is moved to the catalogue's newest digest by a State Store ticker. An update asking for more authority than was accepted waits as a pending update with the running version untouched; approving it accepts the new authority, and a rollback restores the previous version with the authority accepted against it.
- Model provider keys never enter an agent container: the runtime reaches its providers through the egress proxy, which holds the keys. A task's own credential can no longer replace the workflow definition its run is pinned to, and a package workflow's triggers, tools and forge calls are bounded by the authority accepted for the package.
- The dashboard warns when it is reachable from off-host over plain HTTP, and the wildcard listen address counts as off-host rather than loopback. Instance health, logs, config and identities, the setup checklist and the skill catalogue are system-org only, and API requests are refused until the access chain has loaded.
- `/approve` reaches Telegram; the router served it but nothing published it.
- A worktree a killed container left root-owned is taken back by the daemon, and a PR review's benchmark runner works again on configured models and public PRs.
- An unserved `/api` path returns 404 instead of the dashboard page, and an input group's select no longer loses clicks to its addon.
### archie-agent
- The runtime reaches model providers through the egress proxy, so provider keys stay out of the container.
- Agent steps resolve model aliases and their own org's models and credentials, failing on an unknown alias instead of falling back.
- A switch step runs the case matching its reference.
- A call waiting on another step is reconciled from durable steps, so it resumes after a daemon restart rather than stranding.
## [1.52.0] - 2026-10-09
### archied
- The harness page's setup terminal opens a real session: it starts an ephemeral container from a Kit profile, runs the CLI's own login and captures the OAuth tokens at the provider's token endpoint. Point the dashboard at the daemon with `[services.harness].target` and a `HARNESS_TOKEN` and it stops answering 503; the terminal is created at your browser's size. Takeover of a live task is not in this release.
- A credential's token endpoint is refused when the run is not granted that service, instead of proxy-ing the provider's real tokens into the container.
- Settings → Profiles, Credential bindings and Playbooks are editable from the dashboard, and curator definitions can be changed and applied without a restart.
- Settings say whether each one applies live or needs a restart, show what is consuming resources, and report whether an apply landed.
- Status shows each service's dependency checks, the agent workers and the broker.
- The Logs page reads recent logs from every service, not just the daemon.
- Captures and webhook sources are scoped to the org that owns them: the list, retention and delivery authorization all act in the right org, and a workflow definition resolves in its own org.
- Chat settings are attributed to the signed-in user, and Settings → Tokens explains when a personal token cannot be created.
- A channel enabled after Archie started works immediately; a channel that fails on its own recovers; a failed channel is no longer reported as enabled, and stored channel settings no longer save duplicate or unnormalized values.
- The task table sorts, the command palette no longer scrolls sideways or loses its highlight, unknown routes render a not-found page, and configuration reload failures are shown instead of passing silently.
- A scheduled job whose payload names a dangerous command is refused.
- A disabled model provider is never served from the ambient API key.
- `generate_video` is backed by ai-sdk's MiniMax video provider.
- A dashboard token is no longer written to the startup log.
### archie-agent
- `workflow.call`: a call is keyed on its declared step path, its key is freed once the callee reaches a terminal state, and a caller waiting on a callee releases its capacity instead of holding it.
- `command.run` honours step retry and `on_failure`.
- A value passed between steps keeps its declared type, and optional result booleans are enforced only when the workflow declares them.
- Capture tools have their results checked against the declared schema.
- A single-cycle run waits for its in-flight tasks before exiting, and identity tasks inherit live settings.
- Kit containers run Docker's init as PID 1, so orphaned processes are reaped instead of accumulating inside a long task.
## [1.51.1] - 2026-10-08
### archied
- Chat with OpenAI's gpt-6 models (gpt-6-luna and the rest) works with tools; a turn failed with "Function tools with reasoning_effort are not supported".
## [1.51.0] - 2026-10-08
### archied
- A secret engine enabled after Archie started (Bitwarden, for example) now supplies its keys straight away; providers that depended on it no longer stay disabled until a restart.
- The dashboard chat has a microphone button: record a voice message and it is transcribed like a Telegram voice note. It shows only when a `transcription` model role is set under Settings → Models.
- A file Archie sends in the dashboard chat is a download link for an hour, instead of a note that it can't be delivered.
- Typing `/model` or `/personality` on its own in the dashboard chat offers the choices as buttons.
## [1.50.1] - 2026-10-08
### archied
- When an update is rolled back, the log names the health check that failed instead of only "unhealthy".
## [1.50.0] - 2026-10-08
### archied
- Tools that need your approval ask for it again, and Archie can ask you a question or offer choices mid-reply. Since the services were split these never reached Telegram or the dashboard: approval-gated tools failed and questions were never asked.
- The dashboard chat shows approvals as Approve / Always this session / Deny, choices as buttons, and questions with a reply field.
- `/update` in the dashboard chat lists what's available with Install and Not now.
- Settings → Status → Versions installs the update it shows; its Install button sent an empty request.
## [1.49.4] - 2026-10-07
### archied
- Settings → Status and Settings → Extensions are split into tabs instead of one long page; the Versions table's status column ends at the card's edge.
- Tools & MCP has one "Add MCP server" button; the transport is chosen in the form, and an unnamed new server is not an unsaved change.
- Settings → Repositories shows the add field when no repositories are configured, instead of a blank page.
- The unsaved-changes bar always rests at the bottom of the window.
## [1.49.3] - 2026-10-07
### archied
- Settings → Status → Versions shows the Gateway as "Update available" with an Install button when a newer release exists; it read "Unknown" with no way to install. The Runtime row stays "Unknown" until an agent task has run.
- The release channel buttons sit at the Updates card's right edge instead of mid-row.
## [1.49.2] - 2026-10-07
### archied
- Carries the 1.49.0 and 1.49.1 changes, whose builds were never published. The update check reads GitHub releases directly and still offers only releases with a verifiable linux-amd64 zip.
## [1.49.1] - 2026-10-07
### archied
- When the dashboard session expires, the page returns to the sign-in screen instead of showing errors on every page until a manual refresh.
## [1.49.0] - 2026-10-07
### archied
- Extensions that declare no egress hosts (vault, email, gitea) reach the network again; only packages that declare their hosts are confined to them. The Accept dialog shows "network: unrestricted" for the rest.
- The update check finds releases itself, and reuses a found release for ten minutes so repeated checks stay under GitHub's rate limit.
## [1.48.1] - 2026-10-07
### archied
- **Settings → Status → Updates** now chooses only the release channel (stable, prereleases, or a pinned version). Update checks and installs always run the `archie-update-*` scripts installed beside the binaries; the dashboard can no longer set the command that runs.
## [1.48.0] - 2026-10-07
### archied
- **Settings → Status → Updates** edits the update check and install commands. They default to the `archie-update-*` scripts installed beside the binaries, so a zip install shows **Install** on the Versions card with nothing configured. The `update_check_command` and `update_install_command` keys under `[chat.telegram]` are no longer read; remove them from `config.toml`.
- `archie-update-install` run from a shell now reads `~/.config/archie/env`, so the pre-update backup of the bundled database no longer fails with `no password supplied`. Run it with `--auto` to install the newest release.
## [1.47.3] - 2026-10-07
### archied
- **Settings → Extensions**: **Accept** in the authority review now accepts the extension, and **Remove** removes it. Both previously closed the dialog without doing anything.
## [1.47.2] - 2026-10-06
### archied
- **Events → Inspector** now lists your capture sources with their real URLs and a **New source** button, replacing the `/webhooks/capture/<source>` placeholder. Sources no longer sit on the Bindings tab.
## [1.47.1] - 2026-10-06
### archied
- The bundled PostgreSQL has no network and publishes no port: the services reach it through its Unix socket under `~/.local/share/archie/postgres`, so it no longer collides with another PostgreSQL on 5432. Leaving the database question blank in `archied setup` selects it.
- The installer does not start the services when the bundled PostgreSQL fails to start; it names the command to read its logs.
- On hosts that restrict unprivileged user namespaces (Ubuntu 23.10+), the installer prints an AppArmor profile allowing them for the Archie binaries only.
## [1.47.0] - 2026-10-06
### archied
- Install with one command: `curl -fsSL https://raw.githubusercontent.com/samcharles93/archie-core/main/install.sh | bash` downloads this release, verifies its checksum and runs `archied setup`. `--from-source` builds a checkout instead.
- `archied setup` asks for the PostgreSQL URL. Left blank, it uses the bundled Compose database with a generated password stored in `~/.config/archie/env` as `PGPASSWORD`, not in `config.toml`.
- The bundled PostgreSQL listens on 127.0.0.1 only. A database created before this release keeps its old `archie` password; enter its URL at setup or recreate the volume.
- The release zip carries `docker-compose.yml`.
- Extensions need unprivileged user namespaces, which Ubuntu 23.10 and later restrict. Allow them for the Archie binaries with an AppArmor profile; from the next release the installer prints it. Do not disable the restriction system-wide.
- fix(app): assign the temp-file close result on the error path
- fix(webhook): set a ReadHeaderTimeout on the forge webhook receivers
- fix(forge): refuse a review line number that does not fit an int
- fix(storepkg): mask the tar mode to the permission bits before narrowing
- fix(webui): navigate the Events chain once, not twice
- feat(tools): fail the gate when docs cite a path that no longer exists
- fix(webhookguard): verify uppercase-hex HMAC signatures
- fix(configuration): make bot_user required, defaulted, and named
- feat(workflow): add the command.run step type
- fix(controlplane): an absent MCP server field inherits the file value
- fix(build): restore the go fix fixpoint, and give the formatter one owner
- fix(archied): restore contextcheck directives and drop unused adapter
- feat(secretengine): serve secret engines as go-plugin extensions
- refactor(statestore): own package for the State Store service; access reset moves to archie-state-store
- refactor(archied): gateway owns model work; daemon drops chat runtime, tools, memory and curators
- refactor(archiegateway): own package for the Gateway service
- fix(services): services wait for peers instead of exiting; restarted broker keeps its endpoint
- refactor(archieplaybooks): fold archie-playbooks into archied playbooks lint|serve
- refactor(agentrun): agent stage contract moves to the domain layer
- refactor(agentexec): model loop moves to agentexec/modelloop
- fix(configuration): bindings encryption keys must use the env engine
- feat(storepkg): fetch packages from any registry, plain HTTP on loopback only
- feat(webui): install, accept and enable extensions from the dashboard
- feat(presence): every service re-stamps a presence record in the State Store
- refactor(plugin): delete Yaegi daemon plugins and plugin_dir
- refactor(module): the log action is built in; delete the module loader and reconciler
- refactor(skill): delete Yaegi skill scripts and the run_go_script tool
- refactor(examples): the firewall workflow moves to archipelago
- feat(presence): services card on the status page and archied status
- feat(archiemessaging): verify update reports against archied's presence and restore release announcements
- fix(configuration): an overlay stands in for a missing config file; dev overlay is complete
- feat(access): edit org, workspace and object policies from the dashboard; refuse owner lockout
- feat(access): instance network rules at the capture receiver; policies reload without a restart
- feat(staterpc): attribute State Store calls to the calling service; policy audit records it
- feat(controlplane): playbooks and agent profiles install from packages; the daemon reads eda-playbooks live
- feat(forgeext): forge surface served by extensions; forge.type names the installed package
- refactor(forge): github and gitea leave core; webhooks parse in the forge extension
- feat(staterpc): the State Store derives org and actor from the principal archie-ui forwards
- feat(channelext): chat channels served by extensions; messaging runs the enabled ones
- refactor(channels): webhook and email run only as extensions; their channel settings go
- feat(skills): skill packages project into a skills resource the gateway reads live
- fix(gatewayrpc): sender_id and rate_limited cross the chat wire
- fix(controlplane): change history names kinds and reads only the caller's org
- feat(contracts)!: requests no longer name their org; the State Store derives it from the caller
- feat(identity): personal API tokens, created and revoked from the dashboard, act as their owner
- fix(archieui): a sign-in provider outage is a health issue, not a startup failure
- feat(staterpc): one run credential per task, kept in the State Store, authorizes its store calls and its push
- fix(forgerpc): forge calls need the run credential and reach only the run's own repository
- feat(controlplane): identity credential grants edited from the dashboard and applied live
- feat(daemon): a workflow that names an identity runs as it; the dispatcher needs run on the workflow
- feat(staterpc): every run start is audited by the State Store, or the run credential is withdrawn
- refactor(forgerpc): identity RPC subjects are keyed by identity ID
- fix(nats): containers log in with their run credential and reach only their task's subjects
- feat(egress): the run credential is the proxy login; Kit secrets resolve per request from live grants
- fix(webui): bind the container runtime document's keys, drop the blank Advanced page
- fix(webui): drop the repository review switch the server no longer accepts
- feat(controlplane): serve the step vocabulary in the workflow-definitions schema; the editor checks step types against it
- fix(ui): drop the topbar nav's edge fade that clipped the first item
- refactor(workflow): delete the bootstrap smoke-test workflow and its intake kind
- feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure
- feat(workflow): repository step types; implement and tdd ship as YAML in general steps
- feat(workflow): when conditions, handoff, human approval and forge steps; feasibility and triage ship as YAML
- feat(workflow): retries, parallel branches, review steps; every shipped workflow is YAML and the per-workflow step types are gone
- feat(ui): workflow canvas renders each definition as a step graph with data edges, parallel branches and conditions
- feat(ui): the workflow canvas watches a run live: each step shows its state, duration and error, and the view follows the step in progress
- feat(controlplane): serve each step type's settings schema; the workflow editor checks settings before save
- feat(ui): build workflows on the canvas: step palette, schema-driven settings forms, references to earlier results, reorder and remove
- feat(ui): the canvas Start node lists what starts the workflow: issue routes, event bindings, playbooks and other workflows
- feat(ui): canvas authoring by right-click menu and + insertion points; steps edit in a slide-in panel and show what they do
- fix(ui): workflow page header is one tab row with save and a more menu; drop the ID field, step list, version footer and the meaningless origin pill
- feat(ui): drive workflows from the canvas: run a workflow, act on the watched run, edit workflow settings from the Start node; the canvas fills the viewport
- feat(ui): inspect workflow step runs from canvas
- feat(workflow): resume a parked run from a chosen step
- feat(ui): bind an event to a workflow from its Start node
- fix(ui): reveal signing secret in canvas source creation
- feat(ui): select review gate findings before approval
- fix(ui): load task debug reliably and copy JSON output
- fix(postgres): queue a review that arrives during a remediation
- fix(ui): keep JSON copy inline on hover
- fix(webui): stop returning database_url from /api/config
- refactor(config): drop unused dispatch state labels
- feat(gateway): serve the dashboard skills and curators over ChatService
- refactor(archieui): leave channel reload unserved by the gateway
- feat(releaseupdate): install from release artifacts with journaled rollback, topology check and channels
- feat(gateway): load SOUL into the chat prompt per turn
- refactor(config): drop the unwired artifact sender and [artifacts] config
- feat(messaging): serve MessagingService.Deliver and deliver chat schedules through it
- refactor(gateway)!: drop budget_key with the webhook chat channel
- refactor(configuration): delete the dead runtime config overlay
- fix(daemon): record terminal non-dispatch outcomes so a capture is evaluated once
- fix(daemon): refuse a disabled workflow on every start path
- fix(workflow): validate workflow.call inside parallel branches
- fix(workflow): validate handoff and approve targets at save
- feat(taskactions): rejecting a pr_open task closes its pull request
- feat(eda): link binding dispatches to the captures and tasks they started
- feat(eda): record every terminal binding outcome and flag failing bindings
- feat(workflow): record parallel branch steps as their own steps
- feat(workflow): record steps skipped by when as skipped
- feat(webui): page and filter the task list on the server
- fix(webui): admit dashboard work requests through the State Store and honour the workflow's repository mode
- fix(ui): restoring shipped workflows keeps custom ones
- refactor(org): rename the default org to org-sys
- fix(postgres): collect inline comments on a review queued behind a running remediation
- fix(daemon): webhook forge intake does not poll for issues
- refactor(archied): drop the unreachable multi-identity webhook skip; validation refuses it
- feat(access): the dashboard operator is a person owning org-sys
- fix(workflow): refuse undeclared inputs and result fields at save
- fix(ui): offer resume only where the server accepts it
- feat(daemon): the timeline names and links the binding and capture that started a task
- feat(eda): pause and resume a binding; resuming goes back through approval
- feat(org): org, workspace and membership API
- fix(webui): the org-sys owner is the instance owner
- fix(webui): member changes need the admin grant and owner changes an owner
- feat(daemon): withdrawing an issue declines its queued or running work
- feat(workflow): later steps read a waited workflow.call's outputs as its result
- feat(workflow): record each failed attempt of a retried step
- feat(daemon): record an approving review on the task's timeline
- feat(workflow): each remediation round names its number, cap and the review it answers
- fix(ui): show step retries as archie's record, not the agent's report
- feat(webui): run details show inputs, outputs and workflow.call links both ways
- feat(webui): page through task logs
- feat(eda): name and delete capture sources; an armed binding blocks the delete
- feat(ui): edit retry backoff and needs on the canvas
- fix(controlplane): report watch outages and align live/restart kind labels
- feat(taskactions): merge pull request action from the task
- fix(daemon): withdraw only issues the same dispatch rule found eligible and then lost
- feat(org): instance admins manage every org
- feat(ui): org area with members, agents, workspaces, access and tokens
- fix(ui): trim filler prose and expose appearance in settings nav
- fix(archiegateway,agentexec,agentworker): rely on ai-sdk reasoning token selection
- feat(ui): org switcher and new org for instance admins
- fix(extension): confine each extension's network to its accepted egress hosts
- fix(captureintake): unwrap form-encoded webhook payloads
- fix(captureintake): decode any form-encoded webhook body to JSON
- fix(modelloop): feed the cached model catalog to the runtime so reasoning models get the right token parameter
- fix(webui): list services with the State Store marked down when it is unreachable
- fix(release): push the release commit and its tag atomically
- fix(eda): dispatch each webhook delivery once, however often the sender retries it
- fix(eda): name a source's delivery header in the dashboard instead of a built-in sender list
- fix(modelloop): mark reasoning models from the carried model limits, in the gateway and the agent worker
- feat(telegram): /stop stops the chat agent, else the tasks it created, or one task; delete the dead approval actions
- feat(storepkg): install packages from a signed default catalogue, listed on the Extensions page
- feat(setup): one guided flow; ask for PostgreSQL and generate the bundled database's password
- fix(setup): keep the generated database password out of config.toml
- feat(install): install from a verified release with curl | bash; ship docker-compose.yml in the release
### archie-agent
- fix(forge): refuse a review line number that does not fit an int
- fix(webhookguard): verify uppercase-hex HMAC signatures
- feat(workflow): add the command.run step type
- feat(secretengine): serve secret engines as go-plugin extensions
- refactor(statestore): own package for the State Store service; access reset moves to archie-state-store
- fix(services): services wait for peers instead of exiting; restarted broker keeps its endpoint
- refactor(agentrun): agent stage contract moves to the domain layer
- refactor(agentexec): model loop moves to agentexec/modelloop
- fix(configuration): bindings encryption keys must use the env engine
- feat(presence): every service re-stamps a presence record in the State Store
- refactor(plugin): delete Yaegi daemon plugins and plugin_dir
- refactor(module): the log action is built in; delete the module loader and reconciler
- refactor(skill): delete Yaegi skill scripts and the run_go_script tool
- feat(access): edit org, workspace and object policies from the dashboard; refuse owner lockout
- feat(access): instance network rules at the capture receiver; policies reload without a restart
- feat(staterpc): attribute State Store calls to the calling service; policy audit records it
- feat(controlplane): playbooks and agent profiles install from packages; the daemon reads eda-playbooks live
- feat(forgeext): forge surface served by extensions; forge.type names the installed package
- refactor(forge): github and gitea leave core; webhooks parse in the forge extension
- feat(staterpc): the State Store derives org and actor from the principal archie-ui forwards
- feat(channelext): chat channels served by extensions; messaging runs the enabled ones
- refactor(channels): webhook and email run only as extensions; their channel settings go
- feat(skills): skill packages project into a skills resource the gateway reads live
- fix(controlplane): change history names kinds and reads only the caller's org
- feat(contracts)!: requests no longer name their org; the State Store derives it from the caller
- feat(identity): personal API tokens, created and revoked from the dashboard, act as their owner
- fix(archieui): a sign-in provider outage is a health issue, not a startup failure
- feat(staterpc): one run credential per task, kept in the State Store, authorizes its store calls and its push
- fix(forgerpc): forge calls need the run credential and reach only the run's own repository
- feat(daemon): a workflow that names an identity runs as it; the dispatcher needs run on the workflow
- feat(staterpc): every run start is audited by the State Store, or the run credential is withdrawn
- refactor(forgerpc): identity RPC subjects are keyed by identity ID
- fix(nats): containers log in with their run credential and reach only their task's subjects
- feat(egress): the run credential is the proxy login; Kit secrets resolve per request from live grants
- feat(controlplane): serve the step vocabulary in the workflow-definitions schema; the editor checks step types against it
- refactor(workflow): delete the bootstrap smoke-test workflow and its intake kind
- feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure
- feat(workflow): repository step types; implement and tdd ship as YAML in general steps
- feat(workflow): when conditions, handoff, human approval and forge steps; feasibility and triage ship as YAML
- feat(workflow): retries, parallel branches, review steps; every shipped workflow is YAML and the per-workflow step types are gone
- feat(controlplane): serve each step type's settings schema; the workflow editor checks settings before save
- feat(ui): the canvas Start node lists what starts the workflow: issue routes, event bindings, playbooks and other workflows
- feat(ui): inspect workflow step runs from canvas
- feat(workflow): resume a parked run from a chosen step
- fix(postgres): queue a review that arrives during a remediation
- refactor(config): drop unused dispatch state labels
- refactor(config): drop the unwired artifact sender and [artifacts] config
- feat(messaging): serve MessagingService.Deliver and deliver chat schedules through it
- refactor(gateway)!: drop budget_key with the webhook chat channel
- fix(daemon): record terminal non-dispatch outcomes so a capture is evaluated once
- fix(workflow): validate workflow.call inside parallel branches
- fix(workflow): validate handoff and approve targets at save
- feat(taskactions): rejecting a pr_open task closes its pull request
- feat(eda): link binding dispatches to the captures and tasks they started
- feat(workflow): record parallel branch steps as their own steps
- feat(workflow): record steps skipped by when as skipped
- feat(webui): page and filter the task list on the server
- refactor(org): rename the default org to org-sys
- fix(postgres): collect inline comments on a review queued behind a running remediation
- feat(access): the dashboard operator is a person owning org-sys
- fix(workflow): refuse undeclared inputs and result fields at save
- feat(daemon): the timeline names and links the binding and capture that started a task
- feat(eda): pause and resume a binding; resuming goes back through approval
- feat(org): org, workspace and membership API
- feat(daemon): withdrawing an issue declines its queued or running work
- feat(workflow): later steps read a waited workflow.call's outputs as its result
- feat(workflow): record each failed attempt of a retried step
- feat(daemon): record an approving review on the task's timeline
- feat(workflow): each remediation round names its number, cap and the review it answers
- feat(webui): run details show inputs, outputs and workflow.call links both ways
- feat(webui): page through task logs
- feat(eda): name and delete capture sources; an armed binding blocks the delete
- feat(taskactions): merge pull request action from the task
- feat(org): instance admins manage every org
- fix(archiegateway,agentexec,agentworker): rely on ai-sdk reasoning token selection
- fix(extension): confine each extension's network to its accepted egress hosts
- fix(modelloop): feed the cached model catalog to the runtime so reasoning models get the right token parameter
- fix(eda): dispatch each webhook delivery once, however often the sender retries it
- fix(eda): name a source's delivery header in the dashboard instead of a built-in sender list
- fix(modelloop): mark reasoning models from the carried model limits, in the gateway and the agent worker
- feat(telegram): /stop stops the chat agent, else the tasks it created, or one task; delete the dead approval actions
- feat(storepkg): install packages from a signed default catalogue, listed on the Extensions page
## [1.46.0] - 2026-10-02
### archied
- feat(workflow): declared workflow outputs for wait:true callers
- feat(prreview): the operator-approval gate is PRReview's own stage-list entry
- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
- feat(prreview): the gate records the review it holds and posts the operator's answer
- feat(taskactions): one approval path answers the review gate from every surface
- feat(webui): the dashboard answers the review gate, including a re-review's instructions
- feat(daemon): resolve the producing identity's org before publishing work
- feat(webui): block invalid settings and show a field's former value
- fix(workflow): derive a declared output's captures need for profile selection
- fix(storepkg): validate every declared authority grant at the package descriptor
- feat(archied): refresh the model catalog at runtime
- feat(mcp): answer server-initiated sampling from the chat model
- feat(container): send registry auth on image pull
- feat(messaging): retract ephemeral replies after their TTL
- feat(messaging): transcribe Telegram voice notes
- fix(egress): take a run's credential kind from its binding, not the Kit
- feat(webui): a live-apply setting reads as applied, never as a restart
- feat(webui): the dashboard reads harness bindings and opens the setup terminal
- feat(gateway): list the harness page in the dashboard page registry
- feat(webui): the harness settings page and its setup terminal
- fix(workflow): park environment gate failures without dispatching a builder
- feat(messaging): adapter-facing clarify, picker and approval contract
- feat(gateway): gate admin slash commands by sender policy
- feat(plugins): load plugin and secret-engine files without a restart
- fix(workflow): deliver the feasibility PRD to the forge issue
- fix(messaging): report the daemon version this process was built from
- fix(messaging): carry an inbound attachment's bytes to the gateway turn
- fix(daemon): resume a retry whose worktree is gone
- fix(archied): omit the max-token bound on reasoning-class models
- fix(logging): file a task log record under its own event time
- fix(control-plane): unify validation for the domain-managed kinds
- feat(webui): let the operator choose the retry worktree mode
- feat(agent): seed a starter SOUL and upgrade only untouched templates
- feat(controlplane): add the writable review-settings resource
- fix(messaging): transcribe voice notes on the model-owning side of the boundary
- fix(messaging): gate the boundary on config reads, not only package links
- feat(messaging): restart only the channel whose settings changed
- feat(container): apply container-runtime-policies live
- feat(tools): reconcile MCP servers and tool settings live
- feat(messaging): add a per-turn interactive carrier for clarify and picker
- feat(gateway): offer ask_user when the turn's channel can carry a question
- feat(telegram): carry clarify and picker through the text fallback
- fix(webui): pin the dashboard validators to the control plane's
- refactor(agent): drop the SOUL upgrade branch with no shipped template
- feat(agentworker): answer MCP sampling from the task's model
- fix(workflow): bind the remediate worktree before the builder runs
- fix(config): carry max_retries into the worker TaskConfig snapshot
- fix(agentworker): supply the guardrail engine to every task run
### archie-agent
- feat(workflow): declared workflow outputs for wait:true callers
- feat(prreview): the operator-approval gate is PRReview's own stage-list entry
- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
- feat(prreview): the gate records the review it holds and posts the operator's answer
- feat(taskactions): one approval path answers the review gate from every surface
- fix(workflow): derive a declared output's captures need for profile selection
- fix(storepkg): validate every declared authority grant at the package descriptor
- feat(mcp): answer server-initiated sampling from the chat model
- feat(container): send registry auth on image pull
- feat(messaging): retract ephemeral replies after their TTL
- feat(messaging): transcribe Telegram voice notes
- fix(egress): take a run's credential kind from its binding, not the Kit
- fix(workflow): park environment gate failures without dispatching a builder
- feat(messaging): adapter-facing clarify, picker and approval contract
- feat(plugins): load plugin and secret-engine files without a restart
- fix(workflow): deliver the feasibility PRD to the forge issue
- fix(messaging): carry an inbound attachment's bytes to the gateway turn
- fix(daemon): resume a retry whose worktree is gone
- fix(logging): file a task log record under its own event time
- fix(control-plane): unify validation for the domain-managed kinds
- feat(webui): let the operator choose the retry worktree mode
- fix(messaging): transcribe voice notes on the model-owning side of the boundary
- feat(messaging): restart only the channel whose settings changed
- feat(container): apply container-runtime-policies live
- feat(tools): reconcile MCP servers and tool settings live
- feat(messaging): add a per-turn interactive carrier for clarify and picker
- feat(agentworker): answer MCP sampling from the task's model
- fix(workflow): bind the remediate worktree before the builder runs
- fix(config): carry max_retries into the worker TaskConfig snapshot
- fix(agentworker): supply the guardrail engine to every task run
## [1.45.0] - 2026-09-30
### archied
- fix(eda): reject a result map missing a field or needing a conversion
- feat(eda): per-org workflow enable/disable gating bindings
- feat(telegram): carry inbound media through the chat turn
- fix(prsource): use a CodeQL-recognised containment guard when extracting archives
- feat(store): key control-plane resources by (org, kind)
- fix(store): refuse resource keys the audit key cannot disambiguate
- fix(daemon): resume the task branch before container acquisition
- feat(webui): show attachment metadata in the session transcript
- feat(webui): name a workflow's declared inputs on the work-request form
- feat(controlplane): carry the caller org from the request principal
- fix(webui): the workflow handlers act in the caller's org
- feat(kitrun): render the OAuth credential file with sentinels
- feat(store): record accepted package authority against the pin
- fix(workflow): the own-PR flow no longer parks on the operator-approval gate
- feat(gateway): a TTL-bounded dedup gate for redelivered platform messages
- feat(egress): capture the OAuth scope set and carry it to the harness secret
- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
- feat(store): project installed package contributions into org resources
- feat(gateway): coalesce rapid-fire text events into one turn
- fix(config): expand plugin, module and skills dirs like every other operator path
- fix(webui): drop the config schema's editability advert
- feat(webui): events counts, YAML reading, log rows and dashboard filters
### archie-agent
- feat(eda): per-org workflow enable/disable gating bindings
- feat(telegram): carry inbound media through the chat turn
- fix(prsource): use a CodeQL-recognised containment guard when extracting archives
- feat(store): key control-plane resources by (org, kind)
- feat(controlplane): carry the caller org from the request principal
- feat(kitrun): render the OAuth credential file with sentinels
- feat(store): record accepted package authority against the pin
- fix(workflow): the own-PR flow no longer parks on the operator-approval gate
- feat(egress): capture the OAuth scope set and carry it to the harness secret
- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
- feat(store): project installed package contributions into org resources
## [1.44.1] - 2026-09-29
### archied
Two fixes to tasks that could not get past their workflow definition.
- **Approving a task no longer parks it again.** A task requeued under a
different workflow kept the previous run's definition pinned, so the worker
refused to compile the dispatch — it named `feasibility` while the row named
`implement` — and the task parked immediately, identically on every further
approval, which left `decline` as the only working operator action.
The daemon now re-pins whenever the pinned definition's id disagrees with the
task's workflow. A pin that is present, digest-valid and id-consistent is
still a strict no-op, so an operator's own definition override survives a
dispatch unchanged.
- **A shipped workflow definition now reaches an existing install.** A stored
seed was consulted only for a resource the store did not already hold, so a
document that changed in the build never reached a database an earlier
release had seeded. For workflow definitions that is a total outage rather
than a stale setting: the collection validates as one document, so a stored
step type this build no longer has failed every task's pin, whatever workflow
the task named — and the documented recovery, removing the resource and
restarting, wrote nothing either, because the store answered the seed's known
request ID from a history that outlives the resource. A seed now refreshes a
kind it wrote the newest revision of and re-creates a resource that is gone,
while an operator's own replacement is never undone.
### archie-agent
The runtime image is rebuilt with this release and links the shared workflow
package carrying the definition-id helper above. Hosts that run agent
containers need `docker compose pull agent` after updating to pick it up.
## [1.44.0] - 2026-09-29
### archied
Archie can now review pull requests.
- **Reviews on request and by watch.** Ask in chat or on the dashboard work form, add a repository to the watch list, or just let archie review its own PRs before it opens them. Review intensity follows a depth dial (quick/standard/deep) classified from the size of the change, and every finished review passes a verification layer — coverage-gap and cross-finding consistency checks — before it is produced.
- **No forge credential reaches the review sandbox.** The daemon prefetches the pull request's data and rebuilds its source snapshot over the forge's HTTP API, so the agent container works from an isolated copy with no read access to the repository's credentials.
- **Reviews stop at the operator gate before posting.** `review.precision_gate` / `approve_before_post` decide whether a finished review posts itself or parks for operator approval. With this release the parked state is a stop sign, not a checkpoint: the approve/reject/re-review responses behind the gate are not wired yet, and the gate's settings are not yet editable in the dashboard (configure them in `config.toml`). A parked review sits until that follow-up lands.
- The adversarial self-review pass archie previously ran before opening its own PRs is superseded by this pipeline and has been removed.
- Hardened harness input handling: harness identifiers are bounded to integer types.
### archie-agent
The runtime image is rebuilt with this release; it links the shared pr-review workflow packages behind the reviews above. Hosts that run agent containers need `docker compose pull agent` after updating to pick it up.
## [1.43.0] - 2026-09-28
### archied
- **Organisations.** Tasks, identities and settings now belong to an org. An
existing install is upgraded into a default org when the State Store first
starts; the upgrade resumes if interrupted. Task de-duplication is scoped
per org and identity.
- **Access policies are enforced** at the dashboard, the API and task
dispatch, with shipped roles and a rule that nothing crosses between orgs.
Denials are recorded and reported on the health page. If a policy locks
you out, `archied access reset --org <org>` (or `--instance`) on the State
Store host restores the shipped defaults.
- **Workflows can call workflows** with a `workflow.call` step. Inputs and
call cycles are checked when the workflow is saved, and the caller waits
on the callee's result.
- **Runs record each step.** A run's stages and agent calls are stored as
steps, the task detail page reads them, and stopping a task or archiving
it goes through one cancel path. After a crash, steps left running are
marked interrupted. Archiving a task removes its worktree.
- **Model roles, repositories, scheduling policy, providers and agent
profiles apply without a restart.**
- **Kit harness profiles:**
- `kit` is now one digest-pinned reference, a workload Kit or a published
Kit set, not a list. **Rewrite `kit = [...]` in `config.toml` or the
agent-profiles settings as the single reference**; a list no longer
loads. Compose mixins by publishing a Kit set.
- OAuth logins are handled on the host: the egress proxy refreshes tokens,
stores them encrypted, and gives the container only placeholders.
- A Kit's skills request mounts `skills_dir` read-only, and its
instructions file (such as `CLAUDE.md`) is written beside the workspace,
which is now `/archie/workspace`.
- A run still cannot be granted the credential a Kit needs, so a Kit that
requires one is refused at launch.
- Rate-limited webhook deliveries get `429`.
- `archie-gateway` and `archie-state-store` report ready to systemd.
### archie-agent
- Runs workflow calls, records its steps and agent calls, and runs Kit
harness stages under the profile's Kit.
## [1.42.0] - 2026-09-26
### archied
- **The dashboard is rebuilt on a new Graphite theme.** Settings moved to its
own sidebar with one save flow across every page (Channels, Tools & MCP,
Scheduling policy, Personas and Schedules, Identities, Plugins, Container
runtime, and a History of past changes). The top bar, Dashboard, Workflows,
task detail, the New task dialog and the Events page are all new: Dashboard
leads with what needs you, a run's stage rail and detail panels sit
side by side, Workflows shows per-workflow stats including completed runs,
and Events states capture status with a copyable capture endpoint. Live
updates share one stream and reopen after a drop instead of going quiet.
- **Settings changes are audited.** A field-level audit table records who
changed what, with a view on each settings page.
- **A task can carry a whole-run wall-clock limit**, separate from a stage's
own budget.
- **A run that makes no changes now ends as completed and its worktree is
cleaned up**, rather than left in a state Workflows didn't count.
- **Abandoning a task no longer closes its forge issue.** Only the workflow's
own terminal outcomes do that now.
- **A task whose container exits before the worker replies is parked**
instead of left running with no way to finish.
- **A worktree still holding uncommitted work is kept**, rather than reset,
when its task reaches a terminal state.
- **A provider's stored settings no longer get corrupted with a process-local
placeholder in place of your configured secret reference**, and archied
rejects a stored value shaped like one on the way back in.
- **Kit v3 harness profiles.** A `[containers.profiles.<name>]` entry can now
name a Kit v3 image (`kit = [...]`, pinned by digest) instead of a plain
container image, running the task's agent stages on an external CLI --
Claude Code, Codex, Pi, OMP or GitHub Copilot CLI -- inside an isolated
sandbox network. This release lands the daemon-side plumbing (egress
proxy, sandbox network, credential injection points); it does not yet ship
a way to grant a run's identity the credential a Kit needs, so a Kit
requiring one is refused at launch until a later release adds it.
- `task dev` now starts the State Store and waits for it before the rest of
the stack.
- Every service binary the installer builds is stamped with its version.
### archie-agent
- Carries the same task-lifecycle fixes as archied above (no-change runs,
parking on an early container exit, and the abandon/forge-issue fix), plus
the Kit v3 harness runner: a stage can now drive an external CLI
headlessly, read output from Claude Code, Codex, Pi, OMP or GitHub Copilot
CLI, and serve it capture tools over MCP.
- Claude's cached tokens are counted as prompt tokens, matching the built-in
agent loop's accounting.
## [1.41.2] - 2026-09-25
### archied
- **`/update` no longer offers an old runtime.** The runtime has shipped under
the release version since the version streams merged, but the update check
still read the retired runtime tags, so a current host was offered runtime
1.35.0 as an update. Do not approve that offer on 1.41.1; update to 1.41.2
instead.
- **`/version` reports the runtime version.** Binaries from the release zip
showed `Runtime: dev`.
## [1.41.1] - 2026-09-25
### archied
- **First published build of 1.41.0.** The 1.41.0 tag produced no release
artifacts; 1.41.1 carries everything listed under 1.41.0 below, including
the PostgreSQL 18 requirement and the removed config keys.
## [1.41.0] - 2026-09-25
### archied
- **Archie now stores everything in PostgreSQL 18, and `database_url` is
required.** Tasks, events, captures, bindings, settings and chat
conversations are served from the database `database_url` names; the State
Store, archied and the Gateway refuse to start without it, and refuse a
server older than PostgreSQL 18. `docker compose up -d postgres` starts a
matching local database with the default URL in `config.example.toml`.
- **Existing SQLite data is not carried over.** This release reads no SQLite
file and ships no importer, so an upgraded install starts with empty task,
event and conversation history. `db_path` is gone; `state_dir` (default
`~/.local/share/archie`) now holds the embedded NATS store and task logs.
- **Backups are whole-database snapshots.** `archie-state-store backup` and
`restore` work on the PostgreSQL database through `pg_dump`/`pg_restore`,
which must be on `PATH`. There is no automatic schema rollback: the way back
from an upgrade is restoring the snapshot taken before it.
- **Events carry a type, and bindings pick one.** Archie infers an event type
from captured payloads; the Inspector shows proposed and unidentified
events and lets you name them. Mappings are per event type and show how
many captures they match, a source can feed several bindings, and a binding
chooses an event type plus an optional filter. An unidentified event does
not dispatch.
- **Sources own webhook signing.** Each source gets a UUIDv7 path and its own
signing secret, or can be explicitly approved to accept unsigned events. A
new binding starts pending approval.
- **EDA playbooks can run module actions and take workflow inputs.** Action
playbooks run at most once per event through the dispatch ledger, a binding
can pass inputs to its workflow, the repository is optional, and a workflow
can name an agent profile. `archie-playbooks lint -eda-dir` checks a
directory, and `archie-playbooks serve` publishes the same findings to your
editor as a language server.
- **Config keys removed.** `[agent]`, `[oidc]`, `[image]`,
`containers.enabled`, `db_path`, and the `token_env` form of `[forge]`,
`[artifacts]` and `[chat.telegram]` no longer exist. Write each credential as
`token = { engine = "env", key = "NAME" }`. A leftover key is reported at
startup as unrecognised rather than failing the load.
- **Dashboard.** Old `#/path` links and the `/captures`, `/mappings` and
`/bindings` addresses no longer redirect; use the Events page tabs. The live
stream moved to `/api/stream`, so reloading `/events` serves the page.
### archie-agent
- The Postgres-backed wire formats, event types and workflow inputs are part
of this image; a host that runs the agent should `docker compose pull agent`
to pick it up.
## [1.40.0] - 2026-09-23
### archied
- **Every park now says what kind of intervention it needs.** A parked task
is classified as `needs you` (a decision or fix only an operator can
supply), `transient` (an environment problem -- container pool, storage,
transport -- retry once it is fixed), or `terminal` (the repository or
identity cannot act; retrying cannot succeed). The class shows beside the
Parked badge on the dashboard, so "needs you" reads as a request rather
than a failure.
- **Operator retries and review-remediation rounds now have separate
budgets.** An operator's manual retries no longer draw down the rounds
Archie may spend addressing review feedback on its pull requests, and a
round-cap park no longer makes a later retry re-park immediately.
- **`latest` now names the newest release. A push to `main` that is not a
release publishes `edge` and `sha-<commit>` instead. A host that was
following `main` by pulling `latest` stops advancing at this release --
switch it to `edge` to keep tracking `main`, or leave it on `latest` to
follow releases.**
### archie-agent
- The park-classification wire format is part of this image; a host that
runs the agent should `docker compose pull agent` to pick it up.
## [1.39.0] - 2026-09-23
### archied
- **Archie now acts on review comments left on its own pull requests.** A
requested-changes review (or a standalone comment) on a PR Archie opened
dispatches a remediation run: the smallest change that satisfies the
feedback, committed to the same PR branch and answered in the review
thread. Approved reviews never remediate, each reaction is its own round,
and the exchange is bounded by the repo's `max_retries` before Archie stops
and says so on the PR.
- **The task run page is a master-detail view.** The run's stage rail and
detail panels sit beside the run list, so one run's timeline is visible
without leaving the page.
- **Live activity groups related updates instead of stacking them by event
kind**, so a burst of progress on one task reads as one story, and the
stage filter resets when you switch attempts.
- Contrast fixes on the info and subtle text tokens clear WCAG AA.
### archie-agent
- The review-reaction remediation path is part of this image; a host that
runs the agent should `docker compose pull agent` to pick it up.
## [1.38.0] - 2026-09-23
### archied — Event capture, mappings and bindings are PocketBase records
+186 -340
View File
@@ -1,365 +1,211 @@
# AGENTS.md
Guidance for any coding agent working in this repository.
Keep every rule here harness-agnostic: name the required behaviour, not the tool
that provides it (e.g. "spawn a fresh reviewer that did not write the code", not
a specific sub-command).
## Code Quality & Refactoring Standards
- **Zero Patch Stacking:** Never apply more than two sequential fixes to the
same logic block. If a solution fails twice, scrap the block and rewrite it
cleanly.
- **Root-Cause Fixes:** Fix invalid state at the producer, not via defensive
checks at the consumer.
- **Architectural Simplicity:** Prefer a complete 20-line rewrite over a 5-line
band-aid that adds conditional complexity or obscures intent.
- **Revert on Flail:** If an implementation becomes convoluted to satisfy edge
cases, discard the approach and select a simpler design.
Rules for any agent working in this repository. Short on purpose: every rule
here changes a decision. If a rule stops changing decisions, delete it.
## What this is
**archied** is a resident daemon that polls a forge (GitHub, Gitea) for issues
assigned/labelled to it, works each one in an isolated git worktree through a
routed workflow (bootstrap / implement / TDD / feasibility), and opens pull
requests for human review.
**archie-core** is event-driven agentic automation. An event (an issue, PR,
webhook, schedule, chat message) is matched to a workflow, the workflow runs an
agent or tool in an isolated container, and the result lands somewhere for
review or action. A repository is an optional input to a workflow, not the point
of the product. A forge is one of many inputs or outputs; core code never
assumes one.
Architecture of record lives in `docs/architecture/` -- `organisation.md` for
the package map, `agent-system.md` for the workflow-execution lifecycle and its
invariants, `plugins-and-extensions.md` for engine families. Read it before
making non-trivial changes. Key invariants: env-enforced gates, model never runs
git, and agent execution functions as a strict data boundary. Before adding a new
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
<temporary - remove on 2026-12-01> The goal until 1 December is a
production-ready archie-core, including the features the maintainer is still
adding. Speak up when a request competes with something more urgent: a bug that
loses work, a failure that shows nothing, a security gap, a broken setup path.
Give the trade-off in a sentence or two and suggest whether the request belongs
in the backlog. Don't hold work back on your own judgement. </temporary>
## Scope Discipline
## Services and layout
`docs/architecture/` is authoritative for settled design.
`docs/architecture/migration-decisions.md` is the open decision register for the
domain migration.
Each service is a gRPC contract in `proto/<service>/v1`, generated into
`internal/contracts/<service>/v1`, and one binary in `cmd/` that parses flags
and calls its composition root in `internal/app/<service>`.
- **Settled design exists** → Implement it immediately with a diff. Do not
produce design prose. If a small detail is missing, ask the maintainer
directly.
- **No settled design exists (or open in `migration-decisions.md`)** → Write a
decisive, 1-page design doc before coding. Land new capabilities in
`docs/prds/` and migration questions in
`docs/architecture/migration-decisions.md`. Promote to `docs/architecture/`
only after implementation lands.
- **Strictly Prohibited:** Ownership ledgers, field-level inventories,
current-state traces, parity matrices for their own sake, and
planning/refactor tracking issues.
- **Solo Project Context:** Prefer the smallest workable change over extensive
defensive scaffolding.
- **Verify handed-over input before acting on it.** An export, transcript, or
artifact that is empty, missing, or truncated is a blocking fact: report it
before starting work that assumes its contents. Never reconstruct the intent
from the working tree instead.
- **PRD writing:** Read and follow `docs/prds/RULES.md` before creating or
editing a PRD.
| Binary | Serves | Dials |
| --- | --- | --- |
| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane PostgreSQL tables | PostgreSQL |
| `archie-gateway` | Chat, conversation state, task tools | State Store |
| `archied` | Scheduling, workflow runs, harness, Daemon contract | State Store, Gateway, Messaging |
| `archie-messaging` | External channel frontends | Gateway |
| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, daemon, harness |
| `archie-agent` | The worker inside each task container | NATS |
## Deployment Model
`internal/domain` holds behaviour and interfaces; `internal/infrastructure`
implements them. Dashboard work follows `ui/CLAUDE.md`. Workflow YAML and its
step vocabulary are in `WORKFLOWS.md`; the server catalogue is authoritative.
- **Systemd is optional:** `deployments/` holds supported profiles
(`single-forge-github.toml`, `multi-forge-github-gitea.toml`,
`local-ollama-standalone.toml`, `docker-nats-stack.toml`,
`systemd-user-service.md`). Never assume a systemd unit exists.
- **Chat filesystem confinement:** Builtin tools default to workspace jail via
`SetPathConfinement(!unrestricted)`. Unrestricted access requires
`[chat] unrestricted_filesystem = true`.
- **NATS endpoint immutability:** The daemon passes agent containers its startup
connection URL (`d.ConnectedNATS.URL`). Containers and daemon must resolve
this address. Embedded mode binds to the Docker bridge gateway. A SIGHUP
reload of `nats.url` logs an error requiring restart to prevent split-brain
delivery.
- **Container pull policy:** `containers.pull_policy` must be `"missing"`
(default) or `"always"`. Private registries return 401 on `"always"` because
no auth is sent. Refresh explicitly via `docker compose pull agent`.
- **Docker Compose:** `docker-compose.yml` carries optional external NATS and
the `agent` build stanza. The agent uses a `build` profile so `up -d nats`
never starts it as a persistent service.
- **Config path:** Runtime configuration lives at
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working
tree is load-bearing at runtime.
## Authority
## Release Process
When sources disagree, the higher one wins:
See `RELEASING.md`. Most sessions touch only `archied`, making releases
gateway-only (`RUNTIME=skip`) by default. Skip untouched components
automatically and note it in the handoff.
1. The maintainer's instruction in this session.
2. This file.
3. The code as it is in the tree.
4. Gitea issues (`tea issues view <n>`): the plan for a piece of work.
5. Everything else (memories, comments, old docs) is a hint. Verify it against
the code before acting on it.
## Build & Test
## Working with the maintainer
Commands are defined in `Taskfile.yml` (requires Go 1.27.0,
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm).
`golangci-lint` is the single writer for ordinary Go formatting; standalone
`gofumpt` formats generated protobuf contracts only.
- **A clear direction is the go-ahead.** Do it in the same turn. Do not restate
the plan, offer options, or ask "shall I proceed?". Stop only for destructive
or outward-facing actions (deleting data, pushing, touching a live host).
- **Post outside the repo only when told.** Chat, tickets and any external
service get a message only on the maintainer's instruction.
- **Report, don't narrate.** Final replies say what changed, what was verified,
and anything blocked, in a few lines. No preamble, no recap of the request, no
closing offers of more help. Leave out what the maintainer can see or infer:
a clean tree, unpushed commits, a passing gate (commits imply it), and steps
skipped that the task never asked for. Name a skipped step only when the
task required it.
## How to decide
- **Broken beats new.** A bug that blocks work gets fixed now, with the smallest
change that unblocks it. No design docs and no new mechanism.
- **Cheapest option first.** Before building, name the smallest change that
solves the problem, including changing configuration or deleting something. If
your plan adds a new mechanism (RPC, process, binary, abstraction, config
field, tool) or grows past about 100 lines, stop and assess whether you're
taking the path of least resistance.
- **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and
features nobody runs get removed, not maintained. Solo project, single user:
breaking changes need no compatibility shims.
- **Finish before starting.** Prefer completing a half-built feature end to end
over starting a new one.
- **Services own contracts.** A service is a gRPC contract in
`proto/<service>/v1` and one binary that serves it. Services reach each other
only through those contracts, never through another service's tables or
packages. A new command is a subcommand of an existing binary. A new binary
exists only for a new service or a real process boundary.
- **No compensating tools.** Do not write a linter, checker or generator to
enforce something a simpler design would make unnecessary. Fix the design.
- **A setting must work end to end.** A config field that parses but has no
consumer is a bug. Settings are edited through the control plane (API and
dashboard), never by requiring a server login.
- **Ask only for real decisions.** Product direction and trade-offs the
maintainer owns are questions. Everything with a conventional answer is not:
decide, do it, say what you chose.
## Code
- Idiomatic Go. Small functions, explicit errors, no package-level mutable
state, no god objects. Each feature wires itself; a composition root only
calls those constructors in order.
- Dependencies point inward: `cmd → app → {domain, infrastructure}`,
`infrastructure` implements `domain` interfaces, `domain` imports neither.
`cmd/` parses flags and calls `app`, nothing else.
- Fix invalid state where it is produced, not with checks where it is consumed.
- Log through the service's injected `*slog.Logger` with the `...Context`
methods, so lines carry the OpenTelemetry trace id. Never the global `slog`.
- If a fix fails twice, throw the block away and rewrite it simply.
- Comments say why, briefly. No migration history, phase names or issue
narration in code.
- Generated files (protobuf, sqlc) are regenerated and committed
with the change that caused them, never hand-edited.
## Tests
The default for a change is no new test. Write one only when:
- something actually broke: write the test that reproduces it, see it fail on
the assertion, then fix; or
- the change alters one of these seams: State Store SQL semantics (transition
guards, idempotent dispatch, cancellation), security boundaries (HMAC, grants,
path confinement, egress, secrets), the workflow step contract, or the
import-boundary rules.
A test that exists must catch a real regression, survive refactoring, run fast,
and be cheap to keep. Never test wiring, constants, defaults, struct shapes,
fakes, or call order. No test opens a real database or needs Docker; test
SQL semantics at the interceptor or domain level with fakes. One table-driven test per behaviour; extend the table
instead of adding a second test. Prefer making an invalid state unrepresentable
to testing that it is rejected. Test helpers live in `_test.go` files only.
## Invariants
These protect users. Do not weaken them without the maintainer's say-so.
- Failure stays local. Any service may crash, restart or be absent without
losing accepted work or taking another service down. Callers retry, degrade
and report the dependency as unhealthy; they never exit because a peer is
missing, and work is acknowledged only once it is durable.
- The model never runs git. Commits and pushes go through the daemon.
- The daemon's own credentials never enter an agent container. Containers get
task-scoped grants that are revoked when the task ends.
- Webhook HMAC is verified before the payload is parsed.
- Task briefs go in `<worktree>/.git/task.json`, never the worktree root.
- NATS: task and RPC replies use `msg.Respond`; flush after registering a
responder; `ARCHIE_TASKS` is a work queue, so never bind overlapping
consumers.
- `ai-sdk` `FullStream` must be drained completely.
## Build and gate
```bash
task build # build archied and archie-agent binaries into bin/
task test # go test ./... -count=1
task test:ui # dashboard node tests (DOM-building primitives)
task ui # build dashboard into ui/dist (LAW asset)
task fmt # go fix ./... && golangci-lint fmt
task vet # go vet ./...
task lint # golangci-lint run ./...
task check # fmt + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
task dev # archied live-reload + Vite HMR together on :5173
task build # binaries into bin/
task test # go test -short ./...
task ui # dashboard into ui/dist
task check # the gate
go test -short ./internal/domain/workflow -run TestName # one test
task dev # every service + Vite at http://localhost:5173, from deployments/dev.toml
task e2e:up # seeded local stack; task e2e:check -- all runs the browser checks
```
Single package/test runs:
`task proto:generate` and `task db:generate` write the committed generated
output for `proto/` and `internal/infrastructure/postgres/`; `task check` runs
their check variants and rejects stale output. The e2e stack is not part of the
gate.
Requires Go 1.27, Task, golangci-lint, Node, pnpm and Docker. Adopt `task fmt` and
`go fix` output as-is.
- `task check` gates the commit: `task check && git commit ...`. Never claim a
gate result you did not just produce on that exact tree; if the gate could not
run, say what you did verify.
- Commit finished work without asking. Stage only your own paths and commit in
the same command. Conventional Commits scoped by package, short messages. Push
only when told.
- Never commit binaries, build output, scratch files or `.references/`. Scratch
goes in `/tmp`.
- Runtime config lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.
Nothing in the working tree is read at runtime. Systemd is optional.
- Releases: `RELEASING.md`.
## Issues (Gitea)
Work is tracked as issues on the primary remote, never in Markdown TODO files.
GitHub is a read-only mirror; do not open, close or comment there.
```bash
go test ./internal/domain/workflow/... -run TestName -v -count=1
tea issues list -r sam/archie --state open --labels priority::critical
tea issues list -r sam/archie --labels epic/<slug> --state open
tea issues view 497
tea issues edit 497 --add-labels status::in_progress --add-assignees sam
tea comment 497 "what changed, and what was run"
tea issues close 497
```
## Repository Hygiene
- An issue is the plan: what is wrong or wanted, and how you know it is done.
Keep it to that.
- Labels carry state: `type::`, `priority::`, `status::in_progress` and
`status::deferred`. Open/closed is the issue state, not a label.
`epic/<slug>` says which epic an issue belongs to.
- Cite the issue number in commits and comments.
- `tea issues list --labels` silently ignores an unknown name and returns every
issue. Check the count is plausible before trusting a filtered list.
- The API caps `limit` at 50 regardless of what you pass.
- No host names, IPs, paths, PIDs or credentials in an issue: the text outlives
the change that wrote it.
- File follow-up work you find as an issue. Do not fix it in passing.
- **Generated assets are LAW:** Never modify, revert, or ignore generated files
in `ui/dist/` or schema outputs. Incorporate them into relevant commits.
- **Ignored paths:** Never commit build artifacts, binaries (`/bin/`,
`/archied`), DB files, working screenshots, `.references/`, or
`node_modules/`.
- **Scratch files:** Place scratch files strictly in `/tmp` or the harness
scratch space. Never put scratch files in the working tree
(`worktree.CommitAll` will stage them).
- **Conventional Commits:** Scope by package: `feat(webui): ...`,
`fix(build): ...`, `chore(release): ...`.
- **Commit policy:** Commit finished, gate-clean changes (`task check`
passing) without asking. Push only when instructed.
## Changing this file
## Organisation (Strict Domain-Driven Architecture)
`docs/architecture/organisation.md` is authoritative. Do not follow flat
structures found in legacy packages.
### Layers and Ownership
- `internal/domain/<area>/`: Domain logic, entities, state machines, commands,
events, and required contracts (interfaces). Never imports infrastructure or
app.
- `internal/infrastructure/<service>/`: Implementations of domain contracts
(persistence, forge clients, external transports, config loading).
- `internal/app/<application>/`: Dependency injection, wiring domain to
infrastructure, lifecycle management, and shutdown ordering.
- `cmd/<binary>/`: CLI flag parsing, OS signal traps, and entry point routing
only. No domain wiring.
### Invariants
- **Dependency Flow:** `cmd → app → {domain, infrastructure}`, with
`infrastructure → domain` implementing contracts. Downward/inward dependencies
only.
- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`, `policy`,
`taskstate` sit directly under `internal/`. They may be imported by any layer,
but **must import zero internal packages**. No `shared/`, `utils/`, or
`common/` catch-alls.
- **File Layout:** One file per API concern (`api_tasks.go`, `api_logs.go`). A
package owns its on-disk format end-to-end (e.g. `internal/logging` defines
and reads its format; transport layers do not parse).
- **Frontend:** Features live in `ui/src/<feature>/` with colocated `.js` and
`.css`. Extract to `ui/src/base/` only on the second distinct consumer.
## Per-Package Invariants & Traps
- **Config fields (cross-cutting): a field that parses is not a field that works.**
A knob added to a struct the extensible surface reuses *parses* everywhere
without taking effect anywhere, and a knob read from the wrong layer is just
as invisible: a file key is only a seed once a stored resource outranks it.
Before adding or reusing a config field, name its consumer, and reject the
configuration when there is none - which is what this repo now does for
per-identity `forge.intake`. Two documents carry the detail:
`.agents/skills/archie-config-and-flags` holds the wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field can take;
`docs/architecture/configuration.md` is the authority on the config model and
its reloadability criterion.
- **`internal/channels/telegram/`:**
- The long-polling worker must call `dropPendingUpdates(ctx, b)` before
`b.Start(ctx)` and on `/restart`.
- Always publish command menus to `default`, `all_private_chats`, and
`all_group_chats` simultaneously via `commands.go` to avoid scope shadowing
from legacy registrations.
- **`ai-sdk` Streaming:** `FullStream` writes synchronously and MUST be drained
completely to prevent producer deadlocks. Do not rely on `TextStream` (drops
deltas).
- **NATS Invariants:**
- `ARCHIE_TASKS` uses `jetstream.WorkQueuePolicy`. Do not bind overlapping
consumer filters; use `Fetch` on existing durables instead of new `Subscribe`
calls.
- RPC and task responses must use core NATS `msg.Respond` to write to ephemeral
`_INBOX.*` subjects, not `eventbus.Publisher`.
- Always flush connections (`nc.Flush()`) immediately after registering
responders to avoid race conditions on initial requests.
- **`internal/gateway/` Chat Prompt:** System prompt `<tools>` blocks are
rendered strictly from the active `core.ToolSet`. Never decouple prompt tool
definitions from passed runtime tools.
- **`internal/container/pool.go` (`WriteTaskJSON`):** Write task briefs to
`<worktree>/.git/task.json`. Never place them in the worktree root (`go-git`
`Add{All:true}` ignores `.gitignore` and leaks root files into branch
commits).
- **MCP Providers:** Daemon registers providers as optional via
`providerRegistry.RegisterOptional`. Missing or failed providers log warnings
and degrade health without terminating the process.
- **`internal/infrastructure/staterpc/` (State Store gRPC contract):**
Authority is `docs/prds/state-store-contract.md` (rev. 2e) -- read it before
changing this package or its callers.
- The proto (`proto/state/v1/state.proto`, service `StateStoreService`,
package `statev1` in `internal/contracts/state/v1/`) is one gRPC service
fronting every ratified store contract (50 RPCs, including grant management
and deprecated compatibility RPCs); the Go consumer facades
stay narrow (`workflow.Store`, `store.TaskStore`, etc., all ≤8 methods
except the `TaskStore` composite) via `staterpc.Client`'s multiple `var _`
assertions -- never add a Go interface method without a matching RPC.
- Error sentinels (`store.ErrStaleTransition`, `ErrBindingNotFound`, ...)
cross the wire via `mapError`/`unmapError` in `values.go`, matched on
`(code, exact canonical message)`. Changing a canonical message string
breaks `errors.Is` on the client without changing behavior visibly --
treat those message constants as part of the wire contract.
- The State Store is a standalone process (`cmd/archie-state-store`, run via
`archied.RunStateStore`) -- the daemon and Gateway never own `archie.db` or
serve this service in-process; `boot.openStateStore` in
`internal/app/archied/state_store.go` is the only caller of
`openProductionTaskStore`. Never add a second listener for the same
service, and never reintroduce an in-process serving path in the
daemon/Gateway (`TestOpenStoresNeverOwnsTaskDB` guards this).
- Per-task credentials are scoped, not just authenticated: `daemon.
StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
task-scoped grant at the remote State Store via `RegisterTaskGrant` before
`ContainerPool.Acquire` and revokes it via `RevokeTaskGrant` on `Release`
(`acquireTaskContainer`/`process` in `internal/daemon/daemon.go`). Fails
closed (parks the task) if a State Store is configured but no issuer is
wired -- it must never fall back to forwarding the daemon's own
administrative token. Server-side, `staterpc.TaskGrants.UnaryInterceptor`
authorizes a task-scoped token for only `Update`/`Transition`/`InsertEvent`
on its own task ID; every other RPC (including `RegisterTaskGrant`/
`RevokeTaskGrant` themselves and the streaming capture RPCs) requires the
administrative token.
- `archie-agent` has exactly one `workflow.Store` path: gRPC via
`staterpc.Client` (`agenttransport/nats.Transport.Store`), using the
`STATE_STORE_URL`/`STATE_STORE_TOKEN` env the daemon injects. The legacy
NATS `storerpc` transport is deleted (`internal/storerpc` no longer
exists); do not reintroduce a dual-path selection.
- `store.BindingDispatcher.RecordDispatch` takes no `*sql.Tx` (dropped in
`.4.2` -- it cannot cross a gRPC boundary; production always passed `nil`).
Do not reintroduce a transaction parameter on a producer-owned store
interface that a remote adapter must also implement.
- **`internal/forge/webhook/` (forge webhook receiver):**
- Verify HMAC (`webhookguard.VerifyHMAC` against `X-Hub-Signature-256`) before
parsing the payload, never after -- an unverified body must not reach
`github.ParseWebHook`.
- Do not give the webhook-built `workintake.TaskEnvelope` a delivery-source-
specific idempotency key. `IdempotencyKey()` is keyed on `owner/repo/number`
only so a webhook-delivered issue and a later poll of the same issue dedup
against each other via `PublishUnique`; adding an event ID or timestamp to
the key defeats that and reintroduces poll/webhook double-dispatch.
- Webhook intake refuses to start when `[[identities]]` is configured (one
receiver, one dispatch config). Do not silently enable it for multi-identity
deployments without first building per-identity routing -- see
`docs/architecture/messaging-and-work-intake.md`'s "Intake provenance"
section.
- **`internal/domain/embedding/` + `internal/infrastructure/embedding/`:**
Embedding client contract + implementation. Config-driven exactly like chat
model roles: `models.embedding = "provider/model"` plus a `[providers.*]`
entry. `infrastructure/embedding.New` degrades to `(nil, false)` -- never an
error -- for a missing role, unknown provider, unsupported class, or
unresolved credential; wired as an optional capability in
`bootstrap.go`'s `setupEmbeddings`. Only provider classes matching
`config.Provider`'s shape are supported (openai, gemini, ollama, cohere,
mistral) -- azure needs a `Deployment` field this config type doesn't have.
- **`internal/domain/sampling/`:** The curator `Sampler` interface (see
`docs/prds/curator-sampler-wave1.md`) plus four pure, deterministic
strategies (recency, staleness, random, all). No curator consumes a
`Sampler` yet -- `curator.Registrar` is untouched by this package.
## Development Protocol
1. **Red (Failing Test):** For behaviour with real logic, branching, or a
contract, write failing table-driven tests first against target behaviour.
Verify the failure originates from test assertions, not compilation errors.
Do not write tests that restate an assignment or a constant: a test that
cannot fail for an interesting reason is noise in the gate.
2. **Green (Implementation):** Implement minimal code to satisfy the failing
tests.
3. **Quality Gate:** Run `task check`.
- **The gate gates the commit.** Let the gate's exit status decide whether
the commit runs, as one conditional chain (`check && commit && push`).
Writing them as separate statements on one command line makes the gate
decorative: nothing reads its status but the operator, and a failure is
discovered after it has already been pushed.
- **Never assert a gate result you have not just produced on that exact
tree.** A commit message outlives the tree it describes, and "verified"
is read by people who were not there. If the tree moved, describe the
change and let the run speak.
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
`task fmt` (`go fix` + the configured golangci-lint formatters) verbatim.
Never revert or fight canonical linter/formatter diffs.
5. **No standing adversarial-review pass (for contributors):** Do not spawn a
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
opt-in per request — ask before running one. This is the rule for a human or
agent *contributor*. Separately, archied runs the same adversarial review
automatically on the PRs it opens (gated per repo by `repo.review_enabled`)
— see `docs/architecture/adversarial-review.md`. The two paths are distinct:
you run one when asked; archied runs one before it opens a PR.
6. **Linter Guard:**
- When using `errorlint` fixes, ensure boolean predicates (e.g.
`exitErr.ExitCode() == 1`) are retained alongside `errors.As`.
- When extracting loops/conditionals, verify slice mutations and pointer
semantics do not duplicate elements.
## Issue Tracking (Beads)
All task management is tracked via **bd (beads)**. Do not write local Markdown
TODO lists or use non-Beads trackers.
### Commands
```bash
bd ready # List unclaimed work
bd show <id> # View issue details
bd update <id> --claim # Claim an issue
bd close <id> # Mark issue complete
bd remember # Persist cross-session architectural facts
```
- Run `bd prime` to inspect full engine context.
- Use `bd remember` for knowledge retention. Do not write to root `MEMORY.md`
files.
- Issues live in a local Dolt DB, synced to its own `git+` remote via
`bd dolt push`/`bd dolt pull`. `.beads/issues.jsonl` and
`.beads/interactions.jsonl` are local-only export/audit files
(`.gitignore`d, `export.auto: false`) -- never `git add` them and never
create a commit whose only content is beads bookkeeping. Bead state moves
through Dolt, not through git commits on this repo.
## Session Completion Protocol
1. **Log remaining work:** File new items via `bd` for identified debt or
follow-up tasks.
2. **Run gate:** Verify `task check` passes completely clean.
3. **Update tracker:** Close finished issues via `bd close <id>`. This alone
is not commit-worthy -- do not stage or commit `.beads/` for it.
4. **Commit:** Only for actual code/doc changes, scoped to the files that
changed.
```bash
git add <scoped-files>
git commit -m "feat(scope): description"
```
5. **Sync & Push Policy:** Do not push to git remotes or run `bd dolt push`
unless explicitly instructed.
6. **Handoff:** Report changed files, gate verification results, and active
issue states.
## Maintaining this file
Keep this file for knowledge useful to almost every future agent session in this project.
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
Prefer rewriting or pruning existing entries over appending new ones.
When updating this file, preserve this bar for all agents and keep entries concise.
A rule is added only after a real failure it would have prevented, and it must
say which decision it changes. Remove rules that no longer change decisions.
Keep it short enough to read in full every session.
+7 -18
View File
@@ -2,11 +2,10 @@
# Pre-installs system tools agents can't install themselves (no apt, no sudo).
# Language packages are installed at runtime via uv/npm/go.
#
# Build: docker build -t archie-agent:latest .
# This image is launched only by archied with a daemon-written task brief,
# task worktree mount, and authenticated NATS environment.
# Build: task image:agent (or docker build --build-arg RUNTIME_VERSION=<ver>)
# A build that names no version stamps none, and the agent reports dev.
# ── builder ───────────────────────────────────────────────────────────
# ── builder ──
FROM golang:1.27-trixie AS builder
ARG RUNTIME_VERSION=dev
WORKDIR /src
@@ -17,17 +16,15 @@ RUN CGO_ENABLED=0 go build \
-ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
-o /usr/local/bin/archie-agent ./cmd/archie-agent/
# Same Debian release as the runtime, so glibc matches.
FROM node:24-trixie-slim AS node
# ── runtime ───────────────────────────────────────────────────────────
# ── runtime ──
FROM debian:trixie-slim
ARG RUNTIME_VERSION=dev
LABEL org.opencontainers.image.version="${RUNTIME_VERSION}"
ENV DEBIAN_FRONTEND=noninteractive
# build-essential is for agents building native npm/Python extensions.
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates \
curl \
@@ -41,7 +38,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
openssh-client \
&& rm -rf /var/lib/apt/lists/*
# ── Node.js 24 ────────────────────────────────────────────────────────
# ── Node.js 24 ──
COPY --from=node /usr/local/bin/node /usr/local/bin/node
COPY --from=node /usr/local/include/node /usr/local/include/node
COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
@@ -50,7 +47,7 @@ RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
npm install -g pnpm typescript tsx esbuild stylelint htmlhint && \
npm cache clean --force
# ── Go ────────────────────────────────────────────────────────────────
# ── Go ──
# Reuse the builder's toolchain so the runtime Go can't drift from the one
# archie-agent was compiled with.
COPY --from=builder /usr/local/go /usr/local/go
@@ -58,13 +55,7 @@ ENV GOPATH="/go"
# /go/bin must be on PATH or anything `go install` puts there is unreachable.
ENV PATH="/usr/local/go/bin:/go/bin:${PATH}"
# Pinned release binaries. Building these with `go install` pulled ~2GB of
# module and build cache into the image. delve is omitted because it ships no
# prebuilt binary; `go install ...@latest` at runtime if an agent needs it.
#
# golangci-lint owns ordinary source formatting and lint checks. Standalone
# gofumpt is retained for generated protobuf contracts in tools/proto.sh.
ARG GOLANGCI_LINT_VERSION=2.13.2
ARG GOLANGCI_LINT_VERSION=2.14.0
ARG GOFUMPT_VERSION=0.11.0
ARG BUF_VERSION=1.72.0
@@ -78,8 +69,6 @@ RUN curl -fsSL "https://github.com/golangci/golangci-lint/releases/download/v${G
chmod +x /usr/local/bin/gofumpt /usr/local/bin/buf
# ── Python via uv ─────────────────────────────────────────────────────
# uv manages its own interpreters — no apt Python, no deadsnakes PPA. One
# version is the default; agents can `uv python install <other>` on demand.
ARG PYTHON_VERSION=3.14
RUN curl -fsSL https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"
+14 -18
View File
@@ -1,29 +1,26 @@
# archied — the archie daemon, built as a standalone container.
# archied — the archie daemon
# Run via docker compose alongside NATS.
FROM node:24-trixie-slim AS dashboard
WORKDIR /src/ui
RUN corepack enable
COPY ui/package.json ui/pnpm-lock.yaml ui/pnpm-workspace.yaml ./
RUN pnpm install --frozen-lockfile
COPY ui/ ./
RUN pnpm run build
FROM golang:1.27-trixie AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
COPY --from=dashboard /src/ui/dist ./ui/dist
ARG GATEWAY_VERSION=dev
ARG RUNTIME_VERSION=dev
RUN CGO_ENABLED=0 go build \
-ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${GATEWAY_VERSION} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
-ldflags "-X github.com/samcharles93/archie-core/internal/buildinfo.Version=${GATEWAY_VERSION} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
-o /usr/local/bin/archied ./cmd/archied/
# archied is static, but this can't be scratch: in inprocess mode the daemon
# runs agent tools itself, and the shell tool invokes bash; codesearch shells
# to git. Worktrees don't count — internal/worktree uses go-git. This image
# is not part of the current deployment (docker-compose.yml only builds
# Dockerfile, the agent image; archied runs on the host under systemd), but
# if it's ever used in inprocess mode, grep needs ripgrep on PATH -- it is
# no longer embedded in the binary.
#
# No Node: the builtin tools (read/write/edit/find/grep/shell/test) cover what
# desktop-commander did. Any npx-launched MCP stdio server will now fail to
# start, and a failed provider rolls back the tool-provider family and exits
# the daemon — so remove tools.mcp_servers entries needing npx before
# deploying this image.
FROM debian:trixie-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates git && \
@@ -33,8 +30,7 @@ ARG GATEWAY_VERSION=dev
ARG RUNTIME_VERSION=dev
LABEL org.opencontainers.image.version="${GATEWAY_VERSION}"
LABEL cloud.catlow.archie.runtime-version="${RUNTIME_VERSION}"
# One release stream: CHANGELOG.md carries every release section, with each
# component's detail as a labelled section inside it. The per-component files
# this used to copy were deleted with the split release.
COPY CHANGELOG.md /usr/share/archie/CHANGELOG.md
ENTRYPOINT ["archied"]
+202
View File
@@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
+7
View File
@@ -0,0 +1,7 @@
NOTICE
This product includes software from the Cedar project
(https://github.com/cedar-policy/cedar), Copyright Amazon.com, Inc. or its
affiliates, licensed under the Apache License, Version 2.0, as implemented by
github.com/cedar-policy/cedar-go, which declares the same license in its
repository. This repository links the library; it derives no source from it.
+158
View File
@@ -0,0 +1,158 @@
# Archie
**Event-driven Agentic Automation**
Archie connects events from your systems to agents that can investigate, reason,
and act. Define what an event means, map its data into a workflow, and give that
workflow an agent equipped for the job: its own execution environment, tools,
and identity.
The aim is to automate work across system administration, incident response,
network operations, service management, and software delivery. You define the
process and the access it requires; agents work through its stages, using the
context of each event to decide how to accomplish the task.
Archie is under active development and not every capability below is
finished.
## From an event to an outcome
```text
Event source → Event type → Mapping → Binding → Workflow → Agent
```
| Concept | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Source** | Receive events from a system such as a firewall, monitoring stack, service desk, or forge. Configure its endpoint and signing requirements. |
| **Event type** | Identify which kind of event arrived from its headers and payload. Infer a schema from captured events or a pasted example. |
| **Mapping** | Extract named, typed parameters from the event. Reuse a mapping across bindings and see how often it matches. |
| **Binding** | Select a workflow, filter the events that should trigger it, and supply its inputs from mapped values or constants. |
| **Workflow** | Define the stages of work, their inputs and outputs, and the agent profile to use. Call other workflows when work needs another specialist or process. |
| **Agent** | Execute the work in a container with the tools for its purpose, acting under its own identity and granted permissions. |
A single source can produce several event types. An event type can feed several
bindings, and each binding can apply its own conditions. This lets the same
incoming data drive different responses without building a custom integration
for every workflow.
For example, a firewall sends a blocked-connection event. Archie identifies the
event type and maps the source address and severity into an investigation
workflow. A network investigator gathers evidence, assesses the activity, and
returns its findings. The workflow could then call a separate containment
workflow, subject to the permissions and approvals configured for that action.
The same model supports other processes:
- **Infrastructure operations:** A monitoring alert starts a diagnostic workflow
to inspect a service, collect evidence, and propose or perform an authorised
recovery action.
- **Service management:** An incoming request supplies the parameters for a
triage, investigation, or fulfilment workflow.
- **Software delivery:** A forge event starts a review or implementation
workflow with the repository's toolchain, validation steps, and pull request
as its output.
These are examples of workflows you can build. Their behaviour comes from the
workflow, tools, and access you configure.
## Agents equipped for their work
An agent profile selects the container image and available tools. You can supply
images with the software needed for a particular environment: network utilities
for an investigator, operational tooling for a systems agent, or a language
runtime and test framework for repository work.
Workflows declare structured inputs and can return structured outputs. They can
run with a scratch workspace, require a repository, or accept one optionally. An
investigation can finish with a report; a maintenance workflow can finish with
an operational result; a coding workflow can finish with a pull request.
Workflows can also call other workflows and pass data between them. Each called
workflow has its own run and agent profile. A caller can wait for the result or
continue while the called workflow runs independently.
The archipelago marketplace's `workflows/firewall` package is an example of a
workflow that uses typed inputs, a network investigator profile, and no
repository.
## Identities and controlled execution
Agents act as their own identities, with secrets and permissions granted to
that identity. Runs receive credentials scoped to their task; event data
supplies inputs and cannot grant access. Organisations, workspaces and
policy-based access control are in progress.
## Building and operating automations
The dashboard brings together event inspection, mappings, bindings, workflows,
and task activity. The intended authoring path starts with a real payload or an
example: identify its structure, map the fields you need, select a workflow, and
approve the binding.
Sources default to signed delivery; an unsigned source must be explicitly
approved. Binding changes require re-approval before they can dispatch work.
## Run it on a server
You need x86_64 Linux with curl and unzip, Docker (agents and the bundled
PostgreSQL run in containers) and a model: local [Ollama](https://ollama.com)
or a hosted provider API key.
1. **Install.**
```bash
curl -fsSL https://offloaded.dev/install.sh | bash
```
It downloads the latest release, verifies its checksum, installs the five
services into `~/.local/bin` and runs `archied setup`. Setup asks for the
PostgreSQL URL (leave it blank for a bundled database with a generated
password), a model provider and key, and a forge (choose **none** for
event-driven automation only). Answers go to `~/.config/archie/config.toml`
and secrets to `~/.config/archie/env`. The installer then starts the
bundled PostgreSQL with Docker Compose and installs and starts systemd user
units. Pass options with `| bash -s -- --help`; `--from-source` builds a
checkout instead. Re-run `archied setup` at any time to change the answers.
Extensions run in an unprivileged user namespace. Ubuntu 23.10 and later
block these by default; on such a host the installer prints an AppArmor
profile that allows them for the Archie binaries only, to install with
`sudo`.
2. **Check it is up.**
```bash
systemctl --user status archied archie-state-store archie-gateway archie-ui archie-messaging
curl -s http://127.0.0.1:8485/health/detailed
```
3. **Open the dashboard** at <http://127.0.0.1:8484>. It binds loopback by
default; tunnel to it (`ssh -L 8484:127.0.0.1:8484 server`) or see
[deployments](deployments/README.md#running-the-dashboard) to expose it
with a token.
4. **Automate your first event** with
[Your first playbook](docs/guides/first-playbook.md): send a webhook, map
its fields, bind it to a workflow and watch the task run.
To write the config by hand instead, start from
[`deployments/standalone.toml`](deployments/standalone.toml) (no forge) or
another [deployment template](deployments/README.md).
## Develop
`task dev` starts every service with Vite hot reload at
<http://localhost:5173>, using [`deployments/dev.toml`](deployments/dev.toml).
`task check` is the quality gate; [AGENTS.md](AGENTS.md) lists its tools.
## Documentation
- [Your first playbook](docs/guides/first-playbook.md)
- [Deployment examples](deployments/README.md)
- [Release process](RELEASING.md)
Contributions follow [AGENTS.md](AGENTS.md).
## License
Copyright 2026 Sam Catlow. Licensed under the [Apache License, Version 2.0](LICENSE). Third-party attributions are in [NOTICE](NOTICE).
+235 -77
View File
@@ -1,100 +1,258 @@
# Releasing
One release stream. `CHANGELOG.md` carries every release section, one generated page
per version describes it, and one tag names the release. A release is one version
covering whatever changed; the components' entries are labelled sections inside it
(`### archied`, `### archie-agent`), not separate numbers or separate pages.
One release stream. `CHANGELOG.md` carries every release section, one generated
page per version describes it, and one `v*` tag names the release. One version
covers every process in the host bundle (`archied`, `archie-gateway`,
`archie-state-store`, `archie-ui`, `archie-messaging`) and the `archie-agent`
image; per-component detail is a labelled section inside the version
(`### archied`, `### archie-agent`).
The host bundle ships six processes — `archied`, `archie-gateway`,
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks` — and one
version covers all of them. `archie-agent`, the per-task sandboxed runtime, ships as a
container image and its changes are the `## [version]` release's `### archie-agent`
section.
A release is cut by CI, published to `next`, run on the canary for a day, and
promoted to `stable` only if the canary's signals pass. Nothing is run locally.
`tools/release.sh` decides which commits a release carries from the package closure of
**every shipped binary**, not from commit-message guessing: a change to a package only
the messaging service, state store, playbook runner or UI links still lands in the
changelog. Read its header comment for how it partitions commits and enforces
`main`-only, clean-tree releases.
## Notes are written with the change
## What justifies a version
`task release:preview VERSION=X.Y.Z` shows exactly what would land, before anything is
written. A commit set that justifies no version produces no version: `release.sh`
exits **3** with "nothing to release" rather than inventing one, so a pipeline can
finish green without tagging.
Most sessions touch the gateway side (daemon, gateway, web UI, chat, messaging) and
leave the agent runtime alone. That is no longer a per-component `skip` decision — one
version covers the release — but a runtime code change being merged to `main` is still
not the same as it being in production: the `archie-agent` image is rebuilt by the
release, and a host that runs the agent must pull the new image
(`docker compose pull agent`) to get it.
## What the notes are for
A commit that changes what a reader experiences adds its bullet under
`## [Unreleased]` in `CHANGELOG.md`, in the same commit. The release takes that
section as it stands, so write the bullet as the release note, not as a commit
subject.
**Release notes describe the reader's experience of what shipped.** The test is
the reader, not whether a sentence is negative:
- A capability that **never existed** leaves no expectation to correct, so a note
about it reads as a feature to someone who never had the thing — out.
- **The implementation's journey** — what was rebuilt, what a guard finally
covers, what a browser API refuses to surface — is not the reader's experience
either — out.
- A capability that **shipped but is not yet wired** *is* the reader's
experience, so it belongs, worded as a caveat on the capability and paired with
the behaviour that compensates for it.
- A capability that **never existed** leaves no expectation to correct, so a
note about it reads as a feature to someone who never had the thing: out.
- **The implementation's journey** (what was rebuilt, what a guard finally
covers, what a browser API refuses to surface) isn't the reader's experience
either: out.
- A capability that **shipped but isn't yet wired** _is_ the reader's
experience, so it belongs, worded as a caveat on the capability and paired
with the behaviour that compensates for it.
Design constraints and withheld capabilities belong in `docs/architecture/`,
where implementers look, because there they are requirements rather than news.
Do not apply this mechanically: deleting a caveat a reader needs misleads them,
which is the failure this rule exists to prevent.
Design constraints and withheld capabilities are not release news. Deleting a
caveat a reader needs misleads them, which is the failure this rule exists to
prevent.
## Cutting a release
```bash
task release:preview VERSION=1.3.0 # preview what would land
task release:prepare VERSION=1.3.0 # write the section into CHANGELOG.md, uncommitted
# edit CHANGELOG.md -- generated notes are a starting point, not the release
task release VERSION=1.3.0 # commit + annotated tag
git push origin main --follow-tags # CI stamps images with real versions
```
Dispatch the **release** workflow (`.github/workflows/release.yml`) with
`major`, `minor`, `patch` or an exact version. It runs `task release` on `main`:
`release:prepare` emits bare commit subjects; they are a starting point. Rewrite them
to say what a reader gets, per "What the notes are for" above.
1. refuses a dirty tree, an existing tag, or an `[Unreleased]` with no entries;
2. turns `[Unreleased]` into `## [x.y.z] - date` under a new empty
`[Unreleased]`, and runs `task news`;
3. commits `chore(release): vx.y.z` and tags `vx.y.z`;
Pushing is a separate, explicit step — never push without confirming first (see the
repo's general "check before doing anything hard to reverse" rule). The deploy
workflow reads tags pointing at `HEAD`; pushing the commit without its tag gets images
stamped `dev`.
then pushes `main` and the tag atomically with `DEPLOY_TOKEN`. A push made with
the job token wouldn't start other workflows, so the user token is what lets
the tag start the deploy.
Every workflow that reaches the registry or the canary reads its credentials
from Actions secrets, so a mirror of this repository carries its own set:
| Name | Kind | Used by |
|---|---|---|
| `DEPLOY_TOKEN` | secret | release, deploy, canary, promote — the registry push, the tag push, and the package links |
| `RELEASE_SIGNING_KEY` | secret | deploy — signs the release statement |
| `CANARY_TOKEN` | secret | deploy, canary, promote — the canary's dashboard API |
| `CANARY_URL` | variable | deploy, canary, promote — where that dashboard is |
| `CANARY_WINDOW` | variable | canary — the judged window; empty means the default |
A mirror missing them fails at its first login or push; `release.yml` names the
missing `DEPLOY_TOKEN` before it checks out, so the run doesn't read as a broken
release.
After a release, pull `main` before committing on it again: CI has added the
release commit.
## What a release publishes
Tagging one version produces, from a single `deploy` run:
The tag push runs `deploy.yml`:
- **Container images** — `ghcr.io/samcharles93/archied:latest` and
`ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by the
release, so runtime commits merged to `main` do not reach a running sandbox until the
host pulls the new image.
- **A GitHub Release with a distribution zip** — `dist-zip` builds every process the
reference deployment runs (`archied`, `archie-gateway`, `archie-state-store`,
`archie-ui`, `archie-messaging`, `archie-playbooks`) for linux/amd64, packs them with
`deployments/INSTRUCTIONS.md` and `CHANGELOG.md`, and attaches the zip to the
Release. The Release body is that version's `## [version]` section of `CHANGELOG.md`.
- **Gate.** `task check TEST_FLAGS=-count=1` (uncached, including the
Docker-backed tests `-short` skips) and `govulncheck`, then a check that the
tag has a `[version]` section in `CHANGELOG.md`.
- **Images.** `archied:v<version>` and `archie-agent:v<version>` on a release
tag; `archied:edge` and `archied:sha-<commit>` on any other push to `main`.
`:latest` moves only on promotion, so it names the newest promoted release.
- **The signed release.** `archied release publish` signs a statement
(version, issued_at, zip digest, agent image by digest) with
`RELEASE_SIGNING_KEY` and pushes it with the distribution zip to
`git.catlow.cloud/sam/archie` as `v<version>` and `next`. It never moves
`stable`.
- **The release-notes page** on Gitea, from that version's `CHANGELOG.md`
section, which the statement links to.
- **The canary install**: `archied release canary start` points the canary at
`next` and installs the release through its dashboard.
The zip is also uploaded as an Actions artifact, but that is a backup copy: artifacts
expire after 90 days and need an Actions login to download. The Release asset is the
durable, operator-reachable one.
GitHub-style Actions run the workflow from the tagged commit, so a fix to
`deploy.yml` reaches a release only if it is an ancestor of the tag. Re-cut the
release rather than committing the fix on top of a tagged one.
## Gate
## The canary
CI (`deploy.yml`) runs `task check` before building images, then verifies any release
tag at `HEAD` has a matching `[version]` section in `CHANGELOG.md`. A tag with no
changelog entry is a hard failure. No tags at `HEAD` is a warning, not a failure —
images get stamped `dev`.
The canary is the production host, following `next`. Every quarter hour
`canary.yml` runs `archied release canary check`, which reads the canary
through its dashboard API and judges **the release the canary actually runs**,
not the moving `next` tag:
One consequence worth knowing when a release commit needs amending: GitHub Actions
runs the workflow **from the commit that triggered it**, so a fix to `deploy.yml` only
takes effect for a release if it is an ancestor of the tagged commit. Delete and re-cut
the tag (`git tag -d`, `task release`) rather than committing the fix on top of an
already-tagged release.
| Signal | Source | Fails when |
| --- | --- | --- |
| Install outcome | `GET /api/chat/update` | the canary doesn't run the judged release (the watchdog rolled it back) |
| Readiness | `GET /health/detailed` | the rollup isn't `ok` |
| Alerts | `GET /api/alerts` | an open `action` alert was first raised after the release was installed |
| Error log | `GET /api/logs?level=error` | error lines per window exceed `2 × baseline + 10` |
| Task outcomes | `GET /api/tasks` | the share of finished tasks that parked or died rose more than 10 points |
- **Control.** The canary's own window before the release was installed. With
one production host there's no simultaneous control.
- **Window.** 24 hours counted from the **install** on the canary, not from
the release's issue time: the host records it in `installed.json`
(`committed_at`) and reports it as `installed_at` in `GET /api/chat/update`.
One cycle of schedules and traffic. The first 30 minutes are for the install
and restart. `canary.yml` passes `-window` when the `CANARY_WINDOW` Actions
variable is set; the flag defaults to 24h. A host that doesn't report an
install time degrades to the release statement's issue time.
- **Hard signals** (install, readiness, alerts) roll back at any check after
that. **Relative signals** (errors, tasks) are judged against the baseline
whenever both windows carry enough data, so a breach rolls the release back
even mid-window; a full window with no failure promotes it.
- **Too little data skips a signal** rather than failing it: fewer than 5
finished tasks in the window, or an error log that reaches back less than an
hour into the baseline. A log read that stops short of a window is scaled to
a full window from what it covers.
### Queueing
`deploy.yml` installs each new release on the canary with
`archied release canary start -version V`, which first points the canary back
at `next` (clearing any rollback pin) and then installs `V` — unless the
canary is already judging a release newer than stable that isn't `V`, in which
case `V` is **queued** behind it and the canary keeps running what it judges.
`-force` installs regardless. A `check` that promotes (or finds nothing to
judge) installs the newer `next` in the same run, so a queue drains one
release per promotion.
### Subcommands
```
archied release canary status read-only: channel/pin, installed release and
installed_at, stable/next, window progress, and
the verdict the current signals would give
archied release canary start point the canary at next and install -version,
queued behind a release being judged (-force to
override)
archied release canary check judge the installed release over -window
(default 24h): promote, pick up a newer next,
or roll back; a held canary is reported, and a
held pin that is no longer installable fails
the run red
archied release canary promote promote the installed release now if its
signals pass; refuses with exit 1 otherwise
archied release canary unpin return the canary to next from any pin
```
### Promote
A release that passes the window is promoted: `stable` is retagged to the
`v<version>` manifest. The signature covers the statement, not the tag, so the
retag needs no signing key. The `archied` and `archie-agent` images' `:latest`
move to their `:v<version>` first, and the agent image must be the digest the
statement pins. Promotion refuses a prerelease and a release issued before the
one `stable` names, the same replay rule hosts enforce. The decision and its
reasons are in the `canary` run log.
Early promotion is a dispatch away: the **promote** workflow
(`.github/workflows/promote.yml`) takes a `version` input and runs
`archied release canary promote -version V` on the canary. It judges the
release the canary runs — the window doesn't matter for the decision — and
refuses (red run) on any hard failure or relative breach with enough data.
### Roll back
`stable` stays put, and the run turns red. Before the canary is pinned to
`stable`, `check` verifies `stable` is actually installable — its statement's
zip blob must still be in the release repository and its pinned agent image
must still resolve (`releaseupdate.Installable`). If it isn't, the run fails
loudly and the canary stays on `next` rather than being stranded on a pin.
Otherwise the canary is pinned to the `stable` version through its update
settings and reinstalled through its dashboard.
A release whose migrations differ from `stable`'s can't go back without
restoring the pre-update database snapshot, which loses every write since. The
canary is held on the failed release instead (pinned to it) and the fix goes
forward in the next release. The next release's deploy points the canary back
at `next`.
A pinned canary isn't judged, so a rollback is decided once — but `check`
verifies the pin is still installable every run, so a stranded pin shows red
instead of green. `archied release canary unpin` returns the canary to `next`
by hand.
### Configuration
| Name | Kind | Holds |
| --- | --- | --- |
| `CANARY_URL` | Actions variable | the canary's dashboard URL; unset disables the canary steps |
| `CANARY_TOKEN` | Actions secret | an API token bound to a dedicated `service_account` identity on the canary, carrying only the canary grant policy (see below) — never instance admin |
| `CANARY_WINDOW` | Actions variable | optional `-window` override for `canary check`; unset is 24h |
| `DEPLOY_TOKEN` | Actions secret | registry and repository write, for publishing, promoting and the release push; stays CI-only, promotion runs in CI and never on the host |
| `RELEASE_SIGNING_KEY` | Actions secret | the release signing seed |
#### Setting up `CANARY_TOKEN` once
`CANARY_TOKEN` is a bearer token for a dedicated service-account identity in
the system org whose only grant is the canary policy
(`access.CanaryGrantPolicy`): read the signal endpoints (`GET /api/chat/update`,
`GET /api/alerts`, `GET /api/logs`, `GET /api/tasks`), read and write the
`update-settings` resource, and trigger an update install
(`POST /api/chat/update/install`). It carries no other rights, and instance
admin is never needed. With an instance-admin token (for example the operator
session), run against the canary host:
```bash
# 1. Create the service-account identity in the system org.
curl -X POST "$CANARY_URL/api/identities" -H "Authorization: Bearer $ADMIN" \
-H 'Content-Type: application/json' \
-d '{"kind":"service_account","display_name":"ci-canary"}'
# -> {"id":"<canary-identity-id>", ...}
# 2. Issue its token (shown exactly once).
curl -X POST "$CANARY_URL/api/identities/<canary-identity-id>/tokens" \
-H "Authorization: Bearer $ADMIN" -H 'Content-Type: application/json' \
-d '{"name":"ci-canary","days":90}'
# -> {"id":"<token-hash>","token":"archie_pat_..."} -- store the token value as the CANARY_TOKEN secret
# 3. Install the grant pair, scoped to that identity. The policies' org is
# pinned to the caller's org (org-sys for the instance admin), so the
# bodies need no org field. The permit alone is not enough: service
# accounts created through the API are assigned the developer role, so a
# matching forbid (installed second) negates everything outside the
# permit's surface for that identity.
curl -X PUT "$CANARY_URL/api/access/policies" -H "Authorization: Bearer $ADMIN" \
-H 'Content-Type: application/json' \
-d '{"id":"org-canary-grant","level":"org","text":"permit(principal, action, resource) when {\n resource.org == principal.org &&\n principal == Archie::Identity::\"<canary-identity-id>\" &&\n (\n (action == Archie::Action::\"read\" && [\"dashboard\", \"task\"].contains(resource.kind)) ||\n (action == Archie::Action::\"read\" && resource == Archie::Object::\"update-settings\") ||\n (action == Archie::Action::\"update\" && resource == Archie::Object::\"update\") ||\n (action == Archie::Action::\"manage_identities\" && resource == Archie::Object::\"update-settings\")\n )\n};"}'
```
The second policy forbids the canary identity from everything the permit does
not name, so its developer role cannot widen the grant:
```bash
curl -X PUT "$CANARY_URL/api/access/policies" -H "Authorization: Bearer $ADMIN" \
-H 'Content-Type: application/json' \
-d '{"id":"org-canary-grant-forbid","level":"org","text":"forbid(principal, action, resource) when {\\n resource.org == principal.org &&\\n principal == Archie::Identity::\\\"<canary-identity-id>\\\" &&\\n !(\\n (action == Archie::Action::\\\"read\\\" && [\\\"dashboard\\\", \\\"task\\\"].contains(resource.kind)) ||\\n (action == Archie::Action::\\\"read\\\" && resource == Archie::Object::\\\"update-settings\\\") ||\\n (action == Archie::Action::\\\"update\\\" && resource == Archie::Object::\\\"update\\\") ||\\n (action == Archie::Action::\\\"manage_identities\\\" && resource == Archie::Object::\\\"update-settings\\\")\\n )\\n};"}'
```
The policy texts are exactly `access.CanaryGrantPolicy` and
`access.CanaryGrantForbidPolicy` from `internal/domain/access/canary.go` with
the identity id filled in. The canary needs no other rights: `GET
/health/detailed` is unauthenticated, and every other call it makes is covered
by the grant pair.
The runner must reach `CANARY_URL`. Without a canary a release stays on `next`
until promoted by hand, under the same refusals:
```bash
archied release promote -version 1.57.0 \
-latest git.catlow.cloud/sam/archied,git.catlow.cloud/sam/archie-agent
```
+178 -442
View File
@@ -2,13 +2,13 @@ version: "3"
vars:
BIN_DIR: "bin"
# The version a build reports: the nearest tag with the distance and commit,
# or a bare commit when the checkout has no tags (a shallow clone). A build
# should not answer "dev" only because the caller did not name a version.
VERSION:
sh: git describe --tags --always --dirty 2>/dev/null | sed 's/^v//' || echo dev
tasks:
default:
desc: List available tasks
cmds:
- task --list
fmt:
desc: Fix and format Go source with the gate's configured formatters
cmds:
@@ -53,125 +53,32 @@ tasks:
cmds:
- bash tools/proto.sh lint
db:generate:
desc: "Regenerate the sqlc query code from the schema and query files"
cmds:
- go -C tools tool sqlc generate -f {{.ROOT_DIR}}/internal/infrastructure/postgres/sqlc.yaml
db:check:
desc: "Regenerate the sqlc code and reject uncommitted generated differences"
cmds:
- task: db:generate
- git diff --exit-code -- internal/infrastructure/postgres/postgresdb
proto:check:
desc: Regenerate contracts and reject uncommitted generated differences
cmds:
- bash tools/proto.sh check
docs:generate:
desc: Regenerate the committed contract reference from Archie-owned types
summary: |
Writes docs/data/generated/contracts.json. The output is committed, so
this dirties the tree deliberately: review the diff and commit it with
the code change that shifted the contract surface. Never hand-edit the
artifact.
-mod=readonly is mandatory on every `go -C tools` command; see
task test:tools for why.
cmds:
- go -C tools run -mod=readonly ./docsgen --repo-root ..
docs:check:
desc: Verify the committed contract reference matches Archie-owned types
summary: |
Implements Step 6 of docs/architecture/generated-documentation.md:
generates into a temporary directory, compares it with the committed
output, names the authoritative Go definition behind each mismatch, and
exits non-zero without modifying the working tree.
Fix a failure with `task docs:generate`, then commit the result in the
same commit as the code change that shifted the contract surface. This
checks rather than regenerates on purpose: a gate that silently rewrote
the artifact would bless an unintended contract change with no reviewer
ever seeing it, which Step 9 explicitly forbids.
cmds:
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
docs:prds:
desc: Reject session-bound writing in docs/prds
summary: |
A PRD states a decision, a requirement, a constraint or evidence. Those
survive the code moving underneath them. A line number, a progress
report or a dated status claim does not: it is true on the day it is
written and silently wrong a month later, while still reading as
authoritative. The tracker records progress; the PRD records the design.
Each finding names the file, the line, the rule and the fix. There is no
--fix: the replacement is a judgement about what the sentence was for.
cmds:
- go -C tools run -mod=readonly ./prdlint --repo-root ..
news:
desc: Regenerate the news page and per-version release notes from the changelog
summary: |
Writes docs/news/releases.json, docs/news/redirects.json and docs/news/.
The JSON is the canonical, host-neutral fact set every renderer reads;
the redirect table maps the retired /news/<component>/<version>/ URLs to
the unified page for that version; the markdown is the MkDocs adapter.
All of it comes from CHANGELOG.md, so cutting a release adds no writing
here.
The files are committed, so this dirties the tree deliberately: review
the diff and commit it with the changelog that produced it. Never
hand-edit a generated release page.
tools/release.sh --tag runs this before the release commit, and it skips
any file whose bytes already match, so a re-run leaves the tree clean.
desc: Regenerate the release data artifacts from the changelog
cmds:
- go -C tools run -mod=readonly ./newsgen --repo-root ..
news:check:
desc: Verify the committed release notes match the changelog
summary: |
Derives the release notes in memory and fails when the committed files
differ, without modifying the working tree. Runs in `task check`, so a
changelog edit cannot land without its regeneration.
A version page the generator does not produce (a page for a release the
changelog no longer carries, or one left in the retired
docs/news/<component>/ layout) is a finding too; a hand-written news item
belongs at the docs/news root instead.
cmds:
- go -C tools run -mod=readonly ./newsgen check --repo-root ..
docs:artifact:
desc: Regenerate the canonical docs artifacts from the Markdown sources
summary: |
Writes docs/data/generated/docs.json and dev-docs.json: every published
page's url, title, section and raw Markdown body, plus the sidebar tree
derived from the layout, one file per set. The JSON is the canonical,
host-neutral fact set a renderer reads; the Markdown stays the source.
MkDocs was the first renderer and the Astro app is the second, so the
artifact is the product.
Two sets, split by audience: the public set (served under /docs/) is what a
reader of the product needs, the development set (/dev/) is architecture/
and prds/. The split and the reasons for what is held back entirely --
archive/, inspiration/, news/ and the credential notes -- live in
tools/docsite/main.go, because a renderer reading an artifact cannot see
why a page is absent from it.
The files are committed, so this dirties the tree deliberately: review the
diff and commit it with the page that produced it.
The artifact's keys are a frozen contract: an application is built against
them, so renaming one breaks a consumer this repository does not compile.
cmds:
- go -C tools run -mod=readonly ./docsite --repo-root ..
docs:artifact:check:
desc: Verify the committed docs artifacts match the Markdown sources
summary: |
Reproduces both artifacts in memory and fails when a committed file
differs, without modifying the working tree. Runs in `task check`, so a
page edit cannot land without its regeneration.
The generated directory is accounted for by docsgen's generatedArtifacts,
which names both files alongside contracts.json: one registry for the
directory rather than one per writer.
cmds:
- go -C tools run -mod=readonly ./docsite check --repo-root ..
vet:
desc: Run go vet
cmds:
@@ -179,283 +86,169 @@ tasks:
lint:
desc: Run golangci-lint
summary: |
Both modules. ./... from the root stops at the root module, so the tools
module was never linted and drifted unseen -- the same hole task check
already closes for tests with test:tools.
cmds:
- golangci-lint run ./...
- task: lint:tools
lint:tools:
desc: Run golangci-lint over the tools module
summary: |
./... from the root stops at the root module, so the tools module was
never linted and drifted unseen -- the same hole task check already
closes for tests with test:tools.
dir: tools
cmds:
- golangci-lint run ./...
lint:playbooks:
desc: "Lint playbook binding dirs for collisions (standalone tool, cmd/archie-playbooks)"
summary: |
Runs the standalone playbook linter (archie-playbooks lint) against
./playbooks by default. It validates playbook YAML binding files
against the same loaders the daemon uses at startup, so a pre-merge
check can never disagree with runtime validation. Exit non-zero on
any collision / malformed file / invalid binding.
Lint a different set of directories directly:
go run ./cmd/archie-playbooks lint -dir ./a -dir ./b
cmds:
- go run ./cmd/archie-playbooks lint -dir ./playbooks
vuln:
desc: "Scan for known stdlib/dependency CVEs (govulncheck). Not part of task check: it needs network access to the vuln DB and is not build/test-blocking; run it explicitly or in CI."
cmds:
- govulncheck ./...
deadcode:
desc: "Report functions no shipped binary can reach (whole-program RTA from ./cmd/...). Not part of task check: it reports a standing backlog, so gating on it would fail every run until that backlog is zero."
summary: |
Answers "is this reachable in production", which no linter does:
golangci-lint's unused check is package-scoped, so anything exported
and called from a sibling package looks live even when no binary
reaches it.
Run via `go run ...@latest` deliberately. A locally installed deadcode
built against an older Go than this module exits non-zero and prints
NOTHING, which reads as "no dead code" instead of "analysis failed".
Building it against the repo toolchain makes that failure impossible.
-test=false is the point of the report: a function reached only by its
own tests is not reachable in production.
Read the output in one direction only. RTA over-approximates what is
reachable, so "unreachable func" is sound and worth acting on, while
silence proves nothing: interface dispatch and any address-taken
function (every reflect.ValueOf entry in the *extract tables) is
assumed reachable whether or not it is ever called.
cmds:
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
reachaudit:
desc: "Classify unreachable code as tracked / untracked / dynamic (tools/reachaudit). Wraps task deadcode with provenance and tracker status."
summary: |
deadcode says a function is unreachable. reachaudit says whether that
is a known gap, a forgotten one, or an artifact of runtime loading
(yaegi, reflection) that must never be deleted.
Two report sections, because a dead whole package and a dead symbol
inside a live one are different failure modes: "unreachable-*" is a
package no shipped binary imports at all; "in-package-*" is a symbol
dead inside a package that IS shipped -- the ChatCourier/Dispatch
shape, where the feature is wired everywhere except its own call site.
Both carry the same tracked/untracked/dynamic classification.
--refresh re-runs the analysis. Without it the tool reuses
/tmp/reachaudit-deadcode-<sha>.txt with no staleness check beyond HEAD
and a dirty-tree check, which will happily report last week's tree
against today's code if HEAD hasn't moved.
--json PATH and --md PATH write the same findings as structured data or
a Markdown report, in addition to the terminal summary.
cmds:
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
docs:site:
desc: "Build the documentation site into ./site (MkDocs). --strict, so a dead internal link fails the build."
summary: |
Publishes docs/ minus the subtrees held back in mkdocs.yml's
exclude_docs. Requires mkdocs-material:
pip install --user mkdocs-material
Distinct from docs:check, which verifies the generated contract data
rather than the site.
cmds:
- mkdocs build --strict
docs:serve:
desc: "Serve the documentation site locally with live reload on :8000."
cmds:
- mkdocs serve
- cd tools && golangci-lint run ./...
ui:deps:
desc: Install the dashboard's node dependencies (ui/node_modules is gitignored)
desc: Install dashboard dependencies
internal: true
# Parallel UI checks must share one dependency install.
run: once
dir: ui
cmds:
- npm install --no-audit --no-fund
- pnpm install --frozen-lockfile
ui:
desc: Build the dashboard into ui/dist (committed; the Go build embeds it)
desc: Build the dashboard into ui/dist, which the Go build embeds
dir: ui
deps: [ui:deps]
cmds:
- npm run build
ui:check:
desc: Rebuild the dashboard into a temporary directory and reject a stale ui/dist
summary: |
ui/dist is committed because the Go build embeds it, so it is a generated
source file. Nothing else in the gate reads it and `task ui` rewrites it
in place, so before this a change to ui/src that landed without the
rebuilt bundle was invisible -- and two agents in two worktrees could each
"pass" while producing different dashboards.
Builds somewhere temporary and compares, never rewriting the committed
artifact, which is the rule docs:check already follows for the contract
reference. A gate that rebuilt ui/dist in place would bless an unintended
UI change with no reviewer ever seeing it.
Fix a failure with `task ui`, then commit the rebuilt bundle in the same
commit as the source change that caused it.
Declares ui:deps like `ui` and `test:ui` do, so a fresh clone works; that
means the gate runs `npm install` once for each dependent. Task's
sources/generates up-to-date check does not apply to a node_modules
directory, so the guard against that is a follow-up, not a claim here.
deps: [ui:deps]
cmds:
- bash tools/uidist.sh check
- pnpm run build
test:ui:
desc: Test and type-check the dashboard
dir: ui
# ui:deps so a fresh clone fails on a real error rather than on a missing
# node_modules, which is gitignored and installed by nothing else.
deps: [ui:deps]
cmds:
- npm test
- npm run typecheck
- pnpm test
- pnpm run typecheck
# A test event for the capture intake, so the Events surfaces can be driven by
# hand without a real webhook source. See tools/webhook-send.sh --list.
webhook:send:
desc: Send a test event to the dashboard's capture intake (--help for kinds)
bench:prreview:
desc: Run the PR review benchmark on the configured models and write docs/benchmarks/pr-review-*.md (-- -model ALIAS -judge-model REF; --help for flags)
cmds:
- bash tools/webhook-send.sh {{.CLI_ARGS}}
- go run ./cmd/archied prbench {{.CLI_ARGS}}
dev:
desc: "Develop: archied live-reload + archie-gateway + archie-state-store + archie-ui + Vite HMR together. Open http://localhost:5173"
summary: |
Runs the dev loop in one terminal:
desc: Run development services and Vite at http://localhost:5173
deps: [dev:daemon, dev:gateway, dev:messaging, dev:state-store, dev:dashboard, dev:ui]
* air rebuilds and restarts archied on Go changes
* archie-gateway serves ChatContract on 127.0.0.1:8585 (archied
and archie-ui dial it; neither embeds a gateway)
* archie-state-store owns archie.db on 127.0.0.1:9091, loopback,
no token (deployments/dev.toml); archied,
archie-gateway and archie-ui dial it -- none owns
the DB in-process
(docs/prds/state-store-contract.md §12 step 7)
* state admin read-only PocketBase surface over archie.db on
127.0.0.1:8686 (view collections only; the gRPC
contract stays the only writer). Served by the
archie-state-store process, not a sixth one.
* archie-ui serves the dashboard on 127.0.0.1:8484 from the
embedded dist (deployments/dev.toml). After the
UI cutover (archie-core-8cda.5.4) archied runs no
dashboard listener: this is what :8484 is.
* vite serves the dashboard with hot reload on :5173,
proxying /api and /events through to archie-ui
on :8484
dev:tls:
desc: Issue the development CA and service certificates deployments/dev.toml names
status:
- test -f tmp/dev-tls/archie-ui.pem
cmds:
- |
# Task containers reach the State Store over the Docker bridge, which
# services may only do over TLS.
set -eu
d=tmp/dev-tls
mkdir -p "$d"
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 3650 \
-subj /CN=archie-dev-ca -keyout "$d/ca-key.pem" -out "$d/ca.pem" 2>/dev/null
for s in archied archie-gateway archie-messaging archie-state-store archie-ui; do
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 3650 \
-subj "/CN=$s" -addext "subjectAltName=DNS:$s" -addext extendedKeyUsage=serverAuth,clientAuth \
-CA "$d/ca.pem" -CAkey "$d/ca-key.pem" -keyout "$d/$s-key.pem" -out "$d/$s.pem" 2>/dev/null
done
The gRPC ports come from [services.state].listen and [services.gateway].listen in
deployments/dev.toml, each paired with the target that dials it. Move a pair there
together when a port is already taken on the host.
dev:postgres:
desc: Start PostgreSQL and wait for readiness
cmds:
- docker compose up -d postgres
- |
set -eu
for _ in $(seq 1 60); do
status=$(docker inspect --format '{{`{{.State.Health.Status}}`}}' "$(docker compose ps -q postgres)" 2>/dev/null || true)
if [ "$status" = "healthy" ]; then
exit 0
fi
sleep 1
done
echo "postgres did not become healthy within 60s" >&2
exit 1
Open http://localhost:5173 -- not :8484. The Vite server is the one with
hot reload; :8484 serves the last built dist/ and will look stale.
Ctrl-C stops all five.
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
dev:wait-state:
internal: true
cmds:
- |
# Services read their settings from the State Store at boot and exit
# if it is not up yet, so wait for its port ([services.state] in
# deployments/dev.toml).
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
exit 1
dev:daemon:
desc: archied only, live-reloading via air (prefer `task dev`)
desc: Run archied with live reload
cmds:
- task: dev:wait-state
- air -build.args_bin="-config-overlay,deployments/dev.toml"
dev:dashboard:
desc: archie-ui only, no live-reload (prefer `task dev`)
desc: Run the dashboard backend
cmds:
- go run ./cmd/archie-ui -config-overlay deployments/dev.toml
dev:state-store:
desc: archie-state-store only, no live-reload (prefer `task dev`)
# -admin-addr serves the read-only operator dashboard over the same
# archie.db this process already owns. It is a flag rather than a config
# key for the same reason -ready-addr is: the address is a property of
# how this process was launched, not of the deployment's config document.
desc: Run the State Store with development PostgreSQL
deps: [dev:postgres, dev:tls]
cmds:
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml -admin-addr 127.0.0.1:8686
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml
dev:gateway:
desc: archie-gateway only, no live-reload (prefer `task dev`)
# The overlay carries [services.state].target, which archie-gateway
# requires (openStateStoreAdapter fails closed on an empty target).
# Without it `task dev` leaves the gateway dialling whatever the
# developer's installed config names, or unable to start at all, while
# archied, archie-ui and the state store all dial 127.0.0.1:9091.
desc: Run the development Gateway
cmds:
- task: dev:wait-state
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
dev:messaging:
desc: Run the development Messaging Service
cmds:
- task: dev:wait-state
- go run ./cmd/archie-messaging -config-overlay deployments/dev.toml
dev:ui:
desc: Vite dev server only, expects archie-ui already running (prefer `task dev`)
desc: Run Vite (requires the dashboard backend)
dir: ui
cmds:
- npm install --no-audit --no-fund
- npm run dev
- pnpm install
- pnpm run dev
dev:mobile:
desc: Serve the dashboard on your LAN (token-protected) for phone viewing
summary: |
Starts archie-ui with a LAN-reachable [web] bind and a minted dashboard
token, printing the URL (LAN IP + token) and a QR code to scan. After
the UI cutover the dashboard is archie-ui's process: this task starts
archie-ui only. Run the daemon separately (task dev, or archied) for
actual archie operation -- two daemons sharing the bot identity would
double-poll the forge.
The frontend served is the embedded dist, so run `task ui` if you
changed the frontend. The token file is the path archied used to mint
before the cutover, so an existing phone setup keeps its token.
deps:
- ui
e2e:up:
desc: Start the local stack without Docker (PostgreSQL 18, services, Vite) and seed it
cmds:
- cmd: |
IP=$(hostname -I | awk '{print $1}')
TOKEN_FILE="${XDG_DATA_HOME:-$HOME/.local/share}/archie/web-token"
go run ./cmd/archie-ui -listen 0.0.0.0:8484 -token-file "$TOKEN_FILE" &
UI_PID=$!
sleep 2
TOKEN=$(cat "$TOKEN_FILE" 2>/dev/null)
URL="http://$IP:8484/?t=$TOKEN"
echo "Phone URL: $URL"
echo "$URL" | qrencode -t ANSIUTF8
trap "kill $UI_PID 2>/dev/null" EXIT
wait $UI_PID
- bash e2e/stack.sh start
- bash e2e/seed.sh
e2e:down:
desc: Stop the local e2e stack
cmds:
- bash e2e/stack.sh stop
e2e:check:
desc: List browser checks; use -- all or -- CHECK to run, add --headed to watch
cmds:
- node e2e/run.cjs {{.CLI_ARGS}}
canary:rehearse:
# Local rehearsal only: spins up its own registry, database and host, and
# is deliberately absent from check and CI.
desc: Rehearse the release-canary loop on a throwaway local host (needs docker; never part of the gate)
cmds:
- sh tools/canary-rehearse.sh
build:
desc: Build archie services and agent binaries
# Version stamping used to live only in Dockerfile.archied, so any build
# from source -- including a host deployment -- reported "dev" for
# both components and /version was useless there. Derive the same
# -X values from the release tags so a source build is stamped too.
# git describe (without --abbrev=0) yields 1.7.0-2-gbb54786 when HEAD is
# past the tag, which is the honest answer for a mid-cycle build.
deps: [ui]
vars:
GATEWAY_VERSION:
sh: git describe --tags --match 'archied/v*' 2>/dev/null | sed 's|^archied/v||' || echo dev
RUNTIME_VERSION:
sh: git describe --tags --match 'archie/v*' 2>/dev/null | sed 's|^archie/v||' || echo dev
GATEWAY_VERSION: '{{.GATEWAY_VERSION | default .VERSION}}'
RUNTIME_VERSION: '{{.RUNTIME_VERSION | default .VERSION}}'
SERVICE_LDFLAGS: >-
-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary
-X github.com/samcharles93/archie-core/internal/buildinfo.Version={{.GATEWAY_VERSION}}
-X github.com/samcharles93/archie-core/internal/buildinfo.Runtime={{.RUNTIME_VERSION}}
sources:
- Taskfile.yml
- "**/*.go"
# Files the binaries embed.
- "internal/**/*.sql"
- "internal/**/*.yaml"
- "internal/**/*.json"
- "internal/**/*.tpl"
- "internal/**/*.md"
- go.mod
- go.sum
# ui/dist is committed and embedded by ui/embed.go (//go:embed all:dist),
# so it is a build input even though no .go file names it.
- "ui/dist/**"
generates:
- "{{.BIN_DIR}}/archied"
@@ -465,132 +258,75 @@ tasks:
- "{{.BIN_DIR}}/archie-messaging"
- "{{.BIN_DIR}}/archie-agent"
cmds:
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archied ./cmd/archied
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-gateway ./cmd/archie-gateway
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-state-store ./cmd/archie-state-store
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-ui ./cmd/archie-ui
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-messaging ./cmd/archie-messaging
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
# One flag set for every service, matching the release workflow, so each
# binary reports the same version.
- for: [archied, archie-gateway, archie-state-store, archie-ui, archie-messaging]
cmd: go build -trimpath -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
- go build -trimpath -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
test:
desc: Run the Go test suite
desc: Run Go tests; the release gate passes TEST_FLAGS=-count=1
cmds:
- go test ./... -count=1
- go test {{.TEST_FLAGS | default "-short"}} ./...
test:tools:
desc: Run the nested tools module suite, refusing to rewrite its go.mod
summary: |
tools/go.mod replaces the root module, so its build list must satisfy
the root module's requirements. When the root moves on, the tools module
goes stale and any plain go command there rewrites tools/go.mod and
tools/go.sum to catch up, leaving an unrelated dirty diff.
-mod=readonly is explicit because a developer's global GOFLAGS=-mod=mod
overrides the toolchain default and re-enables the silent rewrite.
Fix a failure here with: go -C tools mod tidy
image:agent:
desc: Build the agent image stamped with this checkout's version
# Compose owns the image build; this only supplies the version, which a
# plain `docker build` has no way to learn from a context that excludes .git.
cmds:
- go -C tools test -mod=readonly ./... -count=1
- RUNTIME_VERSION={{.VERSION}} docker compose build agent
check:
desc: "Full quality gate: fmt, proto, docs, vet, lint, build, test, tools tests, ui tests and bundle"
desc: Run the full quality gate
# Finish mutations before starting parallel checks.
cmds:
# Node packages land under ui/, which `go test ./...` walks: installing
# them while the parallel checks scan the tree makes a lockfile update
# delete Go sources mid-walk. Install first, then fan out. Every Go step
# embeds ui/dist, so the dashboard is built before any of them.
- task: ui
- task: fmt
- task: proto:lint
- task: proto:check
- task: docs:check
- task: docs:prds
# Release notes are generated from the changelogs the release process
# already freezes. Left out of the gate, a changelog edit would land
# while the published notes silently lag behind it.
- task: db:check
- task: check:readonly
check:readonly:
internal: true
deps:
- task: proto:lint
- task: news:check
# The public-docs artifact is what the site renders, so a page edit that
# does not reach it publishes a site that disagrees with the repository.
- task: docs:artifact:check
- task: vet
- task: lint
- task: build
- task: test
# The tools module is not covered by ./... from the root; without this
# its dependency drift is only ever discovered by a command that
# silently repairs it.
- task: test:tools
# The dashboard's suite runs here too. Left out of the gate it rots
# silently: nothing else executes it, so a broken DOM primitive ships.
- task: test:ui
# ...and so is the bundle that suite is built from. ui/dist is committed
# and embedded; nothing else checks it against ui/src, and `task ui`
# rewrites it in place, so a forgotten rebuild used to leave no trace in
# the gate at all.
- task: ui:check
contract:
desc: "Report contract conformance: declared surfaces, their consumers, and the drift between them"
summary: |
Walks every declared contract surface -- the two gRPC services, the
dashboard HTTP API -- and classifies each subject as consumed,
declared-unconsumed, undeclared, or a stale declaration.
ADVISORY, and deliberately NOT part of `task check`, matching
tools/reachaudit. The surfaces are discovered by scanning source text:
the .proto files, the adapter bodies that call the generated client, the
route registrations in internal/webui, and the path literals under
ui/src. That makes it useful for a periodic survey and unsafe as a gate
-- a rename or a reformat elsewhere in the tree can change its output
without anything being wrong, and it has already produced a batch of
false "unconsumed" readings once when the dashboard's request helper was
renamed.
Read the findings as a prompt to go and check, not as a verdict. To make
it fail on an undeclared or stale entry, pass --strict by hand:
go -C tools run ./contractaudit --repo-root .. --strict
See docs/prds/contract-conformance-audit.md.
cmds:
- go -C tools run ./contractaudit --repo-root ..
release:preview:
desc: "Show the release notes that would be generated (VERSION=1.2.0)"
cmds:
- tools/release.sh --version {{.VERSION}} --dry-run
requires:
vars: [VERSION]
release:prepare:
desc: "Write the generated notes into CHANGELOG.md, uncommitted, for editing (VERSION=1.2.0)"
cmds:
- tools/release.sh --version {{.VERSION}} --prepare
requires:
vars: [VERSION]
release:
desc: "Freeze the edited changelog into a release commit and tag (VERSION=1.2.0). Run release:prepare first."
cmds:
- tools/release.sh --version {{.VERSION}} --tag
desc: "Turn [Unreleased] into a release, then commit and tag it (RELEASE=major|minor|patch|1.2.3)"
requires:
vars: [VERSION]
clean:
desc: Remove build artifacts
vars: [RELEASE]
cmds:
- rm -rf {{.BIN_DIR}}
docker-build:
desc: Build the archie-agent sandbox image
cmds:
- docker compose build agent
docker-up:
desc: Start the optional external NATS service via docker compose
cmds:
- docker compose up -d nats
docker-down:
desc: Stop the docker compose stack
cmds:
- docker compose down
docker-logs:
desc: Follow the NATS container logs
cmds:
- docker compose logs -f nats
- |
set -euo pipefail
die() { echo "release: $*" >&2; exit 1; }
[ "$(git rev-parse --abbrev-ref HEAD)" = main ] || die "releases are cut from main"
[ -z "$(git status --porcelain)" ] || die "the working tree is dirty"
last="$(git tag --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || true)"
IFS=. read -r major minor patch <<<"${last#v}"
case "{{.RELEASE}}" in
major) version="$((major + 1)).0.0" ;;
minor) version="$major.$((minor + 1)).0" ;;
patch) version="$major.$minor.$((patch + 1))" ;;
*) version="$(echo "{{.RELEASE}}" | sed 's/^v//')" ;;
esac
echo "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$' || die "$version is not a version"
! git rev-parse -q --verify "refs/tags/v$version" >/dev/null || die "v$version already exists"
awk '/^## \[Unreleased\]/ { u = 1; next } u && /^## \[/ { exit } u && /^- / { found = 1 } END { exit !found }' CHANGELOG.md ||
die "[Unreleased] in CHANGELOG.md has no entries"
awk -v hdr="## [$version] - $(date -u +%F)" '{ print } /^## \[Unreleased\]/ { print ""; print hdr }' CHANGELOG.md >CHANGELOG.md.tmp
mv CHANGELOG.md.tmp CHANGELOG.md
go -C tools run -mod=readonly ./newsgen --repo-root ..
git add CHANGELOG.md docs/news
git commit -q -m "chore(release): v$version"
git tag -a "v$version" -m "v$version"
echo "tagged v$version"
+333
View File
@@ -0,0 +1,333 @@
# Workflow definitions
A workflow is a YAML document: an id, what it declares to whatever starts it,
and an ordered list of steps. Definitions are stored in the control plane's
`workflow-definitions` resource and edited on the dashboard's Workflows page
(the Canvas and YAML tabs edit the same document). The shipped workflows are in
`internal/domain/workflow/shipped/`.
The server is the authority. It serves the step vocabulary, including each step
type's settings schema, in the `workflow-definitions` catalog entry
(`x-step-types`), and validates every definition when it is saved. This file
describes that vocabulary; when they disagree, the catalog wins.
```yaml
id: implement
repository: required
inputs:
pr_number: {type: number, required: true}
steps:
- type: repo.prepare
- id: plan
type: agent.run
settings:
read_only: true
mission: |
Plan this change: {{ task.prompt }}
- id: build
type: agent.run
settings:
gate: repository
mission: "Implement it following this plan: {{ steps.plan.summary }}"
- type: repo.commit
settings: {message: "{{ task.title }}", push: true, if_empty: complete}
- type: repo.open-pr
settings: {body: "{{ steps.build.summary }}"}
```
## The workflow
| Field | Type | Meaning |
|---|---|---|
| `id` | text | The workflow's name. Required, unique. |
| `steps` | list | The steps, run in order. At least one. |
| `repository` | `required` \| `optional` \| `none` | `required` (the default) clones the task's repository into a worktree. `optional` clones one when the run names a repository and uses a scratch workspace otherwise. `none` never clones; only steps that run without a repository may be used. |
| `inputs` | mapping | Named, typed values whatever starts the run must supply: `{type, required}`, where type is `string`, `number`, `bool`, `object`, `array` or `any`. Steps read them as `{{ inputs.<name> }}`. |
| `outputs` | mapping | Named, typed results the run writes once each (same shape as inputs). A required output the run never writes parks it. A calling workflow reads them. |
| `profile` | text | The container profile (`[containers.profiles]`) the run's agents use. Resolved when the task is dispatched. |
| `identity` | text | The identity every run acts as, whatever started it. Empty runs as the starter. |
| `needs` | mapping | Harness capabilities the run requires: `captures` (bool), `gate_retries` (number). Declared outputs imply `captures`. |
## A step
| Field | Type | Meaning |
|---|---|---|
| `type` | text | The step type (below). |
| `id` | text | Names the step so later steps can read its result. Unique in the workflow; letters, digits, `-` and `_`. The run records the step under this name. |
| `settings` | mapping | The step type's settings. String settings may contain references. |
| `when` | condition | Skip the step unless the condition holds. |
| `on_failure` | `park` \| `continue` | `park` (the default) stops the run for an operator. `continue` records the failure and moves on. |
| `retry` | mapping | `attempts` (1 to 10) and `backoff` (a duration such as `30s`). A failed step runs again before `on_failure` applies. |
| `parallel` | mapping | Instead of `type`: named branches, each a list of steps, run at the same time. |
### References
Any string setting may contain `{{ path }}`, replaced when the step runs:
| Path | Value |
|---|---|
| `task.title`, `task.body` | The issue or chat request. |
| `task.prompt` | The title and body framed for an agent mission. |
| `task.repository` | `owner/name`. |
| `task.kind` | What the task came from, as prose: `GitHub issue` or `chat-originated task`. |
| `task.issue`, `task.pr` | Issue and pull request numbers. |
| `task.plan` | The plan a `workflow.approve` step handed over (an approved PRD). |
| `task.review` | The review comments a remediation round addresses. |
| `inputs.<name>` | A declared input; an undeclared one is refused at save. |
| `steps.<id>.summary` | What an earlier step reported, e.g. an agent's finish summary or a gate's output. |
| `steps.<id>.result.<field>` | A field of an earlier agent's structured result, or an output of an earlier `workflow.call` that waits. A field the agent's `result` schema or the callee's `outputs` does not declare is refused at save. |
Only earlier steps may be referenced; a reference to a later or unknown step is
refused when the definition is saved. A value that does not exist at run time
(for instance, a step that was skipped) renders empty.
### Conditions
`when` is a reference path, written without braces:
- `steps.assess.result.fit` holds when the value is true, a non-empty string other than `false`, or a non-zero number.
- `!steps.assess.result.fit` holds when it does not.
- `steps.classify.result.workflow == tdd` and `!=` compare the value as text.
### Parallel branches
```yaml
- id: research
parallel:
code: [{id: code, type: agent.run, settings: {mission: ..., read_only: true}}]
docs: [{id: docs, type: agent.run, settings: {mission: ..., read_only: true}}]
- type: agent.run
settings: {mission: "{{ steps.code.summary }} {{ steps.docs.summary }}"}
```
Branches share one worktree, so only read-only `agent.run` and `workflow.call`
steps may run in them. A branch sees the steps before the parallel step and its
own earlier steps, never a sibling's. Every branch's results are visible after
it. Parallel steps do not nest, and need at least two branches.
### How a run ends
A run ends at the first step that sets an outcome: `workflow.finish`,
`workflow.handoff`, `workflow.approve`, `repo.open-pr`, `repo.commit` with
`if_empty: complete`, or `review.reply`. A run that reaches the end of its steps
completes, with the last step's summary as its detail. A step that fails parks
the run unless it continues on failure.
A parked run can be retried from a top-level step instead of from the start.
The steps before it are skipped and their results stay available to
references. The resume point is named by the step's id (else its type), so
give an id to any step whose type appears twice. A run with a repository
resumes only on its pushed branch: work an earlier step did not push is not
there.
## Step types
### `agent.run`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `extra_rules` | text | Appended to the agent system prompt. |
| `gate` | `repository` \| `test-failure` | Hold the agent to the repository gate before it may finish; test-failure requires the tests to fail. |
| `mission` | text | What the agent is asked to do. May reference {{ task.* }}, {{ inputs.* }} and {{ steps.<id>.* }}. |
| `protect_tests` | bool | Write-block the repository test files. |
| `read_only` | bool | Restrict the agent to read-only tools. |
| `result` | mapping | A JSON Schema object the agent must return; later steps read it as steps.<id>.result. |
| `model` | text | The model alias that runs the agent, e.g. default or fast. Empty means default. |
### `command.run`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `level` | `error` \| `warn` | error stops the run on a failing command; warn reports it and continues. |
| `run` | list of mapping | The commands to run in order; the first failure ends the step. |
### `repo.commit`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `if_empty` | `fail` \| `skip` \| `complete` | fail stops the run, skip moves on, complete closes the issue and ends the run. |
| `message` | text | The commit message. |
| `push` | bool | Push the branch after committing. |
| `reference` | `Fixes` \| `Implements` \| `Refs` | How the commit links to the task issue. |
Hooks never run. The commit is created by go-git, which ignores `.git/hooks`
and `core.hooksPath`, and the agent never runs git, so `pre-commit`,
`commit-msg` and `prepare-commit-msg` in the checkout are inert files. A
repository whose rules live only in a hook — a formatter, a secret scanner,
commitlint, a DCO trailer — gets a commit that does not satisfy them: the run
reports success and the pull request fails the check afterwards. Put the same
commands in `command.run` or the repository gate, which both run in the task
container before this step.
### `repo.open-pr`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `body` | text | The pull request description. |
| `review` | bool | Review the change first; a blocking finding parks the task instead of opening the PR. |
### `repo.prepare`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `branch` | `fresh` \| `task` | fresh starts a new branch from the base; task resumes the branch this task pushed. |
### `repo.tooling`
_needs a repository._
No settings. It runs the repository policy's `tooling` commands, in order, in
the task worktree — the installs a gate needs and the container does not ship
(protoc plugins, linters, generators). A repository that declares none installs
nothing and the step succeeds. Place it after `repo.prepare` and before any
`gate.*` step: a failing install fails the step with the command and its output
and says the gate did not run, so a missing toolchain is not read as a red
repository.
### `gate.diff-rules`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `rules` | list of mapping | Patterns the change must not match. |
### `gate.repository`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `expect` | `pass` \| `test-failure` | pass requires every gate command to pass; test-failure requires the test command to fail. |
| `repair` | bool | Let the builder fix a failing gate before the step fails. |
### `forge.close-issue`
_runs without a repository._
No settings.
### `forge.comment`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `body` | text | The comment text. |
| `on` | `issue` \| `pr` | Comment on the issue or the pull request. Empty means issue. |
### `message.send`
_runs without a repository._
Sends text to one chat on a messaging channel the workflow's organisation owns,
and a package's workflow may not send. A test run records the message instead
of sending it.
| Setting | Type | Meaning |
|---|---|---|
| `channel` | text | The messaging channel to send through. |
| `chat_id` | text | The channel's identifier for the chat. |
| `text` | text | The message. References are filled in. |
A scheduled message is a schedule bound to a workflow whose only step is
`message.send`.
### `workflow.approve`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `plan` | text | What the operator decides on; the next workflow reads it as task.plan. |
| `then` | text | The workflow the task runs once approved. |
### `review.pr`
_needs a repository._
No settings.
### `review.reply`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `body` | text | The reply to the review. |
### `review.start-round`
_needs a repository._
No settings.
### `workflow.call`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `inputs` | mapping | Callee input names mapped to scalar literals or `inputs.<name>` references to caller inputs. |
| `outputs` | mapping | Callee output names mapped to `outputs.<name>` references to caller outputs; requires `wait: true`. |
| `wait` | bool | Wait for the child run to finish before continuing. |
| `workflow` | text | The workflow to start as a child run. |
The step must declare an `id`: the step's id is the key of the call it starts,
so a retry of that call site returns the child already started instead of
starting a second one.
### `workflow.finish`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `detail` | text | What the operator reads about the outcome. |
| `status` | `completed` \| `parked` \| `waiting_approval` \| `declined` | How the run ends. Empty means completed. |
### `workflow.handoff`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `detail` | text | Why the task was handed off. |
| `workflow` | text | The workflow the task is requeued under. |
`command.run` commands are `{name, argv, expect_failure}`: `argv` is the
program and its arguments, and `expect_failure` requires a non-zero exit.
`gate.diff-rules` rules are `{id, level, pattern, path, exclude_path, message}`:
`level` (`error` blocks, `warn` reports) and `pattern` (an RE2 expression matched
against each added line) are required; `path` and `exclude_path` are RE2
expressions that limit which files the rule applies to.
## What starts a workflow
- **Issues**, by label: `bug` runs `tdd`, `feature` runs `feasibility`, anything
else runs `triage`, which classifies it and hands off.
- **Event bindings**: a webhook source mapped onto a workflow and its inputs
(Events page).
- **Schedules**: each firing is captured on the reserved `schedule` source as
a `Schedule fired` event (`schedule_id`, `name`, `scheduled_for`,
`fired_at`). A schedule trigger is a binding on that source using the
`schedule-fired` mapping, filtered to one `schedule_id`. A firing starts at
most one task per binding.
- **Playbooks**: a trigger (issue kind and labels) and actions that dispatch
workflows.
- **Other workflows**: `workflow.call` (a child run), `workflow.handoff` (the
same task, requeued), `workflow.approve` (once approved).
- **By hand**: the New task form, or Run on the Workflows page.
The canvas Start node lists the triggers of each workflow.
+9
View File
@@ -0,0 +1,9 @@
package configtemplate
import _ "embed"
// Changelog is the verbatim contents of CHANGELOG.md, so a binary carries the
// release notes for the version it was built as.
//
//go:embed CHANGELOG.md
var Changelog string
-108
View File
@@ -1,108 +0,0 @@
package main
import (
"go/ast"
"go/parser"
"go/token"
"path/filepath"
"strconv"
"strings"
"testing"
)
func TestCommandBoundary(t *testing.T) {
paths, err := filepath.Glob("*.go")
if err != nil {
t.Fatal(err)
}
for _, path := range paths {
if !strings.HasSuffix(path, "_test.go") && path != "main.go" {
t.Errorf("cmd/archie-agent contains substantive production file %q; runtime ownership belongs in internal/app/agentworker", path)
}
}
file, err := parser.ParseFile(token.NewFileSet(), "main.go", nil, 0)
if err != nil {
t.Fatal(err)
}
const (
projectInternal = "github.com/samcharles93/archie-core/internal/"
appImport = projectInternal + "app/agentworker"
)
appIdent := "agentworker"
for _, imported := range file.Imports {
path, err := strconv.Unquote(imported.Path.Value)
if err != nil {
t.Fatal(err)
}
if strings.HasPrefix(path, projectInternal) && path != appImport {
t.Errorf("cmd/archie-agent imports substantive internal package %q; only %q is allowed", path, appImport)
}
if path == appImport && imported.Name != nil {
if imported.Name.Name == "." || imported.Name.Name == "_" {
t.Errorf("cmd/archie-agent imports %q with unsupported alias %q", appImport, imported.Name.Name)
} else {
appIdent = imported.Name.Name
}
}
}
allowedFunctions := map[string]bool{
"main": true,
"run": true,
"runCommand": true,
"natsConnectionSettings": true,
}
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if !ok {
continue
}
if function.Recv != nil || !allowedFunctions[function.Name.Name] {
t.Errorf("cmd/archie-agent main.go declares unexpected function %q; orchestration belongs in internal/app/agentworker", function.Name.Name)
}
delete(allowedFunctions, function.Name.Name)
}
for name := range allowedFunctions {
t.Errorf("cmd/archie-agent main.go is missing intended process function %q", name)
}
var runFunction *ast.FuncDecl
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if ok && function.Name.Name == "run" {
runFunction = function
break
}
}
if runFunction == nil {
t.Fatal("cmd/archie-agent has no run function")
}
workerCalls := 0
ast.Inspect(runFunction.Body, func(node ast.Node) bool {
call, ok := node.(*ast.CallExpr)
if !ok {
return true
}
callee, ok := call.Fun.(*ast.Ident)
if !ok || callee.Name != "runCommand" {
return true
}
for _, argument := range call.Args {
selector, ok := argument.(*ast.SelectorExpr)
if !ok || selector.Sel.Name != "Run" {
continue
}
pkg, ok := selector.X.(*ast.Ident)
if ok && pkg.Name == appIdent {
workerCalls++
}
}
return true
})
if workerCalls != 1 {
t.Fatalf("cmd/archie-agent run passes agentworker.Run to runCommand %d times, want exactly 1", workerCalls)
}
}
+111 -1
View File
@@ -8,15 +8,30 @@ import (
"fmt"
"io"
"log/slog"
"net"
"os"
"os/signal"
"strings"
"syscall"
"github.com/samcharles93/archie-core/internal/app/agentworker"
"github.com/samcharles93/archie-core/internal/infrastructure/egress"
"github.com/samcharles93/archie-core/internal/logging"
)
type workerRunner func(context.Context, agentworker.Settings, *slog.Logger) error
// runHold blocks until signalled and exits 0. It is the keepalive for a Kit
// container that runs no worker: the agent binary is archie's own and is
// mounted into every Kit, so the container needs no binary the image may not
// ship, and holds no environment of its own.
func runHold() int {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done()
return 0
}
func main() {
os.Exit(run())
}
@@ -26,17 +41,33 @@ func run() int {
}
func runCommand(args []string, getenv func(string) string, stderr io.Writer, runWorker workerRunner) int {
if len(args) > 0 && args[0] == "hold" {
return runHold()
}
if len(args) > 0 && args[0] == "relay" {
return runRelay(args[1:], stderr, agentworker.RunRelay)
}
if len(args) > 0 && args[0] == "mcp" {
return runMCP(args[1:], stderr, agentworker.RunCaptureMCP)
}
flags := flag.NewFlagSet("archie-agent", flag.ContinueOnError)
flags.SetOutput(stderr)
natsURLFlag := flags.String("nats-url", "", "NATS server URL (defaults to NATS_URL)")
stateStoreURLFlag := flags.String("state-store-url", "", "State Store gRPC target (defaults to STATE_STORE_URL; required -- the legacy NATS storerpc path is deleted)")
stateStoreTokenFlag := flags.String("state-store-token", "", "State Store bearer token (defaults to STATE_STORE_TOKEN)")
showVersion := flags.Bool("version", false, "print the version and exit")
if err := flags.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
return 0
}
return 2
}
// The release and its updater read this line to prove a shipped
// archie-agent belongs to the release being installed.
if *showVersion {
fmt.Printf("archie-agent %s\n", agentworker.Version())
return 0
}
natsURL, natsToken := natsConnectionSettings(*natsURLFlag, getenv)
if natsURL == "" {
@@ -45,7 +76,7 @@ func runCommand(args []string, getenv func(string) string, stderr io.Writer, run
return 1
}
log := slog.New(slog.NewJSONHandler(stderr, nil))
log := slog.New(logging.WithTrace(slog.NewJSONHandler(stderr, nil)))
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
@@ -68,6 +99,10 @@ func runCommand(args []string, getenv func(string) string, stderr io.Writer, run
NATSToken: natsToken,
StateStoreTarget: stateStoreURL,
StateStoreToken: stateStoreToken,
StateStoreCA: []byte(getenv("STATE_STORE_CA")),
ModelProxy: getenv(egress.ModelProxyEnv),
ModelProxyHosts: egress.ParseHosts(getenv(egress.ModelProxyHostsEnv)),
ModelProxyCA: getenv(egress.ModelProxyCAEnv),
}, log); err != nil {
return 1
}
@@ -81,3 +116,78 @@ func natsConnectionSettings(flagURL string, getenv func(string) string) (url, to
}
return url, getenv("NATS_TOKEN")
}
type relayServer func(ctx context.Context, forwards map[string]string) error
// runRelay is the sandbox egress relay: the container on both a sandbox's
// isolated network and the host-reachable one, forwarding a fixed set of
// ports to the proxy, NATS and the State Store.
func runRelay(args []string, stderr io.Writer, serve relayServer) int {
flags := flag.NewFlagSet("archie-agent relay", flag.ContinueOnError)
flags.SetOutput(stderr)
forwards := map[string]string{}
flags.Func("forward", "listen=target: forward connections on listen to target (repeatable)", func(v string) error {
listen, target, ok := strings.Cut(v, "=")
if !ok || listen == "" || target == "" {
return fmt.Errorf("%q is not listen=target", v)
}
if _, _, err := net.SplitHostPort(listen); err != nil {
return fmt.Errorf("listen address %q: %w", listen, err)
}
if _, _, err := net.SplitHostPort(target); err != nil {
return fmt.Errorf("target %q: %w", target, err)
}
if _, dup := forwards[listen]; dup {
return fmt.Errorf("listen address %q is forwarded twice", listen)
}
forwards[listen] = target
return nil
})
if err := flags.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
return 0
}
return 2
}
if len(forwards) == 0 {
fmt.Fprintln(stderr, "error: at least one -forward is required")
flags.Usage()
return 1
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := serve(ctx, forwards); err != nil {
fmt.Fprintln(stderr, "error:", err)
return 1
}
return 0
}
type mcpServer func(ctx context.Context, specPath, capturesPath string) error
// runMCP serves a stage's capture tools to a harness over stdio. The
// harness starts it, so it runs as the harness user and holds no secrets.
func runMCP(args []string, stderr io.Writer, serve mcpServer) int {
flags := flag.NewFlagSet("archie-agent mcp", flag.ContinueOnError)
flags.SetOutput(stderr)
spec := flags.String("spec", "", "JSON file listing the stage's capture tools")
captures := flags.String("captures", "", "file accepted capture calls are appended to")
if err := flags.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
return 0
}
return 2
}
if *spec == "" || *captures == "" {
fmt.Fprintln(stderr, "error: -spec and -captures are required")
flags.Usage()
return 1
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := serve(ctx, *spec, *captures); err != nil {
fmt.Fprintln(stderr, "error:", err)
return 1
}
return 0
}
-134
View File
@@ -1,134 +0,0 @@
package main
import (
"bytes"
"context"
"errors"
"log/slog"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/app/agentworker"
)
func TestRunCommandPreservesCLIExitSemantics(t *testing.T) {
tests := []struct {
name string
args []string
getenv func(string) string
worker workerRunner
wantCode int
}{
{name: "help", args: []string{"-h"}},
{name: "flag parse error", args: []string{"-unknown"}, wantCode: 2},
{name: "removed consumer flag", args: []string{"-consumer", "legacy"}, wantCode: 2},
{name: "missing NATS URL", wantCode: 1},
{name: "missing state store URL", args: []string{"-nats-url", "nats://test"}, wantCode: 1},
{
name: "worker failure",
args: []string{"-nats-url", "nats://test", "-state-store-url", "127.0.0.1:9090"},
worker: func(context.Context, agentworker.Settings, *slog.Logger) error {
return errors.New("worker failed")
},
wantCode: 1,
},
{
name: "success",
args: []string{"-nats-url", "nats://test", "-state-store-url", "127.0.0.1:9090"},
worker: func(context.Context, agentworker.Settings, *slog.Logger) error {
return nil
},
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
getenv := test.getenv
if getenv == nil {
getenv = func(string) string { return "" }
}
worker := test.worker
if worker == nil {
worker = func(context.Context, agentworker.Settings, *slog.Logger) error {
t.Fatal("worker called")
return nil
}
}
if got := runCommand(test.args, getenv, &bytes.Buffer{}, worker); got != test.wantCode {
t.Fatalf("runCommand() = %d, want %d", got, test.wantCode)
}
})
}
}
func TestRunCommandRequiresNATSURL(t *testing.T) {
var stderr bytes.Buffer
called := false
code := runCommand(nil, func(string) string { return "" }, &stderr, func(context.Context, agentworker.Settings, *slog.Logger) error {
called = true
return nil
})
if code != 1 || called {
t.Fatalf("(code, worker called) = (%d, %v), want (1, false)", code, called)
}
for _, want := range []string{"error: -nats-url or NATS_URL is required", "Usage of archie-agent:"} {
if !strings.Contains(stderr.String(), want) {
t.Fatalf("stderr %q does not contain %q", stderr.String(), want)
}
}
}
func TestRunCommandMapsWorkerOutcomeToExitStatus(t *testing.T) {
workerErr := errors.New("startup failed")
tests := []struct {
name string
workerErr error
wantCode int
}{
{name: "success"},
{name: "worker failure", workerErr: workerErr, wantCode: 1},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
var stderr bytes.Buffer
code := runCommand([]string{"-nats-url", "nats://flag"}, func(string) string { return "token" }, &stderr, func(_ context.Context, settings agentworker.Settings, _ *slog.Logger) error {
if settings.NATSURL != "nats://flag" || settings.NATSToken != "token" {
t.Fatalf("settings = %#v", settings)
}
return test.workerErr
})
if code != test.wantCode {
t.Fatalf("code = %d, want %d", code, test.wantCode)
}
if test.workerErr != nil && stderr.Len() != 0 {
t.Fatalf("stderr = %q, want command not to duplicate application logging", stderr.String())
}
})
}
}
func TestNATSConnectionSettings(t *testing.T) {
getenv := func(name string) string {
switch name {
case "NATS_URL":
return "nats://nats.example:4222"
case "NATS_TOKEN":
return "test-nats-token"
default:
return ""
}
}
t.Run("container environment", func(t *testing.T) {
url, token := natsConnectionSettings("", getenv)
if url != "nats://nats.example:4222" || token != "test-nats-token" {
t.Fatalf("natsConnectionSettings() = (%q, %q)", url, token)
}
})
t.Run("flag URL takes precedence", func(t *testing.T) {
url, token := natsConnectionSettings("nats://flag.example:4222", getenv)
if url != "nats://flag.example:4222" || token != "test-nats-token" {
t.Fatalf("natsConnectionSettings() = (%q, %q)", url, token)
}
})
}
+3 -4
View File
@@ -9,7 +9,7 @@ import (
"os/signal"
"syscall"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/archiegateway"
"github.com/samcharles93/archie-core/internal/buildinfo"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
@@ -17,17 +17,16 @@ import (
func main() { os.Exit(run()) }
func run() int {
var options archied.GatewayOptions
var options archiegateway.Options
showVersion := buildinfo.RegisterVersionFlag("archie-gateway")
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Listen, "listen", "", "gateway gRPC listen address (defaults to [services.gateway].listen, else 127.0.0.1:8585)")
flag.StringVar(&options.Token, "token", "", "Bearer [REDACTED] required for a non-loopback listener (defaults to [services.gateway].target_token)")
flag.Parse()
showVersion()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := archied.RunGateway(ctx, options); err != nil {
if err := archiegateway.Run(ctx, options); err != nil {
fmt.Fprintln(os.Stderr, err)
return 1
}
+25 -111
View File
@@ -1,125 +1,39 @@
// This file enforces the objective half of the Messaging Service deletion gate
// (docs/prds/messaging-service-boundary.md, "Deletion Gate and Verification"): the
// linked binary carries no state-store, daemon, workflow, forge, gateway or
// dashboard runtime. Go imports are atomic, so a single reference to a type living
// beside a runtime relinks the runtime, and the severance holds only while
// something re-measures it. That is exactly how this package came to link the
// SQLite driver, the workflow engine and agentexec through one import of
// internal/app/controlplane (archie-core-1ng1).
// The Messaging Service reaches the State Store and the workflow engine only
// through their contracts. Go imports are atomic, so one reference relinks a
// runtime, and the boundary holds only while something re-measures it.
package main
import (
"context"
"os/exec"
"strings"
"testing"
"time"
)
const modulePath = "github.com/samcharles93/archie-core/"
// bannedCategory is one class of runtime the Messaging Service must not link.
// The names are the PRD's wording; the prefixes are how that class appears in
// this module.
type bannedCategory struct {
name string
prefixes []string
}
// deletionGate is the PRD's list, one entry per category it names. Two deliberate
// absences:
//
// - internal/channels is NOT here. The Messaging Service hosts those adapters;
// it is the process they live in, not a consumer of them.
// - internal/gatewayrpc needs no exception. It is the Gateway's contract, not
// its runtime, and it does not sit under the internal/gateway prefix -- the
// check below would catch it if it ever did.
var deletionGate = []bannedCategory{
{"state store", []string{
"modernc.org/sqlite",
modulePath + "internal/store",
}},
{"daemon runtime", []string{
modulePath + "internal/daemon",
modulePath + "internal/app/archied",
modulePath + "internal/container",
modulePath + "internal/worktree",
}},
{"workflow engine", []string{
modulePath + "internal/domain/workflow",
modulePath + "internal/agentexec",
modulePath + "internal/taskrun",
}},
{"forge client", []string{
modulePath + "internal/forge",
modulePath + "internal/forgerpc",
}},
{"gateway runtime", []string{
modulePath + "internal/gateway",
}},
{"dashboard", []string{
modulePath + "internal/webui",
}},
}
// gateExceptions are packages under a banned prefix that carry only contract,
// vocabulary or view types, so linking them is the intended end state rather
// than a tolerated leak. internal/domain/workflow/task is the Task status and
// view vocabulary the Messaging Service renders; its own dependency set holds
// none of the banned runtimes, which is what makes the exception defensible
// rather than a hole. cmd/archie-ui/architecture_test.go carries the same entry
// for the same reason.
//
// Each one must stay linked: an exception nothing needs any more is a hole in
// the fence, so this list is checked in both directions.
var gateExceptions = []string{
modulePath + "internal/domain/workflow/task",
}
// under reports whether importPath is prefix or a package below it.
func under(importPath, prefix string) bool {
return importPath == prefix || strings.HasPrefix(importPath, prefix+"/")
}
func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
listed, err := exec.CommandContext(t.Context(), "go", "list", "-deps", ".").CombinedOutput()
func TestMessagingDoesNotLinkStoreOrWorkflowRuntime(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
out, err := exec.CommandContext(ctx, "go", "list", "-deps", ".").Output()
if err != nil {
t.Fatalf("go list -deps .: %v\n%s", err, listed)
t.Fatalf("go list -deps .: %v", err)
}
linked := make(map[string]bool, len(gateExceptions))
for importPath := range strings.FieldsSeq(string(listed)) {
if excepted(importPath, linked) {
continue
}
for _, category := range deletionGate {
for _, prefix := range category.prefixes {
if !under(importPath, prefix) {
continue
}
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category.name)
linked := map[string]bool{}
for line := range strings.SplitSeq(strings.TrimSpace(string(out)), "\n") {
linked[line] = true
}
for _, pkg := range []string{
"github.com/jackc/pgx/v5/pgxpool",
"github.com/samcharles93/archie-core/internal/infrastructure/postgres",
"github.com/samcharles93/archie-core/internal/infrastructure/controlplanestore",
"github.com/samcharles93/archie-core/internal/domain/workflow",
"github.com/samcharles93/archie-core/internal/agentexec",
} {
t.Run(pkg, func(t *testing.T) {
if linked[pkg] {
t.Errorf("cmd/archie-messaging links %s: services reach each other only through contracts", pkg)
}
}
}
for _, exception := range gateExceptions {
if !linked[exception] {
t.Errorf("%s is excepted from the deletion gate but is no longer linked; drop the exception instead of leaving its prefix open", exception)
}
}
// A gate that cannot fail, and a `go list` that returns nothing usable, both
// read as a pass. This pins the one thing the loop above assumes.
if !strings.Contains(string(listed), modulePath+"cmd/archie-messaging") {
t.Fatal("go list -deps returned a list that does not even name this package: the gate asserted nothing")
})
}
}
// excepted reports whether importPath sits under an excepted package, recording
// the ones actually linked so a stale exception fails.
func excepted(importPath string, linked map[string]bool) bool {
for _, exception := range gateExceptions {
if under(importPath, exception) {
linked[exception] = true
return true
}
}
return false
}
+1 -2
View File
@@ -23,9 +23,8 @@ func run() int {
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target, else 127.0.0.1:8585)")
flag.StringVar(&options.Gateway.Token, "gateway-token", "", "bearer token presented to archie-gateway")
flag.StringVar(&options.StateStore.Target, "state-store-target", "", "archie-state-store gRPC address (defaults to [services.state].target)")
flag.StringVar(&options.StateStore.Token, "state-store-token", "", "bearer token presented to archie-state-store")
flag.StringVar(&options.Listen, "listen", "", "MessagingService gRPC listen address (defaults to [services.messaging].listen)")
flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "readiness probe timeout (default 5s)")
flag.DurationVar(&options.ShutdownTimeout, "shutdown-timeout", 0, "shutdown timeout (default 5s)")
flag.Parse()
-153
View File
@@ -1,153 +0,0 @@
package main
import (
"context"
"net"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"syscall"
"testing"
"time"
"google.golang.org/grpc"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
)
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("runtime.Caller failed")
}
dir := filepath.Dir(file)
for {
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
return dir
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("could not find repo root")
}
dir = parent
}
}
func buildBinary(t *testing.T) string {
t.Helper()
bin := filepath.Join(t.TempDir(), "archie-messaging")
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-messaging")
cmd.Dir = repoRoot(t)
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("go build archie-messaging: %v\n%s", err, string(out))
}
return bin
}
type fakeChatServer struct {
messaging.ChatContract
}
func (f *fakeChatServer) Snapshot(ctx context.Context) (messaging.ChatSnapshot, error) {
return messaging.ChatSnapshot{}, nil
}
func startTestGateway(t *testing.T) (target string, cleanup func()) {
t.Helper()
lis, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("net.Listen: %v", err)
}
srv := grpc.NewServer()
gatewayrpc.RegisterServer(srv, &fakeChatServer{})
go func() {
_ = srv.Serve(lis)
}()
return lis.Addr().String(), func() {
srv.GracefulStop()
_ = lis.Close()
}
}
// fakeControlPlane serves the empty channel-settings resource the Messaging
// Service reads at startup. The database is authoritative for channel
// settings, so the process refuses to start without a State Store to read.
type fakeControlPlane struct {
controlpb.UnimplementedControlPlaneServiceServer
}
func (f *fakeControlPlane) Catalog(context.Context, *controlpb.CatalogRequest) (*controlpb.CatalogResponse, error) {
return &controlpb.CatalogResponse{}, nil
}
func (f *fakeControlPlane) Query(_ context.Context, request *controlpb.QueryRequest) (*controlpb.QueryResponse, error) {
return &controlpb.QueryResponse{Resource: &controlpb.Resource{Kind: request.GetKind(), Version: 1, ValueJson: []byte("{}")}}, nil
}
func startTestStateStore(t *testing.T) (target string, cleanup func()) {
t.Helper()
lis, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("net.Listen: %v", err)
}
srv := grpc.NewServer()
controlpb.RegisterControlPlaneServiceServer(srv, &fakeControlPlane{})
go func() {
_ = srv.Serve(lis)
}()
return lis.Addr().String(), func() {
srv.GracefulStop()
_ = lis.Close()
}
}
func TestBinaryHelp(t *testing.T) {
bin := buildBinary(t)
cmd := exec.CommandContext(t.Context(), bin, "-help")
out, err := cmd.CombinedOutput()
// flag.ExitOnError or flag help returns exit 0 or 2 depending on standard library
if !strings.Contains(string(out), "gateway-target") {
t.Fatalf("help output missing gateway-target flag: %v\n%s", err, string(out))
}
}
func TestBinaryStartsAndShutsDownCleanly(t *testing.T) {
bin := buildBinary(t)
gatewayTarget, cleanup := startTestGateway(t)
defer cleanup()
stateStoreTarget, stopStateStore := startTestStateStore(t)
defer stopStateStore()
cmd := exec.CommandContext(t.Context(), bin, "-gateway-target", gatewayTarget, "-state-store-target", stateStoreTarget)
if err := cmd.Start(); err != nil {
t.Fatalf("cmd.Start: %v", err)
}
// Allow the process to start up.
time.Sleep(200 * time.Millisecond)
// Send SIGTERM to shut down gracefully.
if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
t.Fatalf("send SIGTERM: %v", err)
}
errCh := make(chan error, 1)
go func() {
errCh <- cmd.Wait()
}()
select {
case err := <-errCh:
if err != nil {
t.Fatalf("process exited with error on SIGTERM: %v", err)
}
case <-time.After(3 * time.Second):
_ = cmd.Process.Kill()
t.Fatal("process did not exit in time after SIGTERM")
}
}
-91
View File
@@ -1,91 +0,0 @@
// Command archie-playbooks is the standalone playbook tool for archie-core,
// shaped like gopls: one binary, multiple invocation modes. It validates
// playbook YAML binding files against the same schema the daemon loads at
// startup, so a pre-merge check can never disagree with runtime validation.
//
// Today it ships one mode (lint). The command dispatch is a table from day
// one, so a future serve/lsp mode slots in without restructuring -- both
// modes are entrypoints into the same validation source in
// internal/domain/workflow.
//
// Known limitation (as of this slice): findings are file-granular, not
// line-granular. The loader decodes playbooks with yaml.Unmarshal into a
// plain map, which discards line numbers; a compiler-style file:line
// diagnostic needs a yaml.Node decoding upgrade, which is out of scope
// here and tracked separately.
package main
import (
"flag"
"fmt"
"io"
"os"
"github.com/samcharles93/archie-core/internal/app/archieplaybooks"
"github.com/samcharles93/archie-core/internal/buildinfo"
)
func main() {
os.Exit(run(os.Args[1:], os.Stderr))
}
func run(args []string, stderr io.Writer) int {
// Subcommand table from day one (gopls shape): each mode owns its flag
// set and returns an exit code. Adding serve/lsp later is a new entry
// here, not a restructuring.
commands := map[string]func([]string, io.Writer) int{
"lint": runLint,
}
if len(args) > 0 && (args[0] == "-version" || args[0] == "--version") {
buildinfo.Print("archie-playbooks")
return 0
}
if len(args) == 0 {
fmt.Fprintln(stderr, "usage: archie-playbooks <command> [args]")
fmt.Fprintln(stderr, "commands:")
for name := range commands {
fmt.Fprintf(stderr, " %s\n", name)
}
return 2
}
cmd, ok := commands[args[0]]
if !ok {
fmt.Fprintf(stderr, "archie-playbooks: unknown command %q\n", args[0])
return 2
}
return cmd(args[1:], stderr)
}
// runLint validates one or more playbook directories against the domain
// loaders and reports collisions / malformed files / invalid bindings.
// Exit codes: 0 clean, 1 findings, 2 usage error.
func runLint(args []string, stderr io.Writer) int {
flags := flag.NewFlagSet("archie-playbooks lint", flag.ContinueOnError)
flags.SetOutput(stderr)
var dirs multiFlag
flags.Var(&dirs, "dir", "playbook directory to lint (repeatable)")
if err := flags.Parse(args); err != nil {
return 2 // flag.ContinueOnError already printed the message
}
if len(dirs) == 0 {
fmt.Fprintln(stderr, "lint: at least one -dir is required")
flags.Usage()
return 2
}
result := archieplaybooks.Lint(dirs, stderr)
return result.ExitCode
}
// multiFlag collects repeated -dir flags.
type multiFlag []string
func (m *multiFlag) String() string { return fmt.Sprint([]string(*m)) }
func (m *multiFlag) Set(v string) error {
*m = append(*m, v)
return nil
}
-75
View File
@@ -1,75 +0,0 @@
package main
import (
"bytes"
"os"
"path/filepath"
"strings"
"testing"
)
// TestRunUnknownCommandExits2: an unrecognised subcommand is a usage error.
func TestRunUnknownCommandExits2(t *testing.T) {
var stderr bytes.Buffer
if code := run([]string{"frobnicate"}, &stderr); code != 2 {
t.Fatalf("run(unknown) = %d, want 2", code)
}
if !strings.Contains(stderr.String(), "unknown command") {
t.Fatalf("stderr = %q, want unknown-command message", stderr.String())
}
}
// TestRunNoCommandExits2: no subcommand is a usage error with the command
// table printed (the gopls-shaped dispatch surface).
func TestRunNoCommandExits2(t *testing.T) {
var stderr bytes.Buffer
if code := run(nil, &stderr); code != 2 {
t.Fatalf("run(nil) = %d, want 2", code)
}
if !strings.Contains(stderr.String(), "lint") {
t.Fatalf("stderr = %q, want lint listed in usage", stderr.String())
}
}
// TestRunLintCleanExits0: lint over a valid directory exits 0.
func TestRunLintCleanExits0(t *testing.T) {
dir := t.TempDir()
writeFile(t, filepath.Join(dir, "routes.yaml"), "bug: tdd\n")
var stderr bytes.Buffer
if code := run([]string{"lint", "-dir", dir}, &stderr); code != 0 {
t.Fatalf("run(lint clean) = %d, want 0; stderr=%q", code, stderr.String())
}
}
// TestRunLintCollisionExits1: a cross-directory collision exits 1 and names
// the colliding key.
func TestRunLintCollisionExits1(t *testing.T) {
dirA := t.TempDir()
dirB := t.TempDir()
writeFile(t, filepath.Join(dirA, "a.yaml"), "security: security-review\n")
writeFile(t, filepath.Join(dirB, "b.yaml"), "security: other-security\n")
var stderr bytes.Buffer
if code := run([]string{"lint", "-dir", dirA, "-dir", dirB}, &stderr); code != 1 {
t.Fatalf("run(lint collision) = %d, want 1; stderr=%q", code, stderr.String())
}
if !strings.Contains(stderr.String(), "security") {
t.Fatalf("stderr = %q, want the colliding label named", stderr.String())
}
}
// TestRunLintNoDirsExits2: lint without any -dir is a usage error.
func TestRunLintNoDirsExits2(t *testing.T) {
var stderr bytes.Buffer
if code := run([]string{"lint"}, &stderr); code != 2 {
t.Fatalf("run(lint no dirs) = %d, want 2", code)
}
}
func writeFile(t *testing.T, path, content string) {
t.Helper()
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
t.Fatalf("write %s: %v", path, err)
}
}
+9 -14
View File
@@ -1,11 +1,5 @@
// Command archie-state-store hosts the State Store's gRPC contract and owns
// the single archie.db SQLite file. It is the .4.3 companion to the daemon's
// in-process State Store server: the same StateStoreService .4.2 serves, but
// extracted into its own process with its own store lifecycle.
//
// The gateway's session SQLite is owned by the separate archie-gateway process
// and is untouched here. See docs/prds/state-store-contract.md (rev. 2c) §5,
// §9 and §11.
// Command archie-state-store hosts the State Store's gRPC contract and is the
// only process that owns the PostgreSQL stores behind it.
package main
import (
@@ -17,7 +11,7 @@ import (
"strings"
"syscall"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/statestore"
"github.com/samcharles93/archie-core/internal/buildinfo"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
@@ -29,26 +23,27 @@ func run() int {
// including no arguments at all, serves the State Store contract. An
// unrecognised word is refused rather than ignored, so a mistyped recovery
// command never leaves an operator watching a server start instead.
if args := os.Args[1:]; statestore.IsAccessResetArgs(args) {
return statestore.RunAccessReset(context.Background(), args[2:], os.Stderr)
}
if args := os.Args[1:]; len(args) > 0 && !strings.HasPrefix(args[0], "-") {
return runRecovery(args, os.Stdout, os.Stderr)
}
var options archied.StateStoreOptions
var options statestore.Options
showVersion := buildinfo.RegisterVersionFlag("archie-state-store")
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)")
flag.StringVar(&options.Token, "token", "", "bearer token required for a non-loopback listener (defaults to [services.state].target_token)")
flag.StringVar(&options.ReadyAddr, "ready-addr", "", "optional readiness HTTP listen address (e.g. 127.0.0.1:9091)")
flag.StringVar(&options.AdminAddr, "admin-addr", "", "optional read-only operator dashboard listen address (e.g. 127.0.0.1:8090)")
flag.Usage = func() {
fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store <backup|restore|validate|rollback> -h\n\n")
fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store <backup|restore|validate|rollback> -h | access reset -h\n\n")
flag.PrintDefaults()
}
flag.Parse()
showVersion()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := archied.RunStateStore(ctx, options); err != nil {
if err := statestore.Run(ctx, options); err != nil {
fmt.Fprintln(os.Stderr, err)
return 1
}
-620
View File
@@ -1,620 +0,0 @@
// Package main smoke-tests the standalone archie-state-store process by
// building the real binary, running it against a minimal config on the
// loopback interface, and driving it through the State Store gRPC contract
// exactly the way a consumer (archied, archie-gateway, archie-agent) does.
//
// This is the .4.7 end-to-end verification for
// docs/prds/state-store-contract.md (rev. 2c): it proves the process owns the
// single archie.db task SQLite, serves the combined task/event/capture
// surface over one gRPC service, preserves error-sentinel fidelity across the
// wire, honours a per-call deadline, survives a restart/recovery cycle, and
// is the sole owner of the SQLite file. See §5 (binary layout), §6 (handoff),
// §7 (error semantics), §11 (remote adapter) and §12 step 7/8 (single owner).
package main
import (
"bufio"
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"net"
"net/http"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"sync"
"syscall"
"testing"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"github.com/samcharles93/archie-core/internal/domain/binding"
"github.com/samcharles93/archie-core/internal/domain/mapping"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
)
// repoRoot walks up from the test's source directory to find the module root
// (where go.mod lives). The test runs in the package directory
// (cmd/archie-state-store), so the module root is above it; walking keeps the
// result correct regardless of the harness working directory.
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot determine test source path")
}
dir := filepath.Dir(file)
for {
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
return dir
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("go.mod not found above test source")
}
dir = parent
}
}
// buildBinary compiles ./cmd/archie-state-store into dir and returns the path.
// This is the real binary the smoke test exercises, not a test double -- the
// point of .4.7 is to verify the actual process.
func buildBinary(t *testing.T, dir string) string {
t.Helper()
bin := filepath.Join(dir, "archie-state-store")
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-state-store")
cmd.Dir = repoRoot(t)
cmd.Env = os.Environ()
out, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("go build archie-state-store: %v\n%s", err, out)
}
if _, err := os.Stat(bin); err != nil {
t.Fatalf("built binary not found: %v", err)
}
return bin
}
// writeMinimalConfig writes a config.toml that passes configuration.Validate
// while keeping the process minimal: the standalone binary takes its gRPC
// listen address from -listen or [services.state].listen, never from the
// target, so the config only needs the fields validation requires plus the
// db_path it owns. The
// forge token resolves from an env var, so no real credential is needed.
func writeMinimalConfig(t *testing.T, dir string) string {
t.Helper()
cfg := filepath.Join(dir, "config.toml")
content := fmt.Sprintf(`bot_user = "archie-bot"
db_path = %q
[forge]
type = "github"
host = "https://github.example.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
[[repos]]
owner = "acme"
name = "widget"
`, filepath.Join(dir, "archie.db"))
if err := os.WriteFile(cfg, []byte(content), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
return cfg
}
// writeConfigWithServiceListen is writeMinimalConfig plus the
// [services.state] block that lets a test supply the listen address through
// configuration instead of the -listen flag.
func writeConfigWithServiceListen(t *testing.T, dir string) string {
t.Helper()
cfg := writeMinimalConfig(t, dir)
f, err := os.OpenFile(cfg, os.O_APPEND|os.O_WRONLY, 0o600)
if err != nil {
t.Fatalf("open config to append: %v", err)
}
defer func() {
if err := f.Close(); err != nil {
t.Fatalf("close config: %v", err)
}
}()
if _, err := f.WriteString("\n[services.state]\nlisten = \"127.0.0.1:0\"\n"); err != nil {
t.Fatalf("append [services.state]: %v", err)
}
return cfg
}
// syncBuffer is a concurrency-safe buffer for a subprocess's stdout/stderr:
// the os/exec goroutine writes while the test goroutine reads (to parse the
// log and to report it on failure). A plain strings.Builder races under
// -race, so both paths take the mutex.
type syncBuffer struct {
mu sync.Mutex
b bytes.Buffer
}
func (s *syncBuffer) Write(p []byte) (int, error) {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.Write(p)
}
func (s *syncBuffer) String() string {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.String()
}
// stateStoreProcess wraps a running archie-state-store subprocess plus the
// addresses it bound. addr is the gRPC listen address; readyAddr is the
// readiness HTTP surface. It is stopped gracefully on cleanup by SIGTERM, the
// signal the systemd unit ("Restart=on-failure") and the daemon use to drain
// the server.
type stateStoreProcess struct {
cmd *exec.Cmd
addr string
readyAddr string
log *syncBuffer
}
// startStateStoreProcess starts bin with config, waiting for the gRPC listener
// to come up and the readiness surface to answer /healthz. It parses the
// binary's stderr log for the bound addresses because --listen 127.0.0.1:0
// lets the process choose ephemeral ports, and the real address (not the
// configured one) is what a consumer must dial.
func startStateStoreProcess(t *testing.T, bin, cfg string) *stateStoreProcess {
t.Helper()
return startStateStore(t, bin, cfg, "127.0.0.1:0", "")
}
// startStateStore is startStateStoreProcess with the listener topology and
// bearer token exposed: the token-protected, non-loopback listener is the
// topology every container-mode deployment profile uses
// (docs/prds/state-store-contract.md §9), where the server installs the
// credential interceptors on both the unary and the streaming surface.
func startStateStore(t *testing.T, bin, cfg, listen, token string) *stateStoreProcess {
t.Helper()
args := []string{"-config", cfg, "-ready-addr", "127.0.0.1:0"}
if listen != "" {
// An empty listen means "pass no -listen at all". A test uses that to
// prove the bound address came from [services.state].listen.
args = append(args, "-listen", listen)
}
if token != "" {
// An explicit -token wins over [services.state].target_token and the
// STATE_STORE_TOKEN secret, so the process authenticates callers with
// exactly this value.
args = append(args, "-token", token)
}
cmd := exec.CommandContext(t.Context(), bin, args...)
cmd.Env = append(os.Environ(), "ARCHIE_GITHUB_TOKEN=test-token")
var log syncBuffer
cmd.Stderr = &log
cmd.Stdout = &log
if err := cmd.Start(); err != nil {
t.Fatalf("start state store: %v", err)
}
p := &stateStoreProcess{cmd: cmd, log: &log}
t.Cleanup(func() { p.stop(t) })
// Recover the ephemeral ports from the JSON log lines the binary emits.
deadline := time.Now().Add(15 * time.Second)
for time.Now().Before(deadline) {
if p.parseAddrs() {
break
}
if cmd.ProcessState != nil {
t.Fatalf("state store exited early:\n%s", log.String())
}
time.Sleep(25 * time.Millisecond)
}
if p.addr == "" || p.readyAddr == "" {
t.Fatalf("did not recover bound addresses from log:\n%s", log.String())
}
// The readiness surface is the liveness signal the runbook uses; poll it
// until it answers (the gRPC listener may come up a tick ahead of it).
deadline = time.Now().Add(15 * time.Second)
req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "http://"+p.readyAddr+"/healthz", nil)
if err != nil {
t.Fatalf("build readiness request: %v", err)
}
for time.Now().Before(deadline) {
if resp, err := http.DefaultClient.Do(req); err == nil {
_ = resp.Body.Close()
if resp.StatusCode == http.StatusOK {
return p
}
}
time.Sleep(25 * time.Millisecond)
}
t.Fatalf("readiness /healthz never became healthy:\n%s", log.String())
return nil
}
// parseAddrs scans the captured log for the bound gRPC and readiness
// addresses. The binary logs "archie-state-store running" with the gRPC addr
// and "state store readiness listening" with the HTTP addr.
func (p *stateStoreProcess) parseAddrs() bool {
if p.addr != "" && p.readyAddr != "" {
return true
}
scanner := bufio.NewScanner(strings.NewReader(p.log.String()))
for scanner.Scan() {
line := scanner.Text()
var rec map[string]any
if err := json.Unmarshal([]byte(line), &rec); err != nil {
continue
}
if msg, _ := rec["msg"].(string); msg == "archie-state-store running" {
if addr, ok := rec["addr"].(string); ok && addr != "" && p.addr == "" {
p.addr = addr
}
}
if msg, _ := rec["msg"].(string); msg == "state store readiness listening" {
if addr, ok := rec["addr"].(string); ok && addr != "" && p.readyAddr == "" {
p.readyAddr = strings.TrimPrefix(addr, "http://")
}
}
}
return p.addr != "" && p.readyAddr != ""
}
// stop drains the process with SIGTERM and waits for it to exit. This is the
// same graceful-stop path serveStateStore's signal handling implements.
func (p *stateStoreProcess) stop(t *testing.T) {
t.Helper()
if p.cmd.Process == nil {
return
}
_ = p.cmd.Process.Signal(syscall.SIGTERM)
done := make(chan struct{})
go func() { _ = p.cmd.Wait(); close(done) }()
select {
case <-done:
case <-time.After(10 * time.Second):
_ = p.cmd.Process.Kill()
<-done
}
}
// contract is the combined consumer surface a daemon/gateway/agent mixes: the
// task lifecycle + events surface (store.TaskStore) and the capture surface.
// Mapping/binding/dispatch is exercised separately in
// TestStateStoreRealProcessRemoteSurfaces via the concrete Client, which
// asserts against each narrow interface at compile time.
type contract interface {
store.TaskStore
store.CaptureStore
}
// dial opens a gRPC connection to the state store process and wraps it in the
// remote contract adapter, exactly as the daemon/gateway/agent consumer does
// (internal/infrastructure/staterpc.Client).
func dial(t *testing.T, addr string) contract {
t.Helper()
conn, err := grpc.NewClient("passthrough:///"+addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatalf("dial %s: %v", addr, err)
}
t.Cleanup(func() { _ = conn.Close() })
return staterpc.NewClient(conn)
}
// capture builds a CapturedEvent without pulling the whole store field set
// into every call site.
func capture(source, body string) store.CapturedEvent {
return store.CapturedEvent{Source: source, Body: body, Authenticated: true}
}
// TestStateStoreRealProcessSmoke exercises the actual archie-state-store
// binary end-to-end: the combined task/event/capture view through one consumer
// adapter, error-sentinel fidelity across the wire, the not-found-as-(nil,nil)
// convention, and single-owner SQLite (the binary owns the one archie.db file
// and the consumer dials gRPC without opening any store file).
//
// It also takes its listen address from [services.state].listen rather than
// -listen, so the startup path every deployment uses is covered by the process
// that exercises the most: before that key existed the address came from a flag
// default with no config key, so a host whose port was already taken could
// only be retargeted by passing -listen and
// hand-writing an overlay whose target matched -- and the failure read as a
// code fault, "address already in use" in the store and a gRPC handshake error
// in every client.
func TestStateStoreRealProcessSmoke(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeConfigWithServiceListen(t, dir)
st := startStateStore(t, bin, cfg, "", "")
if st.addr == "" {
t.Fatalf("no bound gRPC address in the log:\n%s", st.log.String())
}
if !strings.Contains(st.log.String(), `"listen":"127.0.0.1:0"`) {
t.Fatalf("the resolved listen was not the configured address:\n%s", st.log.String())
}
cl := dial(t, st.addr)
ctx := t.Context()
// Combined task/event/capture view: a task, an event on that task, and an
// unrelated capture written through one consumer, read back across all
// three surfaces in a single pass (the dashboard/observability read path).
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "")
if err != nil || task == nil {
t.Fatalf("EnqueueChatTask = %+v, %v", task, err)
}
if err := cl.Transition(ctx, task.ID, task.Status, "running", "smoke started"); err != nil {
t.Fatalf("Transition: %v", err)
}
if _, err := cl.InsertEvent(ctx, events.Event{Kind: "stage_finish", TaskID: task.ID, Attempt: 1, Data: map[string]any{"duration_ms": 12.0}}); err != nil {
t.Fatalf("InsertEvent: %v", err)
}
// R4's document is stored as an event, so the real process must round-trip
// it with its nested structure and its attempt key intact: the standalone
// State Store owns the only copy, and a lost field here is a Config tab
// that reads a run it cannot describe. The key is the daemon's own
// (internal/daemon/daemon.go writes "document"), asserted by name below.
if _, err := cl.InsertEvent(ctx, events.Event{
Kind: events.KindConfigCaptured, TaskID: task.ID, Attempt: 1,
Data: map[string]any{
"schema": events.ConfigCapturedSchema,
"document": map[string]any{"bot_user": "archie", "models": map[string]any{"implement": "anthropic/claude"}},
},
}); err != nil {
t.Fatalf("InsertEvent config_captured: %v", err)
}
if capID, err := cl.InsertCapture(ctx, capture("sentry", `{"id":1}`), 0, 0); err != nil || capID == "" {
t.Fatalf("InsertCapture = (%q, %v)", capID, err)
}
got, err := cl.TaskByID(ctx, task.ID)
if err != nil || got == nil || got.ID != task.ID || got.Status != "running" {
t.Fatalf("TaskByID after transition = %+v, %v", got, err)
}
evs, err := cl.TaskEvents(ctx, task.ID)
if err != nil || len(evs) != 2 || evs[0].Kind != "stage_finish" {
t.Fatalf("TaskEvents = %+v, %v", evs, err)
}
if evs[0].Attempt != 1 {
t.Errorf("TaskEvents attempt = %d, want 1 across the real process", evs[0].Attempt)
}
if evs[1].Kind != events.KindConfigCaptured || evs[1].Attempt != 1 || evs[1].Data["schema"] != events.ConfigCapturedSchema {
t.Errorf("config_captured event = %+v, want its kind, attempt and schema preserved", evs[1])
}
if _, renamed := evs[1].Data["config"]; renamed {
t.Error(`the document crossed under "config"; the producer writes it under "document"`)
}
if len(evs[1].Data) != 2 {
t.Errorf("config_captured data keys = %v, want exactly schema and document", evs[1].Data)
}
if doc, ok := evs[1].Data["document"].(map[string]any); !ok || doc["bot_user"] != "archie" {
t.Errorf("config_captured payload = %#v, want the decoded document under its own key", evs[1].Data)
}
if caps, err := cl.ListCaptures(ctx, 10); err != nil || len(caps) != 1 || caps[0].Source != "sentry" {
t.Fatalf("ListCaptures = %+v, %v", caps, err)
}
if counts, err := cl.StatusCounts(ctx); err != nil || counts["running"] != 1 {
t.Fatalf("StatusCounts = %+v, %v", counts, err)
}
t.Run("error_sentinel_fidelity", func(t *testing.T) {
// A stale transition must rehydrate to store.ErrStaleTransition across
// the wire (§7). Because the binary is up and we dialed it, a sentinel
// mismatch here would surface as a transport error, so a pass proves
// the gRPC mapError/unmapError round-trip, not just the in-process
// adapter.
err := cl.Transition(ctx, task.ID, "queued", "merged", "")
if !errors.Is(err, store.ErrStaleTransition) {
t.Fatalf("stale Transition = %v, want store.ErrStaleTransition", err)
}
})
t.Run("not_found_is_not_error", func(t *testing.T) {
// Reading a missing task returns (nil, nil), never a NotFound gRPC
// error (§7's found=false-not-error convention).
missing, err := cl.TaskByID(ctx, task.ID+999999)
if err != nil || missing != nil {
t.Fatalf("TaskByID missing = (%+v, %v), want (nil, nil)", missing, err)
}
})
t.Run("single_owner_sqlite", func(t *testing.T) {
// The binary owns one task SQLite file (db_path + "-tasks.sqlite");
// the consumer called only gRPC methods and never opened a store file.
// The config anchor path itself must not be opened directly (no dual
// store ownership, §12 step 8).
taskFile := filepath.Join(dir, "archie.db-tasks.sqlite")
if _, err := os.Stat(taskFile); err != nil {
t.Fatalf("state store did not own %s: %v", taskFile, err)
}
if _, err := os.Stat(filepath.Join(dir, "archie.db")); err == nil {
t.Fatalf("config anchor path was opened directly; dual store ownership violated §12 step 8")
}
})
}
// TestStateStoreRealProcessDeadline verifies the per-call deadline behaviour
// the state store contract requires (§6 StoreTimeout): a consumer context that
// is cancelled before the call completes must surface a deadline/cancel error
// rather than hang or silently succeed.
func TestStateStoreRealProcessDeadline(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
st := startStateStoreProcess(t, bin, cfg)
cl := dial(t, st.addr)
ctx, cancel := context.WithCancel(t.Context())
cancel()
_, err := cl.StatusCounts(ctx)
if err == nil {
t.Fatal("StatusCounts on a cancelled context returned nil; expected a deadline/cancel error")
}
if !errors.Is(err, context.Canceled) && !errors.Is(err, context.DeadlineExceeded) {
t.Fatalf("StatusCounts cancelled = %v, want context.Canceled or DeadlineExceeded", err)
}
}
// TestStateStoreRealProcessRestartRecovery starts the process, writes a task,
// stops it (SIGTERM), restarts it on the same config/db_path, and verifies the
// task and its events were recovered from the on-disk SQLite -- the
// restart/recovery path the runbook relies on when archie-state-store is
// restarted as a service.
func TestStateStoreRealProcessRestartRecovery(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
first := startStateStoreProcess(t, bin, cfg)
s1 := dial(t, first.addr)
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "")
if err != nil || task == nil {
t.Fatalf("first EnqueueChatTask = %+v, %v", task, err)
}
if _, err := s1.InsertEvent(t.Context(), events.Event{Kind: "run_started", TaskID: task.ID}); err != nil {
t.Fatalf("first InsertEvent: %v", err)
}
first.stop(t)
// Restart on the same config; the SQLite file persists on disk.
second := startStateStoreProcess(t, bin, cfg)
s2 := dial(t, second.addr)
got, err := s2.TaskByID(t.Context(), task.ID)
if err != nil || got == nil || got.Title != "survive restart" {
t.Fatalf("TaskByID after restart = %+v, %v", got, err)
}
if evs, err := s2.TaskEvents(t.Context(), task.ID); err != nil || len(evs) != 1 {
t.Fatalf("TaskEvents after restart = %+v, %v", evs, err)
}
// Stale-running work reopened on a fresh process is recovered by
// RecoverStale, which must return without error on the restarted store.
if _, err := s2.RecoverStale(t.Context()); err != nil {
t.Fatalf("RecoverStale after restart: %v", err)
}
}
// TestStateStoreRealProcessTokenProtectedCaptureStream is the capture-batch
// regression against the real binary: the token-protected, non-loopback
// listener topology a container-mode deployment uses, read through the
// production client wiring (staterpc.Dial) the daemon and the dashboard both
// use. The reads the batch needs are server-streaming RPCs, whose metadata
// the unary-only client interceptor never saw -- so before the fix this
// failed with PermissionDenied, and no unary fallback existed to take. 20 x
// 256 KiB is 5 MiB, past gRPC's 4 MiB unary cap, so the batch also proves the
// streams still carry it.
func TestStateStoreRealProcessTokenProtectedCaptureStream(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
const token = "operator-secret-token"
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
st := startStateStore(t, bin, cfg, "0.0.0.0:0", token)
// The listener advertises the wildcard address it bound; a consumer dials
// the host address it can reach, which is this host's loopback.
_, port, err := net.SplitHostPort(st.addr)
if err != nil {
t.Fatalf("parse bound address %q: %v", st.addr, err)
}
cl, cleanup, err := staterpc.Dial("127.0.0.1:"+port, token)
if err != nil {
t.Fatalf("dial token-protected state store: %v", err)
}
t.Cleanup(cleanup)
ctx := t.Context()
body := strings.Repeat("x", 256<<10)
for range 20 {
if _, err := cl.InsertCapture(ctx, capture("large", body), 0, 0); err != nil {
t.Fatalf("InsertCapture: %v", err)
}
}
captures, err := cl.ListCaptures(ctx, 20)
if err != nil {
t.Fatalf("ListCaptures over a token-protected listener: %v", err)
}
if len(captures) != 20 {
t.Fatalf("got %d captures, want 20", len(captures))
}
for _, c := range captures {
if c.Body != body {
t.Fatal("capture body truncated")
}
}
}
// TestStateStoreRealProcessRemoteSurfaces exercises the capture/mapping/
// binding surfaces the standalone process fronts (the daemon/webui surfaces
// swapped to the adapter in .4.4/.4.5), proving one process serves the full
// combined contract a consumer mixes.
func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
st := startStateStoreProcess(t, bin, cfg)
conn, err := grpc.NewClient("passthrough:///"+st.addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatalf("dial: %v", err)
}
t.Cleanup(func() { _ = conn.Close() })
cl := staterpc.NewClient(conn)
ctx := t.Context()
mappingID, err := cl.InsertMapping(ctx, mapping.Mapping{Name: "m1", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}})
if err != nil || mappingID == "" {
t.Fatalf("InsertMapping = (%q, %v)", mappingID, err)
}
if got, err := cl.GetMapping(ctx, mappingID); err != nil || got == nil || got.Name != "m1" {
t.Fatalf("GetMapping = %+v, %v", got, err)
}
bindingID, err := cl.InsertBinding(ctx, binding.Binding{
Name: "b1", Matcher: binding.Matcher{Source: "sentry"}, MappingID: mappingID,
Workflow: "implement", Secret: "0123456789abcdef0123456789abcdef",
})
if err != nil || bindingID == "" {
t.Fatalf("InsertBinding = (%q, %v)", bindingID, err)
}
// A binding starts as draft and must be edited (draft -> pending_approval)
// then approved (pending_approval -> armed) before it is armed for a
// source. Drive the state machine so ArmedBindingsForSource returns it.
if err := cl.UpdateBinding(ctx, binding.Binding{
ID: bindingID, Name: "b1", Matcher: binding.Matcher{Source: "sentry"},
MappingID: mappingID, Workflow: "implement", Owner: "acme", Repo: "widget",
Secret: "0123456789abcdef0123456789abcdef",
}); err != nil {
t.Fatalf("UpdateBinding: %v", err)
}
if err := cl.ApproveBinding(ctx, bindingID); err != nil {
t.Fatalf("ApproveBinding: %v", err)
}
if armed, err := cl.ArmedBindingsForSource(ctx, "sentry"); err != nil || len(armed) != 1 || armed[0].ID != bindingID {
t.Fatalf("ArmedBindingsForSource = %+v, %v", armed, err)
}
// Remote surfaces share error-sentinel fidelity on the wire too.
missing := mapping.Mapping{ID: "rabsent00000000", Name: "x", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}}
if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, store.ErrMappingNotFound) {
t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err)
}
}
+28 -22
View File
@@ -7,30 +7,39 @@ import (
"fmt"
"io"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/statestore"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
// recoveryUsage is the whole flag surface of the offline recovery commands.
// They are subcommands of this binary rather than a recovery binary of their
// own: offline database maintenance belongs to the process that owns the file
// and its path layout (docs/architecture/organisation.md#process-boundaries).
// and its path layout.
const recoveryUsage = `usage: archie-state-store <command> [flags]
With no command, archie-state-store serves the State Store gRPC contract.
The recovery commands operate on the task database file directly -- the
configured db_path with "-tasks.sqlite" appended -- and are how an operator
recovers a database the control plane will not start on. Stop the State Store
first: restore and rollback rewrite the file and refuse while another process
owns it, while backup takes a consistent snapshot of a serving store.
The recovery commands are how an operator recovers a database the control
plane will not start on. They operate on the PostgreSQL database the
configuration's database_url names, through pg_dump and pg_restore (which
must be on PATH).
backup -db FILE -out FILE write a snapshot of the database
restore -db FILE -from FILE replace the database with a snapshot
validate -db FILE [-config FILE] check the file, its stored settings and the
configuration the daemon would boot with
rollback -db FILE -kind KIND replay an earlier revision of a stored
backup takes a consistent snapshot of a serving database. restore is
destructive and offline: stop every archie service first, since it refuses
while any of them holds its ownership claim, and every write made after the
snapshot is lost. rollback refuses while the State Store serves. There is no
automatic schema rollback: the way back from a migration is restoring the
snapshot taken before it.
backup -out FILE write a snapshot of the database
restore -from FILE replace the database with a snapshot
validate check the database, its stored settings and
the configuration the daemon would boot with
rollback -kind KIND replay an earlier revision of a stored
[-revision N] resource through the ordinary replace
Every command takes -config FILE and -config-overlay FILE: the configuration
the daemon boots with, which names the database.
`
// runRecovery parses and performs one offline recovery command, reporting the
@@ -42,9 +51,9 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
return 2
}
command := args[0]
options := archied.StateStoreRecoveryOptions{Operation: command}
options := statestore.RecoveryOptions{Operation: command}
switch command {
case archied.RecoveryBackup, archied.RecoveryRestore, archied.RecoveryValidate, archied.RecoveryRollback:
case statestore.RecoveryBackup, statestore.RecoveryRestore, statestore.RecoveryValidate, statestore.RecoveryRollback:
default:
fmt.Fprintf(stderr, "archie-state-store: unknown command %q\n\n", command)
fmt.Fprint(stderr, recoveryUsage)
@@ -54,17 +63,14 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
flags := flag.NewFlagSet("archie-state-store "+command, flag.ContinueOnError)
flags.SetOutput(stderr)
flags.Usage = func() { fmt.Fprint(stderr, recoveryUsage) }
flags.StringVar(&options.DB, "db", "", "task database file the State Store owns (<db_path>-tasks.sqlite)")
flags.StringVar(&options.Out, "out", "", "snapshot file backup writes")
flags.StringVar(&options.From, "from", "", "snapshot file restore reads")
flags.StringVar(&options.Kind, "kind", "", "control-plane resource kind rollback replays")
flags.Int64Var(&options.Revision, "revision", 0, "revision rollback replays (default: the newest one older than the current value)")
// Only validate asks a question about the process rather than the file, so
// only validate takes the configuration the process would boot with.
if command == archied.RecoveryValidate {
flags.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory the daemon boots with")
flags.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
}
// The configuration names the PostgreSQL database, and validate also checks
// the stored settings against it.
flags.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory the daemon boots with")
flags.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
if err := flags.Parse(args[1:]); err != nil {
// A requested help is not a wrong command line: the usage above is the
// answer, and the serve path exits 0 for the same request.
@@ -78,7 +84,7 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
return 2
}
summary, err := archied.RunStateStoreRecovery(context.Background(), options)
summary, err := statestore.RunRecovery(context.Background(), options)
if err != nil {
fmt.Fprintf(stderr, "archie-state-store %s: %v\n", command, err)
return 1
-809
View File
@@ -1,809 +0,0 @@
// Package main tests the offline recovery subcommands of archie-state-store:
// backup, restore, validate and rollback against the task database file
// directly. They are the operator's only path back when the control plane's
// stored settings will not validate, because the daemon fails closed: the
// in-band remedy (replay an earlier revision while the State Store is up) is
// unavailable in exactly the case that needs it.
//
// The tests drive the subcommands the way an operator does -- through
// runRecovery, against real files on disk -- rather than through the internal
// helpers, so the flag surface and the exit codes are part of what is verified.
package main
import (
"bytes"
"database/sql"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strconv"
"strings"
"testing"
_ "modernc.org/sqlite"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
"github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps"
"github.com/samcharles93/archie-core/internal/store"
)
// runRecoveryCmd runs one subcommand the way main does and returns its exit
// code with both streams captured.
func runRecoveryCmd(t *testing.T, args ...string) (int, string, string) {
t.Helper()
var stdout, stderr bytes.Buffer
code := runRecovery(args, &stdout, &stderr)
return code, stdout.String(), stderr.String()
}
// openTaskStore opens the task database the subcommands operate on. It does not
// take the ownership lock: only the serving process does that, and a test that
// wants a "live" store holds it explicitly with holdStoreOwnership.
func openTaskStore(t *testing.T, path string) *store.Store {
t.Helper()
st, err := store.Open(t.Context(), path)
if err != nil {
t.Fatalf("open task store %s: %v", path, err)
}
t.Cleanup(func() { _ = st.Close() })
return st
}
// holdStoreOwnership takes the ownership lock the running State Store holds for
// its whole life, so a test can prove a command refuses to touch a live store.
func holdStoreOwnership(t *testing.T, path string) {
t.Helper()
ownership, err := store.AcquireOwnership(path)
if err != nil {
t.Fatalf("acquire store ownership: %v", err)
}
t.Cleanup(func() { _ = ownership.Release() })
}
// seedTask writes one task so a snapshot can be distinguished from the live
// database by what it contains, not merely by its existence.
func seedTask(t *testing.T, st *store.Store, title string) {
t.Helper()
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", ""); err != nil {
t.Fatalf("seed task %q: %v", title, err)
}
}
func taskTitles(t *testing.T, path string) []string {
t.Helper()
st := openTaskStore(t, path)
tasks, err := st.Tasks(t.Context(), 100)
if err != nil {
t.Fatalf("list tasks in %s: %v", path, err)
}
titles := make([]string, 0, len(tasks))
for _, task := range tasks {
titles = append(titles, task.Title)
}
return titles
}
// backupPath is the snapshot every restore test restores from.
func backupPath(t *testing.T, dir string) string { return filepath.Join(dir, "snapshot.sqlite") }
// backup takes the snapshot the caller then restores, through the subcommand
// under test rather than through the store directly, so a broken backup fails
// the restore test too instead of silently passing an empty file.
func backup(t *testing.T, db, out string) {
t.Helper()
code, _, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", out)
if code != 0 {
t.Fatalf("backup exited %d: %s", code, stderr)
}
}
// The update installer cannot stop the process that runs it, so it backs the
// task database up while the State Store is serving. VACUUM INTO is safe
// against a live writer; a backup that insisted on an exclusively-owned file
// would break the one caller it has, and the update would refuse to start.
func TestRecoveryBackupSnapshotsAStoreItsStateStoreIsServing(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
out := backupPath(t, dir)
seedTask(t, openTaskStore(t, db), "before")
holdStoreOwnership(t, db)
if err := os.WriteFile(out, []byte("stale snapshot"), 0o600); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", out)
if code != 0 {
t.Fatalf("backup exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, out) || !strings.Contains(stdout, db) {
t.Errorf("backup must report the database and the snapshot it wrote; stdout = %q", stdout)
}
// The stale file was replaced by a real snapshot, and the snapshot is a
// store a restore can put back: same rows, readable through the store.
if got := taskTitles(t, out); len(got) != 1 || got[0] != "before" {
t.Fatalf("snapshot tasks = %v, want the one seeded task", got)
}
if entries, err := filepath.Glob(out + ".tmp*"); err != nil || len(entries) != 0 {
t.Errorf("backup left scratch files beside the snapshot: %v (%v)", entries, err)
}
}
// The snapshot is the rollback state, so an interrupted backup must never
// leave a truncated file where a good snapshot was.
func TestRecoveryBackupRefusesAMissingDatabase(t *testing.T) {
dir := t.TempDir()
code, _, stderr := runRecoveryCmd(t, "backup", "-db", filepath.Join(dir, "absent.sqlite"), "-out", backupPath(t, dir))
if code == 0 {
t.Fatal("backup of a missing database succeeded")
}
if !strings.Contains(stderr, "absent.sqlite") {
t.Errorf("refusal must name the database it could not read; stderr = %q", stderr)
}
}
// backup is the one recovery command allowed to run against a serving store,
// and that exemption is only sound while it never replaces the database. With
// -out naming the database it renames the snapshot over the live file and
// leaves the WAL of the database it just unlinked -- the state the restore path
// refuses up front and the code elsewhere calls unrecoverable.
func TestRecoveryBackupRefusesTheDatabaseAsItsOwnSnapshot(t *testing.T) {
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
seedTask(t, st, "live")
code, _, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", db)
if code == 0 {
t.Fatal("backup over the database itself succeeded")
}
if !strings.Contains(stderr, "is the database itself") {
t.Errorf("refusal must say the snapshot is the database; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 1 || got[0] != "live" {
t.Fatalf("refused backup changed the database: tasks = %v", got)
}
}
// Restoring is the forward-migration escape hatch: the previous release
// reads this file, so it must be exactly the snapshot, with the WAL that
// belongs to the replaced database gone rather than replayed over it.
func TestRecoveryRestorePutsTheSnapshotBackAndDropsItsWAL(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
out := backupPath(t, dir)
st := openTaskStore(t, db)
seedTask(t, st, "before")
backup(t, db, out)
seedTask(t, st, "after")
code, stdout, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", out)
if code != 0 {
t.Fatalf("restore exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, out) {
t.Errorf("restore must report the snapshot it restored from; stdout = %q", stdout)
}
// Checked before anything reopens the database: opening a store sets WAL
// mode, which creates these files, so the point is that the restore did not
// leave the replaced database's log behind -- not that a later reader
// cannot recreate its own.
for _, suffix := range []string{"-wal", "-shm"} {
if _, err := os.Stat(db + suffix); err == nil {
t.Errorf("%s survived the restore: the replaced database's write-ahead log must not be replayed over the snapshot", db+suffix)
}
}
if got := taskTitles(t, db); len(got) != 1 || got[0] != "before" {
t.Fatalf("restored tasks = %v, want only the snapshot's task", got)
}
}
// Overwriting a database a running State Store still owns leaves that process
// writing to an unlinked inode while the store serves a file nobody owns --
// the one way an offline command can destroy a task store.
func TestRecoveryRestoreRefusesAStoreTheStateStoreIsRunning(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
out := backupPath(t, dir)
st := openTaskStore(t, db)
seedTask(t, st, "before")
backup(t, db, out)
seedTask(t, st, "after")
holdStoreOwnership(t, db)
code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", out)
if code == 0 {
t.Fatal("restore against a live State Store succeeded")
}
if !strings.Contains(stderr, "owned by another process") {
t.Errorf("refusal must say the database is owned by another process; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 2 {
t.Fatalf("refused restore changed the database: tasks = %v", got)
}
}
func TestRecoveryRestoreRefusesAFileThatIsNotAStore(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
seedTask(t, openTaskStore(t, db), "live")
notAStore := filepath.Join(dir, "notes.txt")
if err := os.WriteFile(notAStore, []byte("this is not a database"), 0o600); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", notAStore)
if code == 0 {
t.Fatal("restore from a file that is not a store succeeded")
}
if !strings.Contains(stderr, notAStore) {
t.Errorf("refusal must name the snapshot it could not read; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 1 {
t.Fatalf("refused restore changed the database: tasks = %v", got)
}
}
func TestRecoveryRestoreRefusesTheDatabaseAsItsOwnSnapshot(t *testing.T) {
// Restoring a database from itself would delete the write-ahead log of the
// file it is about to copy, so the one case that must never reach the swap
// is refused up front.
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
seedTask(t, openTaskStore(t, db), "live")
code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", db)
if code == 0 {
t.Fatal("restore from the database itself succeeded")
}
if !strings.Contains(stderr, "is the database itself") {
t.Errorf("refusal must say the snapshot is the database; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 1 {
t.Fatalf("refused restore changed the database: tasks = %v", got)
}
}
func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) {
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
seedTask(t, st, "healthy")
seedStoreResources(t, st, configPath)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, "schema version") {
t.Errorf("validate must report the schema version it verified; stdout = %q", stdout)
}
// The count is part of what the operator reads, and a check that reports
// "0 stored resources" for a store full of them is worse than no check.
if count := storedResourceCount(t, stdout); count == 0 {
t.Errorf("validate reported no stored resources for a seeded store; stdout = %q", stdout)
}
}
// validate's verdict is only useful if it is the daemon's verdict. Boot refuses
// on configuration.Validate over the file config with every stored resource
// layered onto it (internal/app/archied/control_plane.go), not on the write
// path's own per-resource decode, and the two disagree: the write path accepts
// a scheduling policy boot rejects.
func TestRecoveryValidateRunsTheGateBootRuns(t *testing.T) {
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, db), configPath)
// The control: a store seeded from this config is one the daemon boots on.
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d on a store the daemon starts on: %s", code, stderr)
}
// A hand-edited value, or an older revision of one: the write path's own
// validator never inspects dispatch.trigger, so only the config gate
// catches it, and the daemon exits 1 on it (validateDispatch).
if err := execRaw(t, db, `UPDATE resources SET value='{"poll_interval":"1m","max_retries":3,"dispatch":{"trigger":"bogus"}}' WHERE kind='scheduling-policy'`); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
if code == 0 {
t.Fatalf("validate accepted a stored policy the daemon refuses to boot with; stdout = %q", stdout)
}
if !strings.Contains(stderr, "dispatch.trigger") {
t.Errorf("refusal must name what boot rejects; stderr = %q", stderr)
}
// A store the State Store never seeded holds no kinds at all. Its next start
// creates the resources table and seeds every kind from this same config
// (internal/app/archied/state_store.go), so archied layers those seeds and
// starts: refusing the file here would send an operator to restore a
// snapshot for a store the daemon boots on perfectly well.
unseeded := filepath.Join(dir, "unseeded.db-tasks.sqlite")
openTaskStore(t, unseeded)
code, stdout, stderr = runRecoveryCmd(t, "validate", "-db", unseeded, "-config", configPath)
if code != 0 {
t.Fatalf("validate refused a store the State Store would seed on its next start; stderr = %q", stderr)
}
if !strings.Contains(stdout, "0 stored resources validate") {
t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout)
}
// The upgrade case: a release defines a kind the store does not hold yet,
// and validate runs before the State Store has started again. The State
// Store seeds the kind it is missing, so this is the same stance as the
// store with nothing stored at all -- the file is not the reason the daemon
// would refuse to start, and saying otherwise costs the operator a snapshot.
partial := filepath.Join(dir, "partial.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, partial), configPath)
if err := execRaw(t, partial, `DELETE FROM resources WHERE kind='provider-settings'`); err != nil {
t.Fatal(err)
}
code, stdout, stderr = runRecoveryCmd(t, "validate", "-db", partial, "-config", configPath)
if code != 0 {
t.Fatalf("validate refused a store missing a kind the State Store seeds; stderr = %q", stderr)
}
if count := storedResourceCount(t, stdout); count == 0 {
t.Errorf("validate must still check the kinds the store does hold; stdout = %q", stdout)
}
}
// The subcommands advertise -h as the way to read their flags, and the serve
// path in the same binary exits 0 for the same request, so a script probing the
// recovery surface must not read a requested help as a failure.
func TestRecoveryHelpExitsZero(t *testing.T) {
commands := []string{archied.RecoveryBackup, archied.RecoveryRestore, archied.RecoveryValidate, archied.RecoveryRollback}
for _, command := range commands {
code, _, stderr := runRecoveryCmd(t, command, "-h")
if code != 0 {
t.Errorf("%s -h exited %d, want 0; stderr = %q", command, code, stderr)
}
}
}
// validate diagnoses a deployment; it is not the deployment. Resolving the boot
// config must not create, append to, or rotate the daemon's log file or the
// directory it lives in: a line stamped component="daemon" in archied's log is
// indistinguishable from the daemon having written it.
func TestRecoveryValidateLeavesTheDaemonLogAlone(t *testing.T) {
dir := t.TempDir()
configPath, logFile := writeConfigWithLogFile(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, db), configPath)
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
if _, err := os.Stat(logFile); !os.IsNotExist(err) {
t.Fatalf("validate touched the daemon's log file %s (stat err = %v)", logFile, err)
}
if _, err := os.Stat(filepath.Dir(logFile)); !os.IsNotExist(err) {
t.Errorf("validate created the log directory %s (stat err = %v)", filepath.Dir(logFile), err)
}
}
// validate's verdict is the daemon's verdict only if it reads the configuration
// the daemon reads, and with no -config it reads whatever the one shared
// helper resolves. The resolution rule itself is pinned where it lives
// (internal/infrastructure/configuration); what only this test can pin is that
// the command takes its default from that helper rather than deriving it.
//
// A relative XDG_CONFIG_HOME is the case that separates the two: the command
// has to resolve ${XDG_CONFIG_HOME}/archie/config.toml relative to its working
// directory, and a second derivation through os.UserConfigDir rejects a
// relative value outright, leaving the command with no config to answer about.
func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) {
// The second layout is the teeth: the command has to read the config at the
// resolved path, not merely find some config somewhere under the config home.
// A resolution that drifts finds nothing and validate has no verdict.
tests := []struct {
name string
configDir string // relative to $XDG_CONFIG_HOME
wantOK bool
}{
{name: "$XDG_CONFIG_HOME/archie/config.toml", configDir: "archie", wantOK: true},
{name: "a config elsewhere in the config home is not the default", configDir: "wrong-place"},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
root := t.TempDir()
t.Chdir(root)
t.Setenv("XDG_CONFIG_HOME", "xdg")
configDir := filepath.Join(root, "xdg", tc.configDir)
if err := os.MkdirAll(configDir, 0o700); err != nil {
t.Fatalf("create %s: %v", configDir, err)
}
configPath := writeMinimalConfig(t, configDir)
db := filepath.Join(root, "archie.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, db), configPath)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db)
if !tc.wantOK {
if code == 0 {
t.Fatalf("validate exited 0 with no config at the resolved path %s: %s", configPath, stdout)
}
return
}
if code != 0 {
t.Fatalf("validate with no -config exited %d, so it did not read %s: %s", code, configPath, stderr)
}
if !strings.Contains(stdout, "stored resources validate") {
t.Errorf("validate reported %q, want the verdict on the store seeded from the resolved config", stdout)
}
})
}
}
// validate exists to answer "would archied start against this file". Each case
// below is a state the daemon fails closed on, or a file it cannot read at all.
func TestRecoveryValidateRefusesWhatTheDaemonRefuses(t *testing.T) {
newStore := func(t *testing.T) string {
t.Helper()
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
openTaskStore(t, db)
return db
}
t.Run("forward_migrated_schema", func(t *testing.T) {
// A database written by a newer release is the state a rollback has to
// recognise before it hands the file to an older binary.
db := newStore(t)
if err := execRaw(t, db, `PRAGMA user_version = 99`); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a forward-migrated database")
}
if !strings.Contains(stderr, "newer than supported version") {
t.Errorf("refusal must name the schema version; stderr = %q", stderr)
}
})
t.Run("corrupt_file", func(t *testing.T) {
// A real database header over pages that are not a database. The magic
// is right, so this fails on the content rather than on the format, which
// is the shape a half-written or truncated store has.
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
corrupt := append([]byte("SQLite format 3\x00"), bytes.Repeat([]byte{0xff}, 4096)...)
if err := os.WriteFile(db, corrupt, 0o600); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a corrupt database")
}
if !strings.Contains(stderr, db) {
t.Errorf("refusal must name the file; stderr = %q", stderr)
}
})
t.Run("not_a_database", func(t *testing.T) {
// Pointing -db at the wrong file is the common operator mistake, and the
// configured db_path is a different file from the task database the
// State Store owns.
db := filepath.Join(t.TempDir(), "archie.db")
if err := os.WriteFile(db, []byte("db_path, not the task database"), 0o600); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a file that is not a database")
}
if !strings.Contains(stderr, db) {
t.Errorf("refusal must name the file; stderr = %q", stderr)
}
})
t.Run("stored_resource_that_will_not_validate", func(t *testing.T) {
// A stored value that both gates refuse: the write path stops it at
// Decode (workflow.ExecutionSettings.Validate rejects a negative limit),
// and boot stops on it too -- startWorkflowExecutionSettings decodes the
// same document and exits 1. It can only get here by bypassing the write
// path, which is exactly the state the operator has no path back from.
db := newStore(t)
seedResource(t, openTaskStore(t, db), controlplane.WorkflowExecutionSettingsKind,
`{"max_model_tool_steps":-1,"max_runtime_seconds":60,"max_consecutive_gate_failures":3}`, "hand-edited")
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a stored resource the write path would refuse")
}
if !strings.Contains(stderr, controlplane.WorkflowExecutionSettingsKind) {
t.Errorf("refusal must name the resource kind; stderr = %q", stderr)
}
})
t.Run("missing_database", func(t *testing.T) {
db := newStore(t)
if err := os.Remove(db); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a database that does not exist")
}
if !strings.Contains(stderr, db) {
t.Errorf("refusal must name the file; stderr = %q", stderr)
}
})
t.Run("store_without_the_control_plane_table", func(t *testing.T) {
// A store written before the control plane existed holds no stored
// settings. The serving process creates the table on its next start, so
// refusing this file would send an operator to restore a snapshot for a
// database that would have started perfectly well.
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
openTaskStore(t, db)
if err := execRaw(t, db, `DROP TABLE resources`); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, "0 stored resources validate") {
t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout)
}
})
}
// rollback is the one operation that closes the documented gap: with the State
// Store stopped, it replays the value an earlier revision recorded through the
// ordinary replace, so no rollback RPC is needed and the rollback itself is
// audited as one more revision.
func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first")
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second")
code, stdout, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind)
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, controlplane.ModelRoleAssignmentsKind) {
t.Errorf("rollback must name the resource it replayed; stdout = %q", stdout)
}
resource, err := st.Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
if string(resource.Value) != `{"implement":"anthropic/claude"}` {
t.Errorf("resource value = %s, want the first revision's value", resource.Value)
}
if resource.Version != 3 {
t.Errorf("resource version = %d, want a new revision (3) rather than a rewrite of the old one", resource.Version)
}
history, err := st.ResourceHistory(t.Context(), controlplane.ModelRoleAssignmentsKind, 0)
if err != nil {
t.Fatal(err)
}
if len(history) != 3 {
t.Fatalf("history has %d revisions, want the rollback recorded as the third", len(history))
}
if history[0].Source != archied.OfflineRollbackSource {
t.Errorf("newest revision source = %q, want %q so the rollback is auditable", history[0].Source, archied.OfflineRollbackSource)
}
}
// The revision to restore may be named, which is how an operator reaches past
// the most recent change without replaying it first.
func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first")
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second")
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"google/gemini"}`, "third")
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1")
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
resource, err := st.Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
if string(resource.Value) != `{"implement":"anthropic/claude"}` {
t.Errorf("resource value = %s, want the value recorded at revision 1", resource.Value)
}
}
func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
newStore := func(t *testing.T, revisions int) string {
t.Helper()
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
for i := range revisions {
value := `{"implement":"anthropic/claude"}`
if i > 0 {
value = `{"implement":"openai/gpt"}`
}
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, value, "seed")
}
return db
}
t.Run("unknown_kind", func(t *testing.T) {
db := newStore(t, 2)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", "not-a-resource")
if code == 0 {
t.Fatal("rollback of an unknown resource kind succeeded")
}
if !strings.Contains(stderr, "not-a-resource") {
t.Errorf("refusal must name the kind; stderr = %q", stderr)
}
})
t.Run("no_earlier_revision", func(t *testing.T) {
db := newStore(t, 1)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind)
if code == 0 {
t.Fatal("rollback with no earlier revision succeeded")
}
if !strings.Contains(stderr, "no earlier revision") {
t.Errorf("refusal must say there is nothing to roll back to; stderr = %q", stderr)
}
})
t.Run("current_revision", func(t *testing.T) {
db := newStore(t, 2)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "2")
if code == 0 {
t.Fatal("rollback of the current revision succeeded")
}
if !strings.Contains(stderr, "is the current version") {
t.Errorf("refusal must say the revision is already the current value; stderr = %q", stderr)
}
})
t.Run("live_state_store", func(t *testing.T) {
db := newStore(t, 2)
holdStoreOwnership(t, db)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind)
if code == 0 {
t.Fatal("rollback against a live State Store succeeded")
}
if !strings.Contains(stderr, "owned by another process") {
t.Errorf("refusal must say the database is owned by another process; stderr = %q", stderr)
}
})
}
// A positional argument that is not a subcommand used to be ignored, leaving
// an operator who mistyped a command watching a server start instead.
func TestRecoveryRejectsAnUnknownSubcommand(t *testing.T) {
var stdout, stderr bytes.Buffer
code := runRecovery([]string{"backp", "-db", "x"}, &stdout, &stderr)
if code == 0 {
t.Fatal("an unknown subcommand exited 0")
}
if !strings.Contains(stderr.String(), "backp") {
t.Errorf("refusal must name the unknown subcommand; stderr = %q", stderr.String())
}
}
// writeConfigWithLogFile is writeMinimalConfig plus the daemon's durable log
// destination, which only the daemon may bring into existence.
func writeConfigWithLogFile(t *testing.T, dir string) (string, string) {
t.Helper()
configPath := writeMinimalConfig(t, dir)
logFile := filepath.Join(dir, "logs", "archied.log")
f, err := os.OpenFile(configPath, os.O_APPEND|os.O_WRONLY, 0o600)
if err != nil {
t.Fatalf("open config to append: %v", err)
}
defer func() {
if err := f.Close(); err != nil {
t.Fatalf("close config: %v", err)
}
}()
if _, err := fmt.Fprintf(f, "\n[log]\nfile = %q\n", logFile); err != nil {
t.Fatalf("append [log]: %v", err)
}
return configPath, logFile
}
// seedStoreResources seeds the store the way the State Store seeds it at boot,
// from the same config file the operator hands validate: the command's verdict
// is about the pair, and a store whose settings never matched the config is a
// state boot does not recognise either.
//
// The seeding builds its control-plane server from the shared provider set
// (internal/infrastructure/workflowsteps), which is what every composition root
// registers -- including openStateStoreControlPlane, the root helper the
// recovery path uses. This test cannot call that unexported helper, so it
// registers the same set itself rather than an empty manager: the definitions
// are decoded with the vocabulary the served path validates against, which is
// what makes the seeded values the ones validate is asked about.
func seedStoreResources(t *testing.T, st *store.Store, configPath string) {
t.Helper()
doc, err := configuration.New(nil).Resolve(configPath, "")
if err != nil {
t.Fatalf("resolve %s: %v", configPath, err)
}
steps, err := workflowsteps.NewManager()
if err != nil {
t.Fatalf("register workflow step vocabulary: %v", err)
}
server, err := controlplane.NewServer(st, steps)
if err != nil {
t.Fatalf("build control plane server: %v", err)
}
_, skipped, err := server.ImportConfig(t.Context(), doc.Config)
if err != nil {
t.Fatalf("seed store resources: %v", err)
}
if len(skipped) > 0 {
// This helper stands in for the State Store's own seeding, which seeds
// every kind it can and leaves the rest absent. A skipped kind here
// would mean the fixture store is missing a resource it claims to hold,
// and the verdict under test would be about a different store.
t.Fatalf("seed store resources: %d kind(s) refused: %+v", len(skipped), skipped)
}
}
// storedResourceCount reads the count validate reports out of its summary line.
func storedResourceCount(t *testing.T, stdout string) int {
t.Helper()
before, found := strings.CutSuffix(stdout, " stored resources validate\n")
if !found {
t.Fatalf("no resource count in %q", stdout)
}
fields := strings.Fields(before)
count, err := strconv.Atoi(fields[len(fields)-1])
if err != nil {
t.Fatalf("resource count in %q: %v", stdout, err)
}
return count
}
// seedResource writes one revision of a control-plane resource through the
// store, the way the control plane's replace does. The request ID is derived
// from the label and the revision it produces: the store deduplicates a
// repeated request ID, so a fixed one would make the second write of a series
// a silent no-op.
func seedResource(t *testing.T, st *store.Store, kind, value, label string) {
t.Helper()
current, err := st.Resource(t.Context(), kind)
expected := int64(0)
if err == nil {
expected = current.Version
}
var document any
if err := json.Unmarshal([]byte(value), &document); err != nil {
t.Fatal(err)
}
encoded, err := json.Marshal(document)
if err != nil {
t.Fatal(err)
}
if _, err := st.PutResource(t.Context(), store.ResourceWrite{
Kind: kind, Value: encoded, Actor: label, Source: "test",
RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected,
}); err != nil {
t.Fatalf("seed resource %s: %v", kind, err)
}
}
// execRaw runs one statement against the database file the way an operator
// editing a broken store would, bypassing every check the store applies.
func execRaw(t *testing.T, path, statement string) error {
t.Helper()
db, err := sql.Open("sqlite", path)
if err != nil {
return err
}
defer func() { _ = db.Close() }()
_, err = db.ExecContext(t.Context(), statement)
return err
}
+27 -138
View File
@@ -1,152 +1,41 @@
// This file enforces the objective half of the UI Service deletion gate
// (docs/prds/ui-service-boundary.md, "The deletion gate is objective"). The
// composition half -- no config.Holder, no concrete *store.Store, no Gateway
// runtime type -- is pinned by internal/app/archieui's
// TestComposeUIServerHoldsNoDaemonState. This pins the claim that test cannot
// see: that the linked binary carries no daemon runtime at all. Go imports
// are atomic, so a single reference to a type living beside a runtime relinks
// the runtime, and the severance holds only while something re-measures it.
// This file enforces the dashboard's process boundary
// (docs/prds/external-agent-harness.md, "Session contract", Transport): the
// dashboard must not link the container or daemon internals, because only the
// daemon owns containers. Go imports are atomic, so a single reference
// relinks a runtime, and the boundary holds only while something re-measures
// it. archie-core-h3s0 names this check; it was purged with the test suite and
// is restored here.
package main
import (
"context"
"os/exec"
"strings"
"testing"
"time"
)
const modulePath = "github.com/samcharles93/archie-core/"
// bannedCategory is one class of runtime the UI process must not link. The
// names are the PRD's wording; the prefixes are how that class appears in
// this module.
type bannedCategory struct {
name string
prefixes []string
}
var deletionGate = []bannedCategory{
{"SQL/store implementation", []string{
"modernc.org/sqlite",
modulePath + "internal/store",
}},
{"daemon runtime", []string{
modulePath + "internal/daemon",
modulePath + "internal/app/archied",
modulePath + "internal/container",
modulePath + "internal/worktree",
modulePath + "internal/worktreerpc",
}},
{"workflow engine", []string{
modulePath + "internal/domain/workflow",
modulePath + "internal/taskrun",
modulePath + "internal/agentexec",
}},
{"forge client", []string{
modulePath + "internal/forge",
modulePath + "internal/forgerpc",
}},
{"channel runtime", []string{
modulePath + "internal/channels",
}},
{"model runtime", []string{
modulePath + "internal/gateway",
modulePath + "internal/infrastructure/modelcatalog",
modulePath + "internal/domain/embedding",
modulePath + "internal/infrastructure/embedding",
}},
{"secret runtime", []string{
modulePath + "internal/secret",
}},
{"agent tooling", []string{
modulePath + "internal/tools",
modulePath + "internal/skill",
modulePath + "internal/skillscript",
modulePath + "internal/yaegiutil",
modulePath + "internal/plugin",
}},
{"memory and curator runtime", []string{
modulePath + "internal/domain/memory",
modulePath + "internal/infrastructure/memory",
modulePath + "internal/domain/curator",
modulePath + "internal/infrastructure/sessioncurator",
modulePath + "internal/infrastructure/skillcurator",
}},
{"broker transport", []string{
modulePath + "internal/eventbus",
modulePath + "internal/infrastructure/eventbus",
modulePath + "internal/natsrpc",
}},
}
// bannedExact is banned as a package rather than as a subtree. Nothing may
// reach the database through the UI process, but database/sql/driver and its
// support package arrive from github.com/google/uuid's Valuer/Scanner methods
// and bring no driver with them.
var bannedExact = map[string]string{
"database/sql": "SQL/store implementation",
}
// gateExceptions are packages under a banned prefix that carry only contract,
// vocabulary or view types. The severance moved the UI's references here so
// the parent runtime would stop linking, which makes them the intended end
// state rather than a tolerated leak.
//
// Each one must stay linked. An exception the UI no longer needs is a hole in
// the fence, so this list is checked in both directions.
var gateExceptions = []string{
modulePath + "internal/channels/status",
modulePath + "internal/domain/workflow/task",
}
// under reports whether importPath is prefix or a package below it.
func under(importPath, prefix string) bool {
return importPath == prefix || strings.HasPrefix(importPath, prefix+"/")
}
func TestUIProcessLinksNoDaemonRuntime(t *testing.T) {
listed, err := exec.CommandContext(t.Context(), "go", "list", "-deps", ".").CombinedOutput()
func TestDashboardDoesNotLinkContainerRuntime(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
out, err := exec.CommandContext(ctx, "go", "list", "-deps", ".").Output()
if err != nil {
t.Fatalf("go list -deps .: %v\n%s", err, listed)
t.Fatalf("go list -deps .: %v", err)
}
linkedExceptions := make(map[string]bool, len(gateExceptions))
for importPath := range strings.FieldsSeq(string(listed)) {
if excepted(importPath, linkedExceptions) {
continue
}
if category, banned := bannedExact[importPath]; banned {
reportLink(t, importPath, category)
}
for _, category := range deletionGate {
for _, prefix := range category.prefixes {
if under(importPath, prefix) {
reportLink(t, importPath, category.name)
}
linked := map[string]bool{}
for line := range strings.SplitSeq(strings.TrimSpace(string(out)), "\n") {
linked[line] = true
}
for _, pkg := range []string{
"github.com/samcharles93/archie-core/internal/container",
"github.com/samcharles93/archie-core/internal/app/archied",
"github.com/samcharles93/archie-core/internal/agentexec",
} {
t.Run(pkg, func(t *testing.T) {
if linked[pkg] {
t.Errorf("cmd/archie-ui links %s: only the daemon owns containers", pkg)
}
}
}
for _, exception := range gateExceptions {
if !linkedExceptions[exception] {
t.Errorf("%s is excepted from the deletion gate but is no longer linked; drop the exception instead of leaving its prefix open", exception)
}
})
}
}
func reportLink(t *testing.T, importPath, category string) {
t.Helper()
t.Errorf("archie-ui links %s (%s); the UI process reaches that capability over a contract, never in-process (docs/prds/ui-service-boundary.md, deletion gate)", importPath, category)
}
// excepted reports whether importPath is allowed past the gate, recording
// which exception admitted it so a stale one is reported.
func excepted(importPath string, linked map[string]bool) bool {
for _, exception := range gateExceptions {
if under(importPath, exception) {
linked[exception] = true
return true
}
}
return false
}
-6
View File
@@ -3,8 +3,6 @@
// contracts. It is the .5.2 companion to archie-gateway and
// archie-state-store: a thin main that parses process inputs and hands them
// to archieui.Run.
//
// See docs/prds/ui-service-boundary.md for the ratified boundary.
package main
import (
@@ -29,17 +27,13 @@ func run() int {
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory (only [services.*] targets and [web] are read)")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Listen, "listen", "", "dashboard HTTP listen address (defaults to [web].listen, else 127.0.0.1:8484)")
flag.StringVar(&options.Token, "token", "", "dashboard token; required for a non-loopback listener")
flag.StringVar(&options.TokenFile, "token-file", "", "file holding the dashboard token, minted on first use")
flag.StringVar(&options.OidcIssuer, "oidc-issuer", "", "identity provider issuer URL; requests must then carry a token it signed")
flag.StringVar(&options.OidcAudience, "oidc-audience", "", "audience (resource identifier) this dashboard accepts tokens for; required with -oidc-issuer")
flag.StringVar(&options.OidcClientID, "oidc-client-id", "", "provider client id for browser sign-in; omitted means no sign-in flow")
flag.StringVar(&options.OidcClientSecretEnv, "oidc-client-secret-env", "", "name of the environment variable holding the sign-in client secret")
flag.StringVar(&options.OidcRedirectURL, "oidc-redirect-url", "", "callback URL registered at the provider (path must be /oauth2/callback)")
flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target)")
flag.StringVar(&options.Gateway.Token, "gateway-token", "", "bearer token presented to archie-gateway")
flag.StringVar(&options.State.Target, "state-target", "", "archie-state-store gRPC address (defaults to [services.state].target)")
flag.StringVar(&options.State.Token, "state-token", "", "bearer token presented to archie-state-store")
flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "per-dependency readiness probe timeout (default 5s)")
flag.DurationVar(&options.EventPollInterval, "event-poll-interval", 0, "how often the activity feed polls the State Store for new events (default 1s)")
// BoolFunc rather than BoolVar so an unset flag stays distinguishable
-967
View File
@@ -1,967 +0,0 @@
// Package main's smoke test runs the real archie-ui binary against a State
// Store and a Gateway reached over loopback gRPC, and drives it through HTTP
// the way an operator's browser does.
//
// The in-process suite (internal/app/archieui) proves the composition; this
// proves the process: flags and configuration file, listener bind, dashboard
// token, SPA assets, streamed chat, an operator task action crossing to the
// Gateway, the degradations the PRD ratified, dependency loss while running,
// and a clean SIGTERM. See docs/prds/ui-service-boundary.md, migration
// sequence step 6.
package main
import (
"bufio"
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"log/slog"
"net"
"net/http"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"sync"
"syscall"
"testing"
"time"
"google.golang.org/grpc"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/health"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/webui"
)
const dashboardToken = "smoke-token"
// fakeGateway stands in for the archie-gateway process. The dashboard only
// needs the Gateway to answer, stream, and accept an operator action, so the
// rest satisfy messaging.ChatContract without pretending to do more.
type fakeGateway struct {
mu sync.Mutex
actions []string
}
func (f *fakeGateway) Snapshot(context.Context) (messaging.ChatSnapshot, error) {
return messaging.ChatSnapshot{
Sessions: []messaging.SessionContext{{
SessionID: "s1",
Source: messaging.SessionSource{Platform: "web", ChannelID: "dash"},
}},
Models: []string{"test/model"},
ActiveModel: "test/model",
ActivePersonas: map[string]string{},
CancellationAvailable: true,
}, nil
}
func (f *fakeGateway) GetSession(context.Context, string) (messaging.SessionContext, bool, error) {
return messaging.SessionContext{}, false, nil
}
func (f *fakeGateway) RecentMessages(context.Context, string, int) ([]messaging.Message, error) {
return nil, nil
}
func (f *fakeGateway) RecentTurns(context.Context, string, int) ([]messaging.TurnRecord, error) {
return nil, nil
}
func (f *fakeGateway) Route(context.Context, messaging.Inbound) (messaging.ChatReply, error) {
return messaging.ChatReply{Text: "routed", SessionID: "s1"}, nil
}
// Stream emits the contract's documented order: started, a delta, then done.
//
// A turn that used a tool emits its tool event between the delta and the done,
// which is where the Gateway's own stream reports completed tool activity.
// Whether the dashboard renders it is the operator's setting, carried to this
// process only by the published configuration projection (GitHub #821).
func (f *fakeGateway) Stream(ctx context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) {
events := make(chan messaging.ChatEvent, 4)
go func() {
defer close(events)
turn := []messaging.ChatEvent{
{Kind: "started", SessionID: "s1"},
{Kind: "delta", Text: "hello " + in.Message.Text, SessionID: "s1"},
{Kind: "done", SessionID: "s1"},
}
if in.Message.Text == toolCallPrompt {
turn = []messaging.ChatEvent{
{Kind: "started", SessionID: "s1"},
{Kind: "tool", SessionID: "s1", Tool: messaging.ToolCallEvent{
ID: "call-1", Name: "read_file", Parameters: `{"path":"main.go"}`,
Output: "package main",
}},
{Kind: "delta", Text: "read it", SessionID: "s1"},
{Kind: "done", SessionID: "s1"},
}
}
for _, event := range turn {
select {
case events <- event:
case <-ctx.Done():
return
}
}
}()
return events, nil
}
// toolCallPrompt is the message this suite sends when it wants the fake
// Gateway to report a completed tool call in the turn.
const toolCallPrompt = "read main.go"
func (f *fakeGateway) Cancel(context.Context, string) (messaging.ChatCancellation, error) {
return messaging.ChatCancellation{Cancelled: true}, nil
}
func (f *fakeGateway) SetPersona(context.Context, string, string) (bool, error) { return false, nil }
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action) (messaging.TaskActionResult, error) {
return messaging.TaskActionResult{}, nil
}
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action) (messaging.TaskActionResult, error) {
f.mu.Lock()
defer f.mu.Unlock()
f.actions = append(f.actions, fmt.Sprintf("%d:%s", id, action))
return messaging.TaskActionResult{TaskID: id, Action: string(action)}, nil
}
func (f *fakeGateway) applied() []string {
f.mu.Lock()
defer f.mu.Unlock()
return append([]string(nil), f.actions...)
}
// repoRoot walks up from this test's source directory to the module root, so
// the build works regardless of the harness working directory.
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot determine test source path")
}
dir := filepath.Dir(file)
for {
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
return dir
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("go.mod not found above test source")
}
dir = parent
}
}
func buildUIBinary(t *testing.T, dir string) string {
t.Helper()
bin := filepath.Join(dir, "archie-ui")
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-ui")
cmd.Dir = repoRoot(t)
cmd.Env = os.Environ()
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("go build archie-ui: %v\n%s", err, out)
}
return bin
}
// syncBuffer is a concurrency-safe sink for the subprocess's stderr: the
// os/exec goroutine writes while the test reads it to recover the bound
// address and to report it on failure.
type syncBuffer struct {
mu sync.Mutex
b bytes.Buffer
}
func (s *syncBuffer) Write(p []byte) (int, error) {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.Write(p)
}
func (s *syncBuffer) String() string {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.String()
}
// serveGRPC runs register against a fresh loopback listener, returning the
// dial target and a stop func so a test can take the dependency away.
func serveGRPC(t *testing.T, register func(grpc.ServiceRegistrar)) (target string, stop func()) {
t.Helper()
listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("listen: %v", err)
}
server := grpc.NewServer()
register(server)
go func() { _ = server.Serve(listener) }()
t.Cleanup(server.Stop)
return listener.Addr().String(), server.Stop
}
// writeUIConfig writes the config.toml an operator would keep: the service
// endpoints the UI dials live in it, so the process is started without
// -gateway-target or -state-target and has to read them itself. The rest is
// what configuration validation requires of any archie config file.
func writeUIConfig(t *testing.T, dir, stateTarget, gatewayTarget string) string {
t.Helper()
path := filepath.Join(dir, "config.toml")
content := fmt.Sprintf(`bot_user = "archie-bot"
db_path = %q
[forge]
type = "github"
host = "https://github.example.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
[[repos]]
owner = "acme"
name = "widget"
[services.state]
target = %q
[services.gateway]
target = %q
`, filepath.Join(dir, "archie.db"), stateTarget, gatewayTarget)
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
t.Fatalf("write ui config: %v", err)
}
return path
}
// uiProcess is a running archie-ui, plus the address it actually bound.
type uiProcess struct {
cmd *exec.Cmd
addr string
log *syncBuffer
}
func startUIProcess(t *testing.T, bin, cfg string) *uiProcess {
t.Helper()
// The process outlives t.Context() deliberately: that context is
// cancelled just before cleanups run, which would SIGKILL archie-ui out
// from under the graceful-shutdown check in stop. Cancelling this one is
// registered first, so it runs last and only backstops a process that
// ignored SIGTERM.
ctx, cancel := context.WithCancel(context.WithoutCancel(t.Context()))
t.Cleanup(cancel)
cmd := exec.CommandContext(
ctx, bin,
"-config", cfg,
"-listen", "127.0.0.1:0",
"-token", dashboardToken,
)
cmd.Env = append(os.Environ(), "ARCHIE_GITHUB_TOKEN=test-token")
var log syncBuffer
cmd.Stderr = &log
cmd.Stdout = &log
if err := cmd.Start(); err != nil {
t.Fatalf("start archie-ui: %v", err)
}
p := &uiProcess{cmd: cmd, log: &log}
t.Cleanup(func() { p.stop(t) })
// -listen 127.0.0.1:0 means the kernel picks the port, so the bound
// address comes back out of the process's own startup log.
deadline := time.Now().Add(20 * time.Second)
for time.Now().Before(deadline) && p.addr == "" {
if cmd.ProcessState != nil {
t.Fatalf("archie-ui exited early:\n%s", log.String())
}
p.parseAddr()
if p.addr == "" {
time.Sleep(25 * time.Millisecond)
}
}
if p.addr == "" {
t.Fatalf("did not recover the bound address from the log:\n%s", log.String())
}
waitHealthy(t, p)
return p
}
func (p *uiProcess) parseAddr() {
scanner := bufio.NewScanner(strings.NewReader(p.log.String()))
for scanner.Scan() {
var record map[string]any
if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
continue
}
if msg, _ := record["msg"].(string); msg != "archie-ui running" {
continue
}
if addr, ok := record["addr"].(string); ok && addr != "" {
p.addr = addr
return
}
}
}
func waitHealthy(t *testing.T, p *uiProcess) {
t.Helper()
deadline := time.Now().Add(20 * time.Second)
for time.Now().Before(deadline) {
req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "http://"+p.addr+"/healthz", nil)
if err != nil {
t.Fatalf("build liveness request: %v", err)
}
if resp, err := http.DefaultClient.Do(req); err == nil {
_ = resp.Body.Close()
if resp.StatusCode == http.StatusOK {
return
}
}
time.Sleep(25 * time.Millisecond)
}
t.Fatalf("/healthz never answered:\n%s", p.log.String())
}
// stop ends the process the way a service manager does and reports a
// non-graceful exit, which is how a shutdown-ordering regression surfaces.
func (p *uiProcess) stop(t *testing.T) {
t.Helper()
if p.cmd.Process == nil || p.cmd.ProcessState != nil {
return
}
if err := p.cmd.Process.Signal(syscall.SIGTERM); err != nil {
t.Errorf("SIGTERM archie-ui: %v", err)
return
}
done := make(chan error, 1)
go func() { done <- p.cmd.Wait() }()
select {
case err := <-done:
if err != nil {
t.Errorf("archie-ui exited %v after SIGTERM, want a clean shutdown:\n%s", err, p.log.String())
}
case <-time.After(20 * time.Second):
_ = p.cmd.Process.Kill()
t.Errorf("archie-ui did not exit within 20s of SIGTERM:\n%s", p.log.String())
}
}
// reply is one dashboard response, already read and closed. The assertions
// want the status and the bytes rather than a live body, and handing back a
// closed value keeps the close where the read is.
type reply struct {
status int
header http.Header
body []byte
}
func (r reply) cookies() []*http.Cookie {
return (&http.Response{Header: r.header}).Cookies()
}
// dashboard is a browser-shaped client for the running process.
type dashboard struct {
t *testing.T
base string
client *http.Client
}
// noRedirect returns a dashboard that reports a redirect rather than
// following it, so an exchange can be inspected instead of chased. Following
// it here would land on the clean URL without the cookie jar a browser has.
func (d dashboard) noRedirect() dashboard {
d.client = &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error {
return http.ErrUseLastResponse
}}
return d
}
func (d dashboard) do(req *http.Request) reply {
d.t.Helper()
client := d.client
if client == nil {
client = http.DefaultClient
}
resp, err := client.Do(req)
if err != nil {
d.t.Fatalf("%s %s: %v", req.Method, req.URL.Path, err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
d.t.Fatalf("read %s: %v", req.URL.Path, err)
}
return reply{status: resp.StatusCode, header: resp.Header, body: body}
}
func (d dashboard) request(method, path, body string, authorized bool) *http.Request {
d.t.Helper()
var reader io.Reader = http.NoBody
if body != "" {
reader = strings.NewReader(body)
}
req, err := http.NewRequestWithContext(d.t.Context(), method, d.base+path, reader)
if err != nil {
d.t.Fatalf("build %s %s: %v", method, path, err)
}
if authorized {
req.Header.Set("Authorization", "Bearer "+dashboardToken)
}
if body != "" {
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Archie-CSRF", "1")
}
return req
}
func (d dashboard) get(path string) reply {
d.t.Helper()
return d.do(d.request(http.MethodGet, path, "", true))
}
// chatFrame is one `data: {...}` frame of the chat stream, decoded into the
// fields this suite reads. The UI process only ever receives these over HTTP,
// so asserting on them is asserting on what the browser is handed.
type chatFrame struct {
Type string `json:"type"`
Text string `json:"text"`
Tool string `json:"tool"`
}
// streamChat runs one chat turn over the real HTTP stream and returns every
// frame up to and including the terminating done.
func streamChat(t *testing.T, d dashboard, prompt string) []chatFrame {
t.Helper()
body, err := json.Marshal(map[string]string{"text": prompt, "channel_id": "dash"})
if err != nil {
t.Fatalf("encode the chat turn: %v", err)
}
resp, err := http.DefaultClient.Do(d.request(http.MethodPost, "/api/chat/stream", string(body), true))
if err != nil {
t.Fatalf("POST /api/chat/stream: %v", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Fatalf("POST /api/chat/stream = %d, want 200", resp.StatusCode)
}
var frames []chatFrame
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
payload, ok := strings.CutPrefix(scanner.Text(), "data: ")
if !ok {
continue
}
var frame chatFrame
if err := json.Unmarshal([]byte(payload), &frame); err != nil {
t.Fatalf("decode stream frame %q: %v", payload, err)
}
frames = append(frames, frame)
if frame.Type == "done" {
break
}
}
if err := scanner.Err(); err != nil {
t.Fatalf("read the chat stream: %v", err)
}
return frames
}
// seedStore fills a real task database and publishes the configuration
// projection, so everything the dashboard renders arrives over the wire from
// a store this process never opens.
//
// The document is rendered by webui.BuildConfigView -- the same function the
// daemon calls -- from a config.Config rather than hand-written as a
// ConfigView. A suite that hand-writes the document cannot catch a producer
// that forgets to publish a field, which is the failure mode this covers:
// chat.show_tool_calls, the operator name and the channel flag all reach the
// extracted process through this projection and nowhere else (GitHub #821).
func seedStore(t *testing.T, dir string) *store.Store {
t.Helper()
st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite"))
if err != nil {
t.Fatalf("open store: %v", err)
}
t.Cleanup(func() { _ = st.Close() })
if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "smoke task", "body", "", ""); err != nil {
t.Fatalf("seed task: %v", err)
}
tasks, err := st.Tasks(t.Context(), 10)
if err != nil || len(tasks) != 1 {
t.Fatalf("seeded tasks = %d (%v), want 1", len(tasks), err)
}
seeded := tasks[0]
seeded.PRNumber = 34
if err := st.Update(t.Context(), &seeded); err != nil {
t.Fatalf("record PR number: %v", err)
}
publishConfig(t, st, daemonConfig(true))
return st
}
// daemonConfig is the configuration the daemon would hold for this smoke run.
// showToolCalls is the setting the chat page's expansion is gated on.
func daemonConfig(showToolCalls bool) config.Config {
return config.Config{
BotUser: "archie-bot",
Forge: config.Forge{Type: "github", Host: "https://github.example.com"},
Repos: []config.Repo{{Owner: "acme", Name: "widget", Base: "main"}},
Chat: config.ChatConfig{
ShowToolCalls: showToolCalls,
Operator: "Sam",
WebhookAddr: "127.0.0.1:9099",
},
}
}
// publishConfig renders cfg the way the daemon's configuration owner does and
// writes the result to the store the UI process reads it back from. The UI
// process holds no configuration, so this is the only path by which a setting
// reaches its pages.
func publishConfig(t *testing.T, st *store.Store, cfg config.Config) {
t.Helper()
document, err := json.Marshal(webui.BuildConfigView(webui.ConfigViewInput{Config: cfg}))
if err != nil {
t.Fatalf("render the configuration projection: %v", err)
}
if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{
Schema: webui.ConfigViewSchema, Document: document,
}); err != nil {
t.Fatalf("publish config snapshot: %v", err)
}
}
// TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge drives the real
// binary against a State Store holding a multi-identity deployment's
// projection. Task rows in such a deployment used to render no link at all:
// the projection carried the default identity's forge alone, so the renderer
// withheld rather than pointing every row at the wrong forge
// (archie-core-pv6t). With per-identity forges published, each row is
// attributed to the identity that owns it, by identity name first and repo
// ownership second.
//
// Its own store and process: it publishes a different projection than the
// single-identity smoke test, and republishing over a shared one would rewire
// that test's page underneath it.
func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) {
dir := t.TempDir()
st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite"))
if err != nil {
t.Fatalf("open store: %v", err)
}
t.Cleanup(func() { _ = st.Close() })
// One task carrying its identity (name resolves it), one without an
// identity but on a repo only the Gitea identity owns (ownership
// resolves it), and one on a repo both identities claim (ambiguous, so
// it falls back to the default forge).
for _, seed := range []struct {
owner, repo, identity string
number int
}{
{owner: "acme", repo: "widget", identity: "gitea-bot", number: 7},
{owner: "beta", repo: "svc", number: 8},
{owner: "acme", repo: "shared", number: 9},
} {
if _, err := st.EnqueueIssue(t.Context(), seed.owner, seed.repo, seed.number, "seeded", "body", "", seed.identity); err != nil {
t.Fatalf("seed %s/%s: %v", seed.owner, seed.repo, err)
}
}
published, err := json.Marshal(webui.ConfigView{
Identity: webui.IdentityView{BotUser: "archie-bot", ForgeType: "github", ForgeHost: "https://github.example.com"},
MultiIdentity: true,
Identities: []webui.ForgeIdentityView{
{
Name: "gitea-bot", ForgeType: "gitea", ForgeHost: "https://gitea.example.com",
Repos: []webui.ForgeRepoView{{Owner: "acme", Name: "widget"}, {Owner: "acme", Name: "shared"}},
},
{
Name: "github-bot", ForgeType: "github", ForgeHost: "https://github.example.com",
Repos: []webui.ForgeRepoView{{Owner: "beta", Name: "svc"}, {Owner: "acme", Name: "shared"}},
},
},
})
if err != nil {
t.Fatal(err)
}
if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{
Schema: webui.ConfigViewSchema, Document: published,
}); err != nil {
t.Fatalf("publish config snapshot: %v", err)
}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
})
})
defer stopState()
gatewayTarget, stopGateway := serveGRPC(t, func(r grpc.ServiceRegistrar) {
gatewayrpc.RegisterServer(r, &fakeGateway{})
})
defer stopGateway()
ui := startUIProcess(t, buildUIBinary(t, dir), writeUIConfig(t, dir, stateTarget, gatewayTarget))
d := dashboard{t: t, base: "http://" + ui.addr}
got := d.get("/api/tasks")
if got.status != http.StatusOK {
t.Fatalf("GET /api/tasks = %d (%s), want 200", got.status, got.body)
}
var rows []struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
IssueNumber int `json:"issue_number"`
RepoURL string `json:"repo_url"`
IssueURL string `json:"issue_url"`
}
if err := json.Unmarshal(got.body, &rows); err != nil {
t.Fatalf("decode task rows: %v (%s)", err, got.body)
}
if len(rows) != 3 {
t.Fatalf("task rows = %d, want the 3 seeded behind the State Store (%s)", len(rows), got.body)
}
want := map[string]string{
"acme/widget#7": "https://gitea.example.com/acme/widget/issues/7",
"beta/svc#8": "https://github.example.com/beta/svc/issues/8",
"acme/shared#9": "https://github.example.com/acme/shared/issues/9",
}
for _, row := range rows {
key := fmt.Sprintf("%s/%s#%d", row.Owner, row.Repo, row.IssueNumber)
expected, ok := want[key]
if !ok {
t.Errorf("unexpected row %q (%s)", key, got.body)
continue
}
if row.RepoURL == "" || row.IssueURL != expected {
t.Errorf("row %s links = %q, %q; want %q", key, row.RepoURL, row.IssueURL, expected)
}
}
}
func TestUIProcessServesTheDashboardAgainstLiveDependencies(t *testing.T) {
dir := t.TempDir()
st := seedStore(t, dir)
gateway := &fakeGateway{}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
})
})
gatewayTarget, _ := serveGRPC(t, func(r grpc.ServiceRegistrar) {
gatewayrpc.RegisterServer(r, gateway)
})
ui := startUIProcess(t, buildUIBinary(t, dir), writeUIConfig(t, dir, stateTarget, gatewayTarget))
d := dashboard{t: t, base: "http://" + ui.addr}
t.Run("liveness stays unauthenticated", func(t *testing.T) {
for _, path := range []string{"/healthz", "/health"} {
if got := d.do(d.request(http.MethodGet, path, "", false)); got.status != http.StatusOK {
t.Errorf("GET %s = %d without a token, want 200: probes must not need the dashboard token", path, got.status)
}
}
})
t.Run("an unauthenticated API request is refused", func(t *testing.T) {
if got := d.do(d.request(http.MethodGet, "/api/tasks", "", false)); got.status != http.StatusUnauthorized {
t.Errorf("GET /api/tasks = %d without a token, want 401", got.status)
}
wrong := d.request(http.MethodGet, "/api/tasks", "", false)
wrong.Header.Set("Authorization", "Bearer not-the-token")
if got := d.do(wrong); got.status != http.StatusUnauthorized {
t.Errorf("GET /api/tasks = %d with a wrong token, want 401", got.status)
}
})
t.Run("the token in the URL is exchanged for a cookie", func(t *testing.T) {
got := d.noRedirect().do(d.request(http.MethodGet, "/?t="+dashboardToken, "", false))
if got.status != http.StatusSeeOther {
t.Fatalf("GET /?t=<token> = %d, want 303 onto the clean URL", got.status)
}
var carried bool
for _, cookie := range got.cookies() {
if cookie.Value == dashboardToken && cookie.HttpOnly {
carried = true
}
}
if !carried {
t.Errorf("no HttpOnly cookie carried the token; it would stay in browser history (%v)", got.cookies())
}
})
t.Run("task rows carry forge links from the published projection", func(t *testing.T) {
got := d.get("/api/tasks")
if got.status != http.StatusOK {
t.Fatalf("GET /api/tasks = %d (%s), want 200", got.status, got.body)
}
var rows []struct {
ID int64 `json:"id"`
RepoURL string `json:"repo_url"`
IssueURL string `json:"issue_url"`
PRURL string `json:"pr_url"`
}
if err := json.Unmarshal(got.body, &rows); err != nil {
t.Fatalf("decode task rows: %v (%s)", err, got.body)
}
if len(rows) != 1 {
t.Fatalf("task rows = %d, want the 1 seeded behind the State Store (%s)", len(rows), got.body)
}
const repoURL = "https://github.example.com/acme/widget"
if rows[0].RepoURL != repoURL || rows[0].IssueURL != repoURL+"/issues/7" || rows[0].PRURL != repoURL+"/pull/34" {
t.Errorf("forge links = %q, %q, %q; want them built from the daemon's published projection, since this process holds no configuration of its own",
rows[0].RepoURL, rows[0].IssueURL, rows[0].PRURL)
}
})
t.Run("the SPA and its assets are served", func(t *testing.T) {
index := d.get("/")
if index.status != http.StatusOK || !bytes.Contains(bytes.ToLower(index.body), []byte("<!doctype html")) {
t.Errorf("GET / = %d serving %d bytes; want the embedded index.html", index.status, len(index.body))
}
for path, wantType := range map[string]string{
"/assets/index.js": "javascript",
"/assets/index.css": "css",
} {
asset := d.get(path)
if asset.status != http.StatusOK {
t.Errorf("GET %s = %d, want the embedded asset", path, asset.status)
continue
}
if contentType := asset.header.Get("Content-Type"); !strings.Contains(contentType, wantType) {
t.Errorf("GET %s Content-Type = %q, want %s", path, contentType, wantType)
}
if len(asset.body) == 0 {
t.Errorf("GET %s served an empty body", path)
}
}
})
t.Run("chat streams over the Gateway contract", func(t *testing.T) {
req := d.request(http.MethodPost, "/api/chat/stream", `{"text":"there","channel_id":"dash"}`, true)
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("POST /api/chat/stream: %v", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Fatalf("POST /api/chat/stream = %d, want 200", resp.StatusCode)
}
if contentType := resp.Header.Get("Content-Type"); !strings.Contains(contentType, "text/event-stream") {
t.Fatalf("stream Content-Type = %q, want text/event-stream", contentType)
}
var kinds []string
var text string
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
payload, ok := strings.CutPrefix(scanner.Text(), "data: ")
if !ok {
continue
}
var frame struct {
Type string `json:"type"`
Text string `json:"text"`
}
if err := json.Unmarshal([]byte(payload), &frame); err != nil {
t.Fatalf("decode stream frame %q: %v", payload, err)
}
kinds = append(kinds, frame.Type)
if frame.Type == "delta" {
text += frame.Text
}
if frame.Type == "done" {
break
}
}
if strings.Join(kinds, ",") != "started,delta,done" {
t.Errorf("stream frames = %v, want started,delta,done in order", kinds)
}
if text != "hello there" {
t.Errorf("streamed text = %q, want the Gateway's reply relayed verbatim", text)
}
})
t.Run("the daemon's show_tool_calls setting decides whether tool calls reach the chat page", func(t *testing.T) {
// The chat page expands a completed tool call only when the frame
// arrives, and this process has no [chat] section of its own: the
// setting reaches it through the published projection alone. A turn
// streamed with the setting off must carry no tool frame, and one
// streamed with it on must carry the tool the Gateway reported
// (GitHub #821).
//
// Each case republishes before streaming, the way a config reload
// does; the default is restored afterwards so a later subtest does
// not inherit whichever case ran last.
tests := []struct {
name string
showTools bool
wantFrame bool
}{
{name: "off", showTools: false, wantFrame: false},
{name: "on", showTools: true, wantFrame: true},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
publishConfig(t, st, daemonConfig(tc.showTools))
frames := streamChat(t, d, toolCallPrompt)
var sawTool bool
for _, frame := range frames {
if frame.Tool == "read_file" {
sawTool = true
}
if frame.Type == "done" {
break
}
}
if sawTool != tc.wantFrame {
t.Errorf("show_tool_calls=%v produced tool frame = %v, want %v; frames = %+v",
tc.showTools, sawTool, tc.wantFrame, frames)
}
})
}
publishConfig(t, st, daemonConfig(true))
})
t.Run("an operator task action crosses to the Gateway", func(t *testing.T) {
listed := d.get("/api/tasks")
var rows []struct {
ID int64 `json:"id"`
}
if err := json.Unmarshal(listed.body, &rows); err != nil || len(rows) != 1 {
t.Fatalf("decode task rows: %v (%s)", err, listed.body)
}
path := fmt.Sprintf("/api/tasks/%d/action", rows[0].ID)
action := string(taskstate.ActionCancel)
if got := d.do(d.request(http.MethodPost, path, `{"action":"`+action+`"}`, true)); got.status != http.StatusOK {
t.Fatalf("POST %s = %d (%s), want 200", path, got.status, got.body)
}
want := fmt.Sprintf("%d:%s", rows[0].ID, action)
if applied := gateway.applied(); len(applied) != 1 || applied[0] != want {
t.Errorf("Gateway saw %v, want exactly [%s]: the UI must not mutate task state itself", applied, want)
}
// The same action without the CSRF header is refused, so a
// cross-site form post cannot drive the daemon.
noCSRF := d.request(http.MethodPost, path, "", true)
noCSRF.Body = io.NopCloser(strings.NewReader(`{"action":"` + action + `"}`))
noCSRF.Header.Set("Content-Type", "application/json")
if got := d.do(noCSRF); got.status != http.StatusForbidden {
t.Errorf("POST %s without the CSRF header = %d, want 403", path, got.status)
}
})
t.Run("capture intake is served without the dashboard token", func(t *testing.T) {
accepted := d.do(d.request(http.MethodPost, "/webhooks/capture/demo", "", false))
if accepted.status != http.StatusAccepted {
t.Fatalf("POST /webhooks/capture/demo = %d (%s), want 202: this process is the only listener serving intake after the cutover", accepted.status, accepted.body)
}
listed := d.get("/api/captures")
if listed.status != http.StatusOK || !strings.Contains(string(listed.body), `"enabled":true`) {
t.Errorf("GET /api/captures = %d (%s), want the capture list over the State Store", listed.status, listed.body)
}
})
t.Run("routes with no owner degrade explicitly", func(t *testing.T) {
// The daemon's log feed is host-local and has no contract, so the
// page reports itself off rather than erroring
// (docs/prds/ui-service-boundary.md, route family table).
logs := d.get("/api/logs")
if logs.status != http.StatusOK || !strings.Contains(string(logs.body), `"disabled":true`) {
t.Errorf("GET /api/logs = %d (%s), want an explicit disabled report", logs.status, logs.body)
}
if version := d.get("/api/version"); version.status != http.StatusNotImplemented {
t.Errorf("GET /api/version = %d, want 501: host-local update reporting stays with the daemon", version.status)
}
// Configuration renders from the published snapshot, and this
// process is not a second writer.
rendered := d.get("/api/config")
if rendered.status != http.StatusOK {
t.Fatalf("GET /api/config = %d (%s), want 200", rendered.status, rendered.body)
}
var view webui.ConfigView
if err := json.Unmarshal(rendered.body, &view); err != nil {
t.Fatalf("decode config view: %v (%s)", err, rendered.body)
}
if view.Identity.BotUser != "archie-bot" {
t.Errorf("config view = %s, want the published projection rendered read-only", rendered.body)
}
if got := d.do(d.request(http.MethodPatch, "/api/config", `{}`, true)); got.status != http.StatusMethodNotAllowed {
t.Errorf("PATCH /api/config = %d, want 405: configuration is read here and written through the control plane", got.status)
}
// The setup checklist reads the same projection. It reported
// nothing here while it needed a live config.Holder this process
// never receives (archie-core-ml30).
setup := d.get("/api/setup")
if setup.status != http.StatusOK {
t.Fatalf("GET /api/setup = %d (%s), want 200", setup.status, setup.body)
}
var checklist struct {
Steps []struct {
Title string `json:"title"`
Done bool `json:"done"`
} `json:"steps"`
Operator string `json:"operator"`
}
if err := json.Unmarshal(setup.body, &checklist); err != nil {
t.Fatalf("decode setup checklist: %v (%s)", err, setup.body)
}
if len(checklist.Steps) == 0 {
t.Errorf("setup checklist is empty; the published projection carries what it reads (%s)", setup.body)
}
if checklist.Operator != "Sam" {
t.Errorf("setup operator = %q, want the published name", checklist.Operator)
}
for _, step := range checklist.Steps {
if step.Title == "Connect a repository" && !step.Done {
t.Errorf("checklist says no repository is connected; the projection publishes one (%s)", setup.body)
}
}
})
// Last: taking the State Store away is not reversible for this process.
t.Run("losing a dependency degrades readiness without failing liveness", func(t *testing.T) {
healthy := d.get("/health/detailed")
if healthy.status != http.StatusOK {
t.Fatalf("GET /health/detailed = %d (%s), want 200", healthy.status, healthy.body)
}
var report health.Report
if err := json.Unmarshal(healthy.body, &report); err != nil {
t.Fatalf("decode readiness: %v (%s)", err, healthy.body)
}
if report.Status != health.StatusOK {
t.Fatalf("readiness = %s with both dependencies up, want ok (%s)", report.Status, healthy.body)
}
stopState()
degraded := d.get("/health/detailed")
if err := json.Unmarshal(degraded.body, &report); err != nil {
t.Fatalf("decode readiness after outage: %v (%s)", err, degraded.body)
}
if report.Status == health.StatusOK {
t.Errorf("readiness stayed ok with the State Store stopped (%s)", degraded.body)
}
if live := d.do(d.request(http.MethodGet, "/healthz", "", false)); live.status != http.StatusOK {
t.Errorf("GET /healthz = %d during a dependency outage, want 200: liveness must not imply dependency readiness", live.status)
}
})
}
+34 -3
View File
@@ -2,18 +2,49 @@
package main
import (
"fmt"
"os"
"strings"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/archieplaybooks"
"github.com/samcharles93/archie-core/internal/app/prbench"
)
const commandUsage = "usage: archied [flags] # run the daemon; archied -h lists the flags\n" +
"subcommands: setup, update, release, status, prbench, playbooks"
func main() {
args := os.Args[1:]
os.Exit(run(os.Args[1:]))
}
func run(args []string) int {
// The setup generator is dispatched before the daemon's flags are
// parsed: it writes a first-run config.toml and must not touch the
// store, NATS, or the running daemon's configuration.
if archied.IsSetupArgs(args) {
os.Exit(archied.RunSetup(args[1:], os.Stdin, os.Stdout, os.Stderr))
return archied.RunSetup(args[1:], os.Stdin, os.Stdout, os.Stderr)
}
os.Exit(archied.Run())
if len(args) > 0 {
switch args[0] {
case "update":
return archied.RunUpdate(args[1:], os.Stdout, os.Stderr)
case "release":
return archied.RunRelease(args[1:], os.Stdout, os.Stderr)
case "status":
return archied.RunStatus(args[1:], os.Stdout, os.Stderr)
case "prbench":
return prbench.Main(args[1:], os.Stdout, os.Stderr)
case "playbooks":
return archieplaybooks.Run(args[1:], os.Stderr)
}
// A word that is not a subcommand is refused rather than ignored: a
// stale `archied update-topology` would otherwise start a second
// daemon under the running one's feet.
if !strings.HasPrefix(args[0], "-") {
fmt.Fprintf(os.Stderr, "archied: unknown command %q\n%s\n", args[0], commandUsage)
return 2
}
}
return archied.Run()
}
+74 -494
View File
@@ -1,533 +1,113 @@
# archie configuration
#
# archied configuration
# This file starts the services. Everything else (forge connections, models,
# providers, chat, tools, containers, repositories, policies) is edited in the
# dashboard, and a saved value there overrides the same setting here.
#
# Secrets are NOT stored here: each one is a {engine, key}
# reference resolved through a secrets engine at startup.
# The built-in "env" engine reads key as an environment variable name;
# "bws" (Bitwarden Secrets Manager) is compiled in. Custom engines are
# Yaegi plugins loaded from this directory -- reference implementations
# for sops, vault/openbao and age ship in examples/secret-engines/ and
# each needs its CLI on PATH plus engine-specific env (sops: SOPS_FILE;
# vault: VAULT_ADDR, VAULT_TOKEN, optional VAULT_SECRET_PATH;
# age: AGE_FILE, AGE_IDENTITY).
# secret_engine_dir = "~/.config/archie/secret-engines"
# Secrets are never written here: each is a {engine, key} reference. The
# built-in "env" engine reads key as an environment variable.
# work_dir = "~/.local/share/archie/work" # default
# db_path = "~/.local/share/archie/archie.db" # prefix for independent task and conversation SQLite files
# skills_dir = "~/.local/share/archie/skills" # SKILL.md search path; defaults under work_dir when unset
# plugin_dir = "~/.local/share/archie/plugins" # daemon plugin manifests; unset means no plugins are loaded
# module_dir = "~/.local/share/archie/modules" # EDA playbook Module action kinds (log.go etc.); unset means no modules loaded
# workflow_routing_file = "~/.local/share/archie/workflow-routing.yaml" # kind->workflow rebinding (bug/feature/bootstrap)
# workflow_labels_file = "~/.local/share/archie/workflow-labels.yaml" # arbitrary forge label -> workflow (EDA playbook slice 2)
# playbook_dirs = ["~/.local/share/archie/workflows"] # list of dirs of *.yaml binding files, merged with the two above (slice 3); a key bound twice across sources is a load failure
# eda_playbook_dir = "~/.local/share/archie/eda-playbooks" # rich EDA playbook documents (one trigger; either a CEL-gated workflow action or a list of module actions); a matching workflow playbook decides the task's workflow ahead of the three binding sources above; distinct from playbook_dirs
# database_url = "postgres://archie:archie@localhost:5432/archie?sslmode=disable"
# work_dir = "~/.local/share/archie/work"
# state_dir = "~/.local/share/archie"
poll_interval = "60s"
label = "archie"
bot_user = "vectis-labs-archie"
# 0 switches the cap off; omit the key to take the built-in default (400).
diff_cap_lines = 400
# how many operator-triggered retries a parked task gets
# before it moves to dead (global default; set per-repo to
# override). Enforced by the dashboard's retry action.
# max_retries = 3
[forge]
type = "github"
host = "https://github.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
# How forge issues become work:
# "poll" – re-discover issues each poll_interval (default)
# "webhook" – react to GitHub webhook events the moment they arrive
# "both" – webhook plus the poll as a backstop
# intake = "poll"
# Required when intake is "webhook" or "both": the shared secret configured
# on the GitHub webhook, and the host:port the receiver listens on. On
# GitHub, set the webhook's Content type to application/json (the UI
# default) -- the alternate form-encoded delivery is not supported.
# Webhook intake is single-identity, and that is enforced: with [[identities]]
# configured this combination is REJECTED at startup rather than silently
# downgraded to polling. The receiver binds one secret and one dispatch
# predicate, so it could only judge another identity's events by the wrong
# rules. Either drop the [[identities]] blocks, or keep intake = "poll" and
# let each identity poll.
# intake = "poll" # "poll", "webhook" or "both"
# webhook_secret = { engine = "env", key = "ARCHIE_WEBHOOK_SECRET" }
# webhook_addr = "0.0.0.0:8645"
# intake, webhook_secret and webhook_addr exist only here. Set on a
# [identities.forge] entry they are REJECTED for the same reason: nothing
# reads them, so the identity would silently keep polling. Serving webhook
# intake per identity is a pending migration, not a setting.
# [[identities]] runs more than one bot identity from a single daemon, each
# with its own forge/dispatch/models/providers/budgets/notify -- see
# docs/architecture/identity.md for the full design and constraints (e.g.
# intake settings are rejected per identity, and [forge].intake =
# "webhook"/"both" is rejected alongside [[identities]]). Minimal shape:
# [[identities]]
# name = "personal" # required; namespaces logs/events/NATS subjects
# bot_user = "your-bot" # required
# forge = { type = "github", host = "https://github.com", token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN_PERSONAL" } }
[dispatch]
# Can be of "assignee", "label", or "either"
# this sets the method archie uses to pick up tasks.
trigger = "assignee"
trigger = "assignee" # "assignee", "label" or "either"
ack_reaction = "eyes" # "off" for none
# Optionally set a reaction to show that archie has picked up a task.
# setting this to "off" disables the pickup reactions.
ack_reaction = "eyes"
# dispatch.labels maps each task lifecycle state to the label
# Archie applies on the issue.
# You can rename labels to match your project's conventions,
# or comment one out to skip that transition.
# The labels are the *source of truth* for the dispatch loop: Archie
# scans for issues bearing queued, then moves them through working →
# waiting → pr → parked (→ dead when max_retries is exhausted).
[dispatch.labels]
queued = "archie:queued"
working = "archie:working"
waiting = "archie:waiting"
pr = "archie:pr"
parked = "archie:parked"
# dead = "archie:dead" # state label for a task that exhausted max_retries
[models] # role -> ai-sdk runtime ref (used by agent workflows)
[models]
triage = "openai/gpt-5.4"
planner = "openai/gpt-5.4"
builder = "openai/gpt-5.4"
# `reviewer` runs the adversarial self-review stage and operator-triggered PR
# reviews. Omitted, it falls back to `builder`.
# reviewer = "openai/gpt-5.4"
# `embedding` is optional: it powers in-process embedding consumers
# (curators first). Unset, or a credential that fails to resolve, degrades
# to the capability reporting unavailable -- archied still starts.
# embedding = "openai/text-embedding-3-small"
[providers.openai]
class = "openai"
api_key = { engine = "bws", key = "OPENAI_API_KEY" }
# api_key_env = "OPENAI_API_KEY" # backwards-compatible environment form
[providers.ollama]
class = "ollama"
# [chat]
# `operator` is the display name of user. It is
# passed to the chat agent as runtime metadata, which means it is sent to the
# configured model provider on every turn -- leave it unset to tell the agent
# nothing about who is running it.
# operator = "John Smith"
# `workspace` roots the chat agent's file and shell tools (read, write, edit,
# shell, grep, find). If unser, the tools aren't registered.
# Set it to let the agent read, modify and execute inside that directory
# choose it deliberately
# workspace = "~/.local/share/archie/workspace"
# `max_steps` caps the model/tool round-trips in a single chat turn
# (default 100). This is a task budget, not a safety limit.
# max_steps = 100
# Let read/write/edit/find/grep tools reach absolute paths outside the
# workspace jail. Relative paths still resolve against workspace.
# The shell tool is never confined, so a jail only pushes the agent into
# using shell for everything, losing truncation, line numbering, and
# read-before-write protection. Enable when the agent needs to work
# cross-filesystem (disk ops, system edits, etc.). Grant deliberately.
# unrestricted_filesystem = true
# Render each completed tool call inline in the reply, naming the tool and one
# line of its result, before the answer built from them. Off by default: it is
# there to make a wrong tool choice visible from the chat, at the cost of
# narrating every internal step. Applies to every chat channel -- Telegram
# and the web dashboard both read this one setting.
# show_tool_calls = true
# Optional interactive-chat catalog. /provider groups these references by
# their first path segment, and /model shows only the selected provider's
# entries. When omitted, Archie uses the distinct refs in [models].
# models = [
# "openai/gpt-5.6-sol",
# "openrouter/openai/gpt-5.6-sol",
# ]
# Optional self-hosted update adapter. Both values are argv arrays (never
# shell snippets). The check command must write a releaseupdate.Snapshot JSON
# document to stdout; configure the installer as well to show Approve/Defer.
# [chat.telegram]
# Preferred: resolve the bot token through a configured secret engine.
# token = { engine = "bws", key = "TELEGRAM_BOT_TOKEN" }
# Legacy compatibility: read the token from this environment variable.
# token_env = "TELEGRAM_BOT_TOKEN" # env var holding the bot token from @BotFather
# Run by archie-messaging, which serves /update, so these commands execute on
# whichever host runs that process.
# update_check_command = ["/usr/local/bin/archie-update-check"]
# update_install_command = ["/usr/local/bin/archie-update-install"]
# Inbound email as a chat channel, via SMTP. Empty listen_addr disables it.
# [chat.email]
# listen_addr = "0.0.0.0:2525" # inbound SMTP server
# relay_addr = "smtp.example.com:587" # outbound relay for replies
# Generic inbound webhook gateway: external services push messages into
# chat for LLM processing. This is a distinct surface from
# [forge].webhook_addr (forge issue events) and [capture] (unbound event
# storage for later binding) -- three different inbound HTTP concerns that
# happen to share the word "webhook".
# webhook_addr = "0.0.0.0:8646" # under [chat], not [chat.telegram]
#
# [chat.webhook] configures the single route the gateway serves. Every
# field is optional; an absent section runs with the pre-existing
# behaviour: path "/webhook", no signature validation, raw body as message
# text, no reply.
# [chat.webhook]
# path = "/webhook"
# secret = { engine = "bws", key = "CHAT_WEBHOOK_SECRET" } # verifies
# # X-Hub-Signature-256 on inbound payloads. Empty (the default) accepts
# # any unsigned POST -- set this to make the gateway actually verify
# # what it claims to.
# template = "issue.title" # dot-notation extraction of the message text
# # from the JSON payload. Empty uses the raw body.
# deliver_to = "origin" # "origin" writes the reply as the HTTP
# # response; empty (the default) sends no reply.
# Per-(channel, sender) inbound rate limiting, shared by every chat channel:
# Telegram keys by numeric user ID, email by SMTP from address, webhook by
# its configured route path -- a source, not a person, so it reaches the
# limiter as a transport-only budget key rather than as an identity. Off by
# default -- both fields must be set to a positive value.
#
# This section is the seed for the Channel settings resource. The Web UI owns
# the value a running deployment limits with (restart-required), so edit it
# there rather than here; a stored value is not overwritten by this file.
# [chat.rate_limit]
# window = "1m"
# max_requests = 20
# External MCP tools are launched and managed by Archie's MCP client. A
# command of "npx" gets a persistent package cache under work_dir
# (top of this file) automatically, so a daemon restart reuses it instead
# of re-resolving and re-downloading the package from the npm registry
# every time. This does not cover a package's own separate downloads (e.g.
# a Playwright/Puppeteer-based server fetching a browser binary from a CDN
# via its postinstall script) -- consult that package's own env vars for
# those.
# Most MCP servers are single-threaded and get one tools/call at a time.
# parallel_tool_calls = true (default false) drops that serialization for
# this server only, for a server whose own implementation handles
# concurrent requests. It never affects another configured server.
# [[tools.mcp_servers]]
# name = "desktop-commander"
# transport = "stdio"
# command = "npx"
# args = ["-y", "@wonderwhy-er/desktop-commander@0.2.46", "--no-onboarding"]
# work_dir = "/path/to/workspace"
# parallel_tool_calls = false
# Publish artifacts (review reports, design docs) to the collaborative editor.
# An empty base_url disables publishing entirely. The token is runtime config:
# set WORKSPACE_INGEST_TOKEN in the daemon's environment or use a secret ref.
[artifacts]
# base_url = "https://offloaded.dev"
# token = { engine = "env", key = "WORKSPACE_INGEST_TOKEN" }
# token_env = "WORKSPACE_INGEST_TOKEN"
# archied's own liveness surface, always on. GET /healthz and /health answer
# 200 once the daemon is serving (503 while it is still booting), and
# /health/detailed reports the readiness probes. This is what the update
# watchdog polls after restarting archied to decide whether the release came
# up or has to be rolled back, so it stays separate from the dashboard's
# /healthz: the dashboard can be switched off, and it runs as its own process
# in the extracted UI topology.
[health]
listen = "127.0.0.1:8485"
# Bounds one readiness probe's call into a service the daemon depends on but
# does not own (the Gateway), so a hung dependency degrades that probe instead
# of stalling the whole report. Omit for the default; a negative value leaves
# only the caller's own deadline in force.
# dependency_timeout = "5s"
# Web dashboard and API: task board, activity stream, chat, config,
# memory, SSE events. Served as an embedded SPA with a full REST
# and streaming API. Auth is token-based for non-loopback addresses;
# loopback binds (127.0.0.1, ::1, localhost) skip auth automatically.
#
# From the UI cutover (archie-core-8cda.5.4) the dashboard is served by the
# standalone archie-ui process, not by archied: this listen address is what
# archie-ui binds, and archied runs no dashboard listener at all. Run
# `archie-ui -config <same config.toml>` alongside the other services.
[web]
listen = "127.0.0.1:8484"
# Trust X-Forwarded-Proto and X-Forwarded-Host headers when validating Origin
# on mutating requests (CSRF protection).
#
# Off by default. When false, the expected Origin scheme is derived directly
# from the daemon's own network connection (http unless TLS is terminated by
# archied directly). Setting this to true causes archied to respect the
# X-Forwarded-Proto header sent by a reverse proxy (e.g. Traefik, Caddy, Nginx).
#
# SECURITY WARNING: Enable ONLY when archied is deployed behind a trusted
# reverse proxy that strips or overwrites any client-supplied X-Forwarded-*
# headers. Enabling this on a directly exposed daemon allows untrusted
# clients to spoof the Origin scheme and bypass CSRF protection.
# trust_forwarded_headers = false
# Where archied writes its logs. Without file set, output goes only to
# stderr -- which under systemd means journald holds the sole copy, and
# running by hand leaves no record at all. Setting file gives a durable
# copy independent of the supervisor, and is what lets the dashboard show
# history from before it connected. Both stderr and the file get output
# unless quiet is set.
# [log]
# file = "~/.local/share/archie/logs/archied.log"
# max_size_mb = 20 # rotate once the file exceeds this; 0 uses the default (20)
# keep = 5 # rotated files to retain; 0 uses the default (5)
# level = "info" # "debug" | "info" | "warn" | "error"
# quiet = false # true suppresses stderr once a file is configured
# The built-in file-backed memory engine (internal/domain/memory +
# internal/infrastructure/memory) is always on -- nothing here is required
# to get memory at all. engine selects among the domain/memory engine
# family; "builtin" (the default, same as leaving it unset) is the only
# one implemented so far.
# [memory]
# engine = "builtin" # "builtin" is the only engine implemented so far
# Image generation capability (internal/domain/image). No provider is
# implemented yet -- this section defines the contract/config surface only
# (archie-core-1786748942147-2-47cd5bd1). Absent is valid and registers no
# provider. default names the provider /image uses without asking; leaving
# it unset means /image always asks which mechanism to use. Every provider
# is off by default -- a hosted provider spends real API credits per call,
# and a local one can saturate the host GPU, so both require an explicit
# enabled = true, never an inferred one from the presence of a key alone.
# [image.hosted.openai]
# enabled = false
# class = "openai"
# api_key_env = "OPENAI_API_KEY"
#
# [image.local.sdxl]
# enabled = false
# backend = "sdxl-turbo"
# Notifications for human-in-the-loop moments
# (approval requests, gate failures, parked tasks).
# Archie POSTs a JSON payload to the webhook
# wire it to n8n, email, Slack, or any HTTP endpoint.
[notify]
# webhook = "https://n8n.example.com/webhook/archie"
[budgets]
max_steps = 60
wall_clock = "30m"
wall_clock = "30m" # one agent call
gate_max_failures = 5
task_wall_clock = "4h" # a whole task run
[health]
listen = "127.0.0.1:8485"
# dependency_timeout = "5s"
# Trace export. Without an endpoint nothing is exported.
# [telemetry]
# endpoint = "127.0.0.1:4317" # OTLP/gRPC collector
# insecure = false # plaintext to the collector
# ca_file = "" # PEM bundle verifying the collector
# sample_ratio = 1.0 # share of new traces recorded
# headers = { authorization = "Bearer ..." }
[web]
listen = "127.0.0.1:8484" # "off" disables the dashboard
# trust_forwarded_headers = false # only behind a proxy you control
# Services selects contract adapters at composition time (see
# docs/prds/state-store-contract.md).
[services.gateway]
target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remote once set)
# listen = "127.0.0.1:8585" # The address archie-gateway BINDS. Read only by the
# # archie-gateway process; every client ignores it. Defaults
# # to the target above, so a default deployment's client and
# # server cannot drift onto different ports. Set it when the
# # host already owns that port.
# target_token = "..." # Bearer [REDACTED] for a NON-loopback listener. A loopback listener
# # (127.0.0.1/::1/localhost) needs no token. A non-loopback
# # listener without a token fails closed, as does a
# # non-loopback dial without one. The same token is
# # presented as GATEWAY_TOKEN by remote consumers.
target = "127.0.0.1:8585"
# listen = "127.0.0.1:8585"
[services.state]
target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address archied and
# # archie-gateway dial. They no longer own archie.db
# # in-process: the standalone archie-state-store process
# # owns the single SQLite file (docs/prds/state-store-contract.md
# # §10/§12 step 7). An empty target is a startup error.
# listen = "127.0.0.1:9090" # The address archie-state-store BINDS. Read only by that
# # process; every client ignores it. Defaults to the target
# # above, so a default deployment's client and server cannot
# # drift onto different ports. Move it when a port is already
# # taken on the host.
# target_token = "..." # bearer token for a NON-loopback target. A loopback target
# # (127.0.0.1/::1/localhost) needs no token. A non-loopback
# # target without a token fails closed (docs/prds/state-store-contract.md
# # §9). The same token is injected as STATE_STORE_TOKEN into
# # archie-agent containers so the agent authenticates to the
# # same remote store. See deployments/README.md for how to
# # start archie-state-store.
target = "127.0.0.1:9090"
# listen = "127.0.0.1:9090"
# [tls]
# ca_file = "/etc/archie/tls/ca.pem"
# cert_dir = "/etc/archie/tls"
# NATS is the sole autonomous workflow handoff. mode changes only where the
# broker runs; every workflow still runs in a managed task container:
# "embedded" – in-process nats-server (the default; no external server)
# "external" – connect to url
# Leave the section absent to run embedded.
# [nats]
# mode = "embedded" # "embedded" | "external"
# url = "nats://localhost:4222" # required when mode = "external"
# token_env = "NATS_TOKEN" # optional external-server credential; embedded generates one per start
# mode = "embedded" # or "external" with url
# url = "nats://localhost:4222"
# token_env = "NATS_TOKEN"
# Unbound webhook capture: POST /webhooks/capture/{source} accepts and
# stores any inbound payload archie doesn't yet have a binding for, so it can
# be inspected and mapped later (see docs/prds/event-capture-storage.md).
# Stored in the same SQLite database as tasks, not NATS -- capture has one
# writer and one (human, dashboard) reader, so it doesn't need JetStream's
# fan-out/replay machinery, and SQLite is available in every deployment
# shape unconditionally. All fields default when the section is absent;
# capture is on by default.
#
# From the UI cutover (archie-core-8cda.5.4) the receiver is mounted by the
# archie-ui process, which projects these same values from this file; the
# daemon's binding-dispatch loop consumes captures from the shared State
# Store. Leave this section here even if you do not edit it: both processes
# read it.
# [capture]
# retention = "168h" # 7 days; prune-on-write deletes anything older
# max_events = 5000 # row cap, pruned on every insert regardless of age
# max_body_bytes = 262144 # 256 KiB; larger POSTs are rejected with 413
# rate_per_second = 1.0 # per-remote-address token bucket
# rate_burst = 5
# [log]
# file = "~/.local/share/archie/logs/archied.log"
# level = "info"
# The cron/scheduling ticker engine: how often scheduled jobs are checked,
# how many may run at once, and how long one may run. The engine polls a job
# store for what is due and dispatches each due job to the delivery it names
# -- so nothing here schedules anything by itself, it only tunes the timing.
# Absent is valid: every field defaults independently, and a section naming
# only one of them still gets the defaults for the other two.
#
# Zero (or absent) takes the default named below. A NEGATIVE value is a
# startup error, not a clamp: running something other than what was written
# is how a misconfiguration stays invisible. Zero cannot mean "off" here for
# the same reason it cannot in [tools.tool_policy] -- it is indistinguishable
# from an unset key.
# [scheduling]
# interval = "60s" # tick cadence: how often due jobs are checked.
# # Absent/zero means 1m. The finest granularity a
# # cron-style schedule needs, and polling a local
# # job store that often costs nothing.
# max_parallel = 4 # caps simultaneous parallel-pool runs, so a store
# # reporting many jobs due at once (the first tick
# # after long downtime, typically) cannot launch an
# # unbounded fan-out. Absent/zero means 4. It does
# # not bound the sequential pool, which is one by
# # definition.
# job_timeout = "1h" # bounds one run. Absent/zero means 1h. A job that
# # has not finished in an hour is stuck, and leaving
# # it in flight would suppress every later run of the
# # same job forever.
# events_sink = "none" # "bus" publishes each run and failure on the event
# # stream, which is what the dashboard timeline reads;
# # "none" (the default, same as leaving it unset)
# # leaves the engine unobservable -- a scheduled run
# # has no task or chat turn behind it, so with no
# # sink nothing anywhere records that it fired.
# # Any other value is a startup error, so a typo
# # cannot silently turn observability off.
# Playbook-binding at-rest encryption: [bindings].encryption_key resolves a
# 32-byte high-entropy key through the secret registry (engine + key) and seals
# each binding's HMAC secret in the SQLite bindings.secret column with AES-256-
# GCM (see docs/prds/binding-secret-encryption.md). When the key is absent,
# binding secrets are stored as plaintext (the pre-t2db.7 behaviour) -- enabling
# encryption does not retroactively encrypt existing rows, which stay plaintext
# until they are edited. Rotation: after changing encryption_key, retain the
# previous material in previous_encryption_keys so rows sealed under the old
# key still decrypt, then drop it once no row references it. A reload that
# changes these keys requires a daemon restart.
# [bindings]
# encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }
# previous_encryption_keys = [ { engine = "env", key = "ARCHIE_BINDING_KEY_OLD" } ]
# encryption_key = { engine = "env", key = "ARCHIE_BINDING_KEY" }
# Docker sandbox execution of archie-agent is mandatory for autonomous
# workflows. Omit this section to use the default image, lifetimes, and pull
# policy; the options below show the available overrides. If Docker or
# the image is unavailable, chat and the dashboard still start while tasks
# park explicitly; archied never falls back to a host agent loop.
# [containers]
# image = "ghcr.io/samcharles93/archie-agent:latest"
# max_concurrency = 4 # optional cap; 0/absent means no global cap
# max_uptime = "60m" # container lifetime cap
# volume_ttl = "72h" # max age for persistent repo volumes and Git clone caches
# pull_policy = "missing" # "missing" or "always"
# Access records: how long a recorded access denial is kept before the State
# Store's sweep deletes it. Zero means 90 days.
# [access]
# denial_retention = "2160h"
# At least one [[repos]] entry is required before archied will poll
# anything -- it is deliberately left commented rather than shipped active:
# an active example here validates as a normal, working repo (owner/name are
# only checked for non-empty), so archied would silently start polling a
# repository that doesn't exist. archied setup does not write this section
# ([[repos]] is an array of tables, which the text-patching setup uses
# cannot target) -- add at least one entry by hand.
#
# [[repos]]
# owner = "your-github-username"
# name = "todo"
# base = "main"
# ecosystem = "go" # "go", "python", "node", "rust", or "custom"
# # Override the ecosystem defaults when needed:
# # preflight = [["go", "version"]]
# # test_glob = "*_test.go"
# protect = ["_templ.go"]
# gate = [
# ["templ", "generate", "./components/"],
# ["go", "vet", "./..."],
# ["go", "build", "./..."],
# ["golangci-lint", "run"],
# ["go", "test", "./...", "-count=1"],
# ]
# # allow_concurrent = true # let the daemon run multiple tasks for this repo at once instead of
# # FIFO-serializing them; only safe when concurrent worktrees won't collide
# # (e.g. different base branches or packages per task). Still bounded by
# # [containers].max_concurrency globally.
# # persistent_storage = true # reuse a per-repo Docker volume and Git object cache until volume_ttl
# # max_retries = 5 # per-repo override of the global max_retries above
# # review_enabled = true # run a fresh adversarial reviewer (no path to the implementer's
# # context) after gates pass and before the PR opens. Default false --
# # an uncalibrated reviewer that cries wolf is worse than no review.
# Where releases and the extension catalogue come from on a new instance: an
# OCI repository and the base64 ed25519 key it signs with. Blank is the
# official source. Once stored, change them in the dashboard settings.
# [distribution]
# releases = "registry.example/owner/archie"
# releases_key = "base64 public key"
# catalogue = "registry.example/owner/archipelago/catalogue"
# catalogue_key = "base64 public key"
# ── Tools ───────────────────────────────────────────────────────────────────
# Limits on what a tool may return. These bound how much of the context window
# one tool call can spend: the workspace file tools truncate themselves, but
# skill bodies and MCP server results otherwise arrive whole.
#
# Zero (or absent) takes the default. A NEGATIVE value disables the limit --
# zero cannot mean "off" because it is indistinguishable from an unset key.
# [tools.tool_policy]
# max_result_chars = 50000 # cap on one tool result; -1 for no cap
# spill_dir = "" # unset by default, which truncates oversized results
# # inline. When set, a result over the cap is written
# # here in full and the model is handed the path.
# # It MUST be inside chat.workspace: the read tool
# # refuses paths outside it, so a spill anywhere else
# # is a reference the model cannot open -- worse than
# # truncating. Startup warns if it is outside.
# # Task agents work in their own worktree and cannot
# # read it at all; they always truncate.
# The web_fetch tool: retrieve a URL and return readable text.
# [tools.web_fetch]
# enabled = true # set false to withdraw the tool entirely
# timeout = "30s"
# max_bytes = 2000000
# allow_private_networks = false
# # Off by default, and worth leaving off. archied's own dashboard, NATS and
# # the Docker API answer on loopback and private addresses, and the URL to
# # fetch arrives through chat -- an untrusted path, since a forge issue body
# # or an inbound email can be quoted into a turn. The address is checked at
# # dial time rather than on the URL string, so a public name that resolves to
# # a private address is refused too. Turn this on only for a homelab endpoint
# # you intend Archie to reach.
# The generate_video tool: text-to-video via MiniMax's API. Off by default,
# unlike web_fetch -- this spends real API credits per call, so it needs an
# explicit opt-in and a working key before it is registered at all.
# [tools.minimax]
# enabled = true
# api_key = { engine = "env", key = "MINIMAX_API_KEY" }
# base_url = "" # override the API host; leave unset in normal operation
# # Generation is synchronous from the model's point of view: the tool call
# # blocks until MiniMax reports the video ready or failed, which can take
# # several minutes. The result is a hosted URL delivered through whatever
# # channel supports gateway.MediaSender (Telegram today); channels without
# # that support get the URL as a plain link in the reply text instead.
# Long-running agent loops that maintain memory, skills and — in dry run —
# file follow-up issues from recent runs. Definitions are data: the server
# validates them and the gateway applies them live.
# [[curators]]
# name = "self-intake"
# interval = "1h"
# tools = ["run_list", "run_events", "issue_list"]
# instructions = """
# You are archie's self-intake curator, in dry run. Each pass: list recent
# task runs with run_list, inspect anything parked or failed with run_events,
# check issue_list for each repo so nothing already open is repeated, then
# report candidate follow-up issues, each tied to the run that produced it.
# Do not create issues.
# """
# To let it file: add "issue_create" to tools and tell it to file each
# candidate (citing the run) instead of only reporting it.
+2 -9
View File
@@ -1,12 +1,5 @@
// Package configtemplate embeds config.example.toml so archied setup can
// generate a first-run config.toml from the exact file operators already
// read as documentation, instead of a second copy that can drift from it.
//
// It lives at the module root, rather than under internal/, because embed
// patterns cannot reach outside the directory of the .go file that declares
// them, and config.example.toml is kept at the root where it is easy to
// find and hand-edit. (Written without the directive prefix on purpose:
// staticcheck reads "// go:embed" in prose as a malformed directive.)
// Package configtemplate embeds config.example.toml for archied setup. It
// sits at the module root because embed cannot reach parent directories.
package configtemplate
import _ "embed"
-320
View File
@@ -1,320 +0,0 @@
package configtemplate
import (
"os"
"path/filepath"
"sort"
"strings"
"testing"
)
func TestDeployWorkflowOnlyPublishesRuntimeImageForTaggedRelease(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
// The fallback remains necessary because Dockerfile.archied accepts a
// runtime version, but it must not be used as the image-publish selector.
for _, required := range []string{
`RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"`,
`RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"`,
`echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"`,
`echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"`,
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing runtime-image guard %q", required)
}
}
// The gateway build remains unconditional, while the runtime build is
// guarded. Both selectors are required. A one-stream release creates only a
// `v*` tag -- release.sh has no archie/v* arm any more -- so a
// runtime_tag-only condition would mean the agent image is never rebuilt
// again, and `docker compose pull agent` would fetch an ancient image
// forever. The legacy archie/v* arm stays because history is not re-tagged.
agentMarker := " - name: Build and push archie-agent\n"
agentStart := strings.Index(source, agentMarker)
if agentStart < 0 {
t.Fatal("deploy workflow has no archie-agent build step")
}
agentIf := " if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''\n"
if !strings.Contains(source[agentStart:], agentMarker+agentIf) {
t.Fatal("archie-agent build step is not conditionally enabled")
}
gatewayMarker := " - name: Build and push archied\n"
gatewayStart := strings.Index(source, gatewayMarker)
if gatewayStart < 0 {
t.Fatal("deploy workflow has no archied build step")
}
if strings.Contains(source[gatewayStart:agentStart], "\n if:") {
t.Fatal("archied build step is unexpectedly conditional")
}
}
func TestDeployWorkflowUsesConfiguredFormatters(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
for _, required := range []string{
"github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2",
"golangci-lint fmt",
"git diff --exit-code",
"golangci-lint run ./...",
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing formatter gate %q", required)
}
}
if strings.Contains(source, "gofumpt -w .") {
t.Error("deploy workflow bypasses the configured formatter set")
}
}
func TestPullRequestsRunTheDefinitiveGateWithoutPublishAccess(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/quality.yml")
for _, required := range []string{
"pull_request:",
"contents: read",
"task check",
"git diff --exit-code",
} {
if !strings.Contains(source, required) {
t.Errorf("quality workflow is missing %q", required)
}
}
for _, forbidden := range []string{
"packages: write",
"docker/login-action",
"docker/build-push-action",
} {
if strings.Contains(source, forbidden) {
t.Errorf("quality workflow has publishing capability %q", forbidden)
}
}
}
// unpackagedCommands are commands that deliberately never ship as a host binary.
// Naming each one with its reason keeps an omission a decision rather than an
// oversight -- which is exactly how archied's channels were lost.
var unpackagedCommands = map[string]string{
"archie-agent": "runs only inside the Docker image build-and-push publishes, never as a host binary",
}
// cliOnlyCommands ship in the zip but must never be restarted by the updater:
// they are not services.
var cliOnlyCommands = map[string]bool{"archie-playbooks": true}
// TestDistZipShipsEveryHostCommand is why archie-core-1c01 went unnoticed for
// two days. The v1.30.0 extraction moved Telegram, email and webhook out of
// archied into a new cmd/archie-messaging that nothing packaged: the release zip
// omitted it, scripts/archie-update-install omitted it from both of its lists,
// and install.sh's build loop omitted it too, so a host install ran on with a
// dead Telegram bot and no error logged anywhere. The daemon looked healthy
// throughout.
//
// The host component set was enumerated independently in four places (the zip's
// build loop, the zip's copy list, install.sh's build loop, and the updater's
// two lists), so two coordinated edits would have drifted again. Every list is
// pinned to cmd/ here instead: adding a command fails this test until it is
// packaged, and extracting one fails it until the previous command is removed.
// The updater's service list is separately required to have a documented unit,
// and its runtime guard refuses a host unit the list omits.
func TestDistZipShipsEveryHostCommand(t *testing.T) {
workflow := readDeploymentFile(t, ".github/workflows/deploy.yml")
installer := readDeploymentFile(t, filepath.Join("scripts", "archie-update-install"))
installSh := readDeploymentFile(t, "install.sh")
want := hostRunCommands(t)
wantBinaries := want
wantServices := withoutCLIOnly(want)
built := wordsAfter(t, workflow, "for cmd in ", "; do", nil)
// The marker consumes the prefix of the first word only, so restore it for
// whichever word the marker ended inside.
var shipped []string
for _, word := range wordsAfter(t, workflow, "cp dist/", ` "$name/"`, nil) {
if !strings.HasPrefix(word, "dist/") {
word = "dist/" + word
}
shipped = append(shipped, strings.TrimPrefix(word, "dist/"))
}
services := wordsAfter(t, installer, `GATEWAY_SERVICES="`, `"`, nil)
binaries := wordsAfter(t, installer, `GATEWAY_BINARIES="`, `"`, map[string][]string{"$GATEWAY_SERVICES": services})
installBuilt := installBuildCommands(t, installSh)
for _, list := range []struct {
name string
got []string
want []string
}{
{"deploy.yml dist-zip build loop", built, wantBinaries},
{"deploy.yml dist-zip copy list", shipped, wantBinaries},
{"install.sh build loop", installBuilt, wantBinaries},
{"archie-update-install GATEWAY_BINARIES", binaries, wantBinaries},
{"archie-update-install GATEWAY_SERVICES", services, wantServices},
} {
if diff := setDifference(list.want, list.got); diff != "" {
t.Errorf("%s does not match the host-run commands in cmd/: %s", list.name, diff)
}
}
// The installer now REFUSES an update when a service unit is missing and
// tells the operator to create it from this runbook, so a service the
// runbook never shows is a dead end rather than a documentation gap.
// Stamping is its own list, and a third build site made it three: the zip,
// install.sh and the updater each build the host binaries. A binary that
// cannot say what it is cannot be compared (archie-core-k94o), so a seventh
// command added unstamped fails here rather than waiting to be noticed.
for name, source := range map[string]string{
"deploy.yml": workflow,
"install.sh": installSh,
"archie-update-install": installer,
} {
if !strings.Contains(source, "internal/buildinfo.Version=") {
t.Errorf("%s does not stamp internal/buildinfo.Version", name)
}
}
for _, command := range wantBinaries {
// archied's flag lives in the app package it delegates to, not its thin
// cmd main; the rest report through buildinfo in their own main.
source := filepath.Join("cmd", command, "main.go")
if command == "archied" {
source = filepath.Join("internal", "app", "archied", "main.go")
}
main := readDeploymentFile(t, source)
if !strings.Contains(main, "buildinfo") && !strings.Contains(main, "-version") && !strings.Contains(main, "\"version\"") {
t.Errorf("%s has no way to report its version", source)
}
}
// The installer writes the units, so the runbook no longer carries their
// contents; it must still name each unit, or an operator cannot find one to
// inspect or override.
runbook := readDeploymentFile(t, filepath.Join("deployments", "systemd-user-service.md"))
var undocumented []string
for _, service := range wantServices {
if !strings.Contains(runbook, service+".service") {
undocumented = append(undocumented, service)
}
}
if len(undocumented) > 0 {
t.Errorf("deployments/systemd-user-service.md names no unit for: %s", strings.Join(undocumented, " "))
}
}
// installBuildCommands reads install.sh's build loop. The file has a second
// `for cmd in` (the git/go preflight), so the loop is located by the go build it
// drives rather than by the first marker -- and read from the real list, so a
// missing command is named instead of the marker merely going absent.
func installBuildCommands(t *testing.T, source string) []string {
t.Helper()
before, _, ok := strings.Cut(source, `go build -ldflags "${LDFLAGS}"`)
if !ok {
t.Fatal("install.sh has no go build loop to read")
}
prefix := before
start := strings.LastIndex(prefix, "for cmd in ")
if start < 0 {
t.Fatal("install.sh build loop has no for cmd list")
}
rest := prefix[start+len("for cmd in "):]
before0, _, ok0 := strings.Cut(rest, "; do")
if !ok0 {
t.Fatal("install.sh build loop is unterminated")
}
return strings.Fields(before0)
}
// hostRunCommands is every command under cmd/, minus the deliberately
// unpackaged ones. Deriving it is the point: a list written out here would drift
// from cmd/ exactly as the packaged lists did.
func hostRunCommands(t *testing.T) []string {
t.Helper()
entries, err := os.ReadDir("cmd")
if err != nil {
t.Fatalf("read cmd/: %v", err)
}
var commands []string
for _, entry := range entries {
if !entry.IsDir() {
continue
}
if _, skip := unpackagedCommands[entry.Name()]; skip {
continue
}
commands = append(commands, entry.Name())
}
if len(commands) == 0 {
t.Fatal("cmd/ holds no commands: this guard would assert nothing")
}
sort.Strings(commands)
return commands
}
func withoutCLIOnly(commands []string) []string {
out := make([]string, 0, len(commands))
for _, command := range commands {
if cliOnlyCommands[command] {
continue
}
out = append(out, command)
}
return out
}
// wordsAfter returns the whitespace-separated words between two markers on the
// same line. expand maps a word to the words it stands for, which is how the
// installer's "$GATEWAY_SERVICES" reference is followed to what it names.
func wordsAfter(t *testing.T, source, marker, terminator string, expand map[string][]string) []string {
t.Helper()
start := strings.Index(source, marker)
if start < 0 {
t.Fatalf("no %q in the file under test", marker)
}
rest := source[start+len(marker):]
end := strings.Index(rest, terminator)
if end < 0 {
t.Fatalf("no %q after %q", terminator, marker)
}
var words []string
for word := range strings.FieldsSeq(rest[:end]) {
if replacement, ok := expand[word]; ok {
words = append(words, replacement...)
continue
}
words = append(words, word)
}
return words
}
// setDifference names what is missing from and extra in got, so a failure says
// which side moved rather than that two lists differ.
func setDifference(want, got []string) string {
present := make(map[string]bool, len(got))
for _, item := range got {
present[item] = true
}
var missing []string
for _, item := range want {
if !present[item] {
missing = append(missing, item)
}
}
expected := make(map[string]bool, len(want))
for _, item := range want {
expected[item] = true
}
var extra []string
for _, item := range got {
if !expected[item] {
extra = append(extra, item)
}
}
sort.Strings(missing)
sort.Strings(extra)
var problems []string
if len(missing) > 0 {
problems = append(problems, "missing "+strings.Join(missing, " "))
}
if len(extra) > 0 {
problems = append(problems, "unexpected "+strings.Join(extra, " "))
}
return strings.Join(problems, "; ")
}
-269
View File
@@ -1,269 +0,0 @@
package configtemplate
import (
"os"
"regexp"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
func readDeploymentFile(t *testing.T, path string) string {
t.Helper()
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
return string(data)
}
func TestExternalNATSProfileLoadsWithManagedWorkers(t *testing.T) {
doc, err := configuration.New(nil).File("deployments/docker-nats-stack.toml")
if err != nil {
t.Fatalf("load external NATS deployment: %v", err)
}
if doc.Config.NATS.Mode != config.NATSModeExternal {
t.Errorf("NATS mode = %q, want %q", doc.Config.NATS.Mode, config.NATSModeExternal)
}
if doc.Config.Containers.Image == "" {
t.Error("managed worker image is empty")
}
legacy := doc.Config.LegacyAgent
if legacy.Mode != "" || legacy.Command != "" || len(legacy.Env) != 0 {
t.Errorf("legacy agent selector decoded from supported profile: %#v", doc.Config.LegacyAgent)
}
}
func TestInstallerUsesNativeDaemonAndManagedWorkerImage(t *testing.T) {
source := readDeploymentFile(t, "install.sh")
for _, forbidden := range []string{
"[agent]",
`go build -o "${ARCHIE_BIN_DIR}/archie-agent"`,
`- archie-agent`,
"required only for NATS container mode",
} {
if strings.Contains(source, forbidden) {
t.Errorf("install.sh contains removed deployment behavior %q", forbidden)
}
}
for _, required := range []string{
`ExecStart=${ARCHIE_BIN_DIR}/archied`,
"Docker is required for autonomous workflows",
} {
if !strings.Contains(source, required) {
t.Errorf("install.sh is missing deployment contract %q", required)
}
}
}
func TestWorkerImageIsNotDocumentedAsAStandaloneExecutor(t *testing.T) {
source := readDeploymentFile(t, "Dockerfile")
if strings.Contains(source, "docker run -e NATS_URL") {
t.Error("Dockerfile documents an unsupported manually started worker")
}
if !strings.Contains(source, "launched only by archied") {
t.Error("Dockerfile does not state that archied owns worker lifecycle")
}
}
func TestFormattingUsesOneConfiguredWriter(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
fmtStart := strings.Index(taskfile, " fmt:\n")
fmtEnd := strings.Index(taskfile, " proto:install:\n")
if fmtStart < 0 || fmtEnd < fmtStart {
t.Fatal("Taskfile has no bounded fmt task")
}
fmtTask := taskfile[fmtStart:fmtEnd]
const (
applyFix = "go fix ./..."
verifyFix = "go fix -diff ./..."
)
fix := strings.Index(fmtTask, applyFix)
format := strings.Index(fmtTask, "golangci-lint fmt")
if fix < 0 || format < 0 || fix > format {
t.Error("fmt task must run go fix before the configured golangci-lint formatters")
}
if strings.Contains(fmtTask, "gofumpt -") {
t.Error("fmt task bypasses the configured formatter set with standalone gofumpt")
}
// One go fix pass is not a fixpoint: stditerators rewrites
// `for i := range t.NumField()` into a field iterator that copies its loop
// variable, and forvar only deletes that copy on the following pass. A tree
// that stops after one pass is therefore one copyloopvar rejects, so fmt has
// to keep applying passes and prove the plateau with a dry run that exits
// clean only when nothing is left to fix.
if !strings.Contains(fmtTask, verifyFix) {
t.Error("fmt task does not prove that repeated go fix passes have reached a fixpoint")
}
if got := strings.Count(fmtTask, applyFix); got != 1 {
t.Errorf("fmt task applies go fix %d times inline, want 1: the repetition belongs to the fixpoint loop", got)
}
if got := strings.Count(fmtTask, verifyFix); got != 1 {
t.Errorf("fmt task verifies the go fix fixpoint %d times, want 1", got)
}
if got, owned := strings.Count(taskfile, applyFix), strings.Count(fmtTask, applyFix); got != owned {
t.Errorf("Taskfile invokes go fix %d times, %d of them through task fmt: formatting has one owner", got, owned)
}
}
func TestBuildTaskSourcesTrackEmbeddedAssets(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
start := strings.Index(taskfile, "\n build:\n")
end := strings.Index(taskfile, "\n test:\n")
if start < 0 || end < start {
t.Fatal("Taskfile has no bounded build task")
}
build := taskfile[start:end]
sourcesAt := strings.Index(build, "sources:")
generatesAt := strings.Index(build, "generates:")
if sourcesAt < 0 || generatesAt < sourcesAt {
t.Fatal("build task has no bounded sources block")
}
sources := build[sourcesAt:generatesAt]
for _, tc := range []struct {
name string
path string
reason string
}{
{
name: "embedded dashboard",
path: "ui/dist/**",
reason: "ui/embed.go embeds it with //go:embed all:dist, so a dashboard changing with no .go file changing must still rebuild the binaries",
},
} {
if !strings.Contains(sources, tc.path) {
t.Errorf("build sources do not track %s: %s", tc.name, tc.reason)
}
}
}
func TestBuildTaskStampsInstallTypeOnEveryCommand(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
start := strings.Index(taskfile, "\n build:\n")
end := strings.Index(taskfile, "\n test:\n")
if start < 0 || end < start {
t.Fatal("Taskfile has no bounded build task")
}
build := taskfile[start:end]
cmdsAt := strings.Index(build, "\n cmds:\n")
if cmdsAt < 0 {
t.Fatal("build task has no cmds block")
}
cmds := build[cmdsAt:]
buildLine := regexp.MustCompile(`^ - go build .*\./cmd/([a-z0-9-]+)`)
found := 0
for line := range strings.SplitSeq(cmds, "\n") {
m := buildLine.FindStringSubmatch(line)
if m == nil {
continue
}
found++
if !strings.Contains(line, "internal/installtype.buildType=") {
t.Errorf("build task does not stamp installtype.buildType on %s: %s", m[1], strings.TrimSpace(line))
}
}
if found == 0 {
t.Fatal("build task has no go build commands under ./cmd/: this guard would assert nothing")
}
}
func TestFormattersExcludeInterpretedSecretEngines(t *testing.T) {
config := readDeploymentFile(t, ".golangci.yml")
if !strings.Contains(config, `^examples/secret-engines/(age|sops|vault)\.go$`) {
t.Fatal("formatter config does not protect the interpreted secret engines")
}
}
func TestSupportedProfilesUseOneExecutionTopology(t *testing.T) {
profiles := []string{
"deployments/single-forge-github.toml",
"deployments/multi-forge-github-gitea.toml",
"deployments/local-ollama-standalone.toml",
"deployments/docker-nats-stack.toml",
}
for _, path := range profiles {
source := readDeploymentFile(t, path)
if strings.Contains(source, "\n[agent]\n") {
t.Errorf("%s still selects a legacy agent executor", path)
}
}
for _, path := range profiles[:2] {
source := readDeploymentFile(t, path)
for _, required := range []string{`mode = "embedded"`, "[containers]"} {
if !strings.Contains(source, required) {
t.Errorf("%s is missing default topology marker %q", path, required)
}
}
}
external := readDeploymentFile(t, "deployments/docker-nats-stack.toml")
if !strings.Contains(external, `mode = "external"`) {
t.Error("docker-nats-stack.toml does not explicitly select external NATS")
}
systemd := readDeploymentFile(t, "deployments/systemd-user-service.md")
if !strings.Contains(systemd, "Embedded NATS is the default") {
t.Error("systemd runbook does not identify embedded NATS as the default")
}
if strings.Contains(systemd, "still needs NATS") {
t.Error("systemd runbook still requires an external Compose NATS service")
}
}
// TestInstallerDelegatesConfigGenerationToArchiedSetup pins the contract the
// installer already drifted from once: it hand-rolled a config.toml, hardcoded
// the GitHub token key and the Gitea host, and choosing Gitea then produced a
// config naming a token it never wrote. The durable fix is that the code writing
// the config is the code reading it -- archied setup renders it, archied loads it
// (docs/architecture/configuration.md) -- and nothing stopped the generating
// branch growing back until this.
func TestInstallerDelegatesConfigGenerationToArchiedSetup(t *testing.T) {
source := readDeploymentFile(t, "install.sh")
for _, required := range []string{
// It runs the binary it just built, so the installer cannot hold a
// second idea of what a valid config looks like.
`"${ARCHIE_BIN_DIR}/archied" setup`,
// For a fresh install only: an existing config is the operator's.
`if [ ! -f "${ARCHIE_CONFIG_DIR}/config.toml" ]; then`,
"already exists (preserving user config)",
// The setup run is allowed to fail, and a failure is loud. A config that
// never gets written is the only honest outcome after that.
"could not generate",
} {
if !strings.Contains(source, required) {
t.Errorf("install.sh is missing %q", required)
}
}
// Nothing here renders TOML or splices it afterwards. The splice check is
// per line so a legitimate sed/awk elsewhere in the installer stays allowed.
if strings.Contains(source, "forge_block") {
t.Error("install.sh still carries the forge_block helper: it is what hardcoded the GitHub token key and Gitea host")
}
redirection := regexp.MustCompile(`>>?\s*"?[^"'\s]*config\.toml`)
for index, line := range strings.Split(source, "\n") {
if !strings.Contains(line, "config.toml") {
continue
}
if strings.Contains(line, "sed ") || strings.Contains(line, "awk ") {
t.Errorf("install.sh:%d splices config.toml (%s)", index+1, strings.TrimSpace(line))
}
if redirection.MatchString(line) {
t.Errorf("install.sh:%d writes config.toml itself (%s)", index+1, strings.TrimSpace(line))
}
}
// A TOML table header in the installer is a template by definition. The
// systemd unit it also writes is INI, whose only sections are Unit/Service/
// Install, so those are no part of this list.
template := regexp.MustCompile(`(?m)^\s*\[(forge|models|providers|runners|containers|nats|web|budgets|notify|identit|chat)\]`)
if found := template.FindString(source); found != "" {
t.Errorf("install.sh carries a TOML template (%q): the installer must not hold its own idea of the config schema", strings.TrimSpace(found))
}
}
+89 -46
View File
@@ -1,41 +1,41 @@
# Running this distribution
This archive contains six linux/amd64 binaries:
This archive contains five linux/amd64 binaries:
- **`archied`** — the resident daemon: polls your forge for assigned issues
and dispatches them into sandboxed `archie-agent` containers. It serves no
dashboard: the web UI is `archie-ui`'s process (UI cutover,
`archie-core-8cda.5.4`).
- **`archie-ui`** — serves the operator dashboard and the webhook capture
receiver, dialing the Gateway and State Store gRPC contracts. Reads only
`[services.*]`, `[web]` and `[capture]` from the shared `config.toml`.
- **`archie-gateway`** — serves the chat (`ChatContract`) surface `archied`,
`archie-ui` and `archie-messaging` dial. Runs as its own process; `archied`
never embeds a gateway.
- **`archie-messaging`** — serves the Telegram, email and webhook channels,
dialing the Gateway for the chat contract and the State Store for the stored
channel settings. `archied` runs no gateway for those channels, so without
this process they are simply absent — and nothing logs an error
(`archie-core-1c01`), which is why it has a unit of its own in
`deployments/systemd-user-service.md`.
- **`archie-state-store`** — owns the single `archie.db` SQLite file behind
a gRPC contract. `archied` and `archie-gateway` are gRPC clients of it, not
owners of the database.
- **`archie-playbooks`** — standalone CLI to lint playbook binding YAML
before it reaches `archied`.
Each service owns its data and reaches the others only through their gRPC
contracts (or NATS, for task actions):
`archie-agent` (the per-task sandboxed runtime) is **not** in this archive —
it only ever runs inside the Docker container `archied` spawns per task, never
as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
| Service | Owns | Reaches |
|---|---|---|
| `archie-state-store` | tasks, events, control-plane settings, identities and access policies, installed packages (PostgreSQL) | nothing |
| `archie-gateway` | conversations (PostgreSQL, its own tables) and every model call: chat turns, curators, MCP tools and sampling | State Store; daemon over NATS for task actions |
| `archied` | dispatch: forge polling, the task queue, the embedded NATS broker, agent containers | State Store; Gateway |
| `archie-messaging` | the Telegram, email and webhook channel connections | Gateway; State Store for channel settings |
| `archie-ui` | the dashboard and the webhook capture receiver | Gateway; State Store |
`archied playbooks lint` checks playbook binding YAML before it reaches the
daemon, and `archied playbooks serve` is its language server for editors.
Without `archie-messaging` the channels are simply absent, so it needs a unit
of its own (`deployments/systemd-user-service.md`).
`archie-agent` (the per-task sandboxed runtime) has no unit of its own: it
ships beside `archied` because a Kit run mounts it from that directory. The
agent image is a separate thing, pulled for the containers `archied` spawns
per task: `[containers].image` defaults to
`git.catlow.cloud/sam/archie-agent:latest`, while this archive's `release.json`
pins the digest the release published. Set `[containers].registry_auth` when
that reference is on a registry that needs a login -- see
`deployments/systemd-user-service.md#6-pinning-the-archie-agent-image`.
## Quickstart
1. Pick a starting configuration. The full set of annotated templates lives
in this repository's `deployments/` directory on GitHub
(<https://github.com/samcharles93/archie-core/tree/main/deployments>) —
`single-forge-github.toml`, `multi-forge-github-gitea.toml`,
`local-ollama-standalone.toml`, and `docker-nats-stack.toml` cover the
common cases. Copy whichever fits to:
(<https://offloaded.dev>) —
`standalone.toml` (no forge, the simplest start),
`single-forge-github.toml` and `docker-nats-stack.toml` cover the common cases. Every one needs
PostgreSQL 18 at `database_url`. Copy whichever fits to:
```bash
mkdir -p ~/.config/archie
@@ -46,9 +46,10 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
providers) and place any secrets in `~/.config/archie/env` or referenced
`secret://` locations.
3. Start the five processes, in order (`archie-state-store` and
`archie-gateway` first — `archied`, `archie-ui` and `archie-messaging` dial
both at startup):
3. Start the five processes. Order does not matter: a service whose peer is
not up yet waits for it and reports it as degraded on its health surface
meanwhile. The Gateway waits for the daemon's NATS endpoint when the broker
is embedded.
```bash
./archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
@@ -58,30 +59,25 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
./archied -config ~/.config/archie/config.toml
```
Dashboard reachability comes from `[web].listen` (default
`127.0.0.1:8484`, which needs no dashboard token). For a non-loopback
bind pass `-listen` with `-token` or `-token-file` to mint and persist
one. `archie-ui` reads `GATEWAY_TOKEN` / `STATE_STORE_TOKEN` from its
process environment only — it has no secret registry, so when those
tokens live in a secret manager, whatever starts `archie-ui` must export
them into its environment (the `[services.*].target_token` values in
`config.toml` are the other supported source).
Open `[web].listen` (default `127.0.0.1:8484`) to configure the organisation,
workspace and first administrator account. Remote access requires an HTTPS
reverse proxy. Complete setup before exposing the dashboard publicly.
4. For a persistent, 24/7 deployment instead of a foreground run, follow the
systemd user-unit runbook:
<https://github.com/samcharles93/archie-core/blob/main/deployments/systemd-user-service.md>.
<https://offloaded.dev>.
## Verifying an install
`archie-playbooks lint -dir <playbooks-dir>` validates playbook binding YAML
`archied playbooks lint -dir <playbooks-dir>` validates playbook binding YAML
against the same schema `archied` loads at startup — run it against your
playbooks directory before pointing `archied` at it.
## Version
This archive's binaries are built from the `archied` release tag in its
filename; `archie-ui`, `archie-gateway`, `archie-state-store`,
`archie-messaging` and `archie-playbooks` ship at that same version rather than
filename; `archie-ui`, `archie-gateway`, `archie-state-store` and
`archie-messaging` ship at that same version rather than
being independently tagged (see `RELEASING.md` in the source repository for why
only `archied` and `archie-agent` are independently versioned).
@@ -89,5 +85,52 @@ only `archied` and `archie-agent` are independently versioned).
`archied` are services that must be running and addressable; `archie-messaging`
carries the Telegram, email and webhook channels since the v1.30.0 extraction, so
an install (or an upgrade across v1.30.0) needs its unit as well -- see
`deployments/systemd-user-service.md`. `archie-playbooks` is a CLI and runs on
demand.
`deployments/systemd-user-service.md`.
### Native self-update
Install on Settings → Status runs `archied update install -version X` against
the release source in the update settings. It fetches release `vX`, refuses it
unless the source's key signed its statement, and downloads the Linux/amd64 zip
only if it hashes to the digest that statement names. Every host binary in the
zip must report `X`. It then pulls the agent image the statement pins by digest, backs up the database to
`db.pre-update.dump` in the state directory, stages the new binaries beside the
live ones and hands the transaction to `archied update watchdog` in a process of
its own (a transient systemd user unit). Nothing that runs changes until the
watchdog takes over.
`archied update check` finds the newest GitHub release with a linux-amd64 zip on
the channel chosen under Settings → Status → Updates: stable, next (includes
prereleases) or a pinned version. From a shell it reads
`ARCHIE_UPDATE_RELEASE_CHANNEL` and `ARCHIE_UPDATE_PIN`, or `-channel` and `-pin`.
The notification destination remains separate from the release channel.
`release.json` supplies the service order and required config sections to both
first-install and self-update. A missing unit or config section produces an
ordered migration plan and refuses installation. Apply that plan before retrying.
Automatic topology edits are intentionally unsupported.
The watchdog stops the units in reverse `release.json` order, switches the
staged executables by rename, switches the control-plane image policy (only the
image field, with conflict detection), and restarts the units in order through
`systemctl --user`. archied must report the new version and stay healthy for
120 seconds. Otherwise the watchdog restores the previous binaries and image
policy. Data is not rolled back unless the new release migrated the database:
then the previous binaries cannot serve it, so the pre-update backup is restored
and the outcome report says that every write since the update began is gone.
Without a systemd user manager the watchdog switches binaries and image policy
but restarts nothing, and the install reports that the services need a manual
restart.
Transactions live in `${XDG_STATE_HOME:-~/.local/state}/archie/update`, outside
the binary directory: `transaction/journal.json`, `transaction/previous/`, and
`transaction/archied`, the frozen copy of the archied that wrote the journal. On
daemon boot, an interrupted transaction is
handed to that frozen watchdog with `-recover` before normal startup: a
transaction that never started is discarded, one that was switching or observing
is rolled back, and a decided one is finished. To recover manually, run
`transaction/archied update watchdog -recover -bin-dir ~/.local/bin` from that
state directory. A failed recovery keeps the journal for another attempt.
The database backup stays in the state directory after a committed update for
manual recovery with `archie-state-store restore`.
+36 -52
View File
@@ -4,19 +4,17 @@ This directory contains configuration templates and guides for different deploym
## Directory Structure
* **[`single-forge-github.toml`](./single-forge-github.toml)**:
- **[`single-forge-github.toml`](./single-forge-github.toml)**:
Standard single-forge deployment managing multiple GitHub repositories under a single bot account and GitHub token.
* **[`multi-forge-github-gitea.toml`](./multi-forge-github-gitea.toml)**:
Multi-identity deployment running GitHub and a self-hosted Gitea instance simultaneously with distinct bot accounts, tokens, and repository sets.
- **[`standalone.toml`](./standalone.toml)**: start here. Event-driven
automation with no forge or repositories, local Ollama models, loopback
services and no tokens.
* **[`local-ollama-standalone.toml`](./local-ollama-standalone.toml)**:
Self-hosted deployment running local LLM models via Ollama (e.g., `llama3`, `qwen2.5`) with optional standalone (forge-disabled) operation.
* **[`docker-nats-stack.toml`](./docker-nats-stack.toml)**:
- **[`docker-nats-stack.toml`](./docker-nats-stack.toml)**:
Host-run `archied` orchestrating sandboxed `archie-agent` containers over the repository's Compose-managed NATS service. Copy to `~/.config/archie/config.toml`, start NATS with Compose, then start `archied` on the host.
* **[`systemd-user-service.md`](./systemd-user-service.md)**:
- **[`systemd-user-service.md`](./systemd-user-service.md)**:
Operational runbook for running `archied` as a persistent 24/7 background service via systemd user units and `loginctl enable-linger`.
---
@@ -42,25 +40,24 @@ archied -config ~/.config/archie/config.toml
systemctl --user start archied
```
The templates use the extracted Gateway Service by default. Start
`archie-gateway` before `archied`; it owns the conversation SQLite file and
serves the `ChatContract` gRPC API on the configured target.
Start order does not matter: a service waits for its peers and reports them as
degraded meanwhile. Every template needs PostgreSQL 18 at `database_url`;
`docker compose up -d postgres` provides the default one.
The State Store service (`archie-state-store`) owns the single `archie.db` task
SQLite file and serves the `StateStore` gRPC contract. After the in-process
store path was deleted, BOTH `archied` and `archie-gateway` dial it via
`[services.state].target` and never open `archie.db` themselves
(`docs/prds/state-store-contract.md` §12 step 7). The templates set
The State Store service (`archie-state-store`) owns the task data in the
PostgreSQL database `database_url` names and serves the `StateStore` gRPC
contract. BOTH `archied` and `archie-gateway` dial it via
`[services.state].target` and never open the task tables themselves. The templates set
`[services.state]` accordingly: a host-only agent reaches a loopback bind
(`127.0.0.1:9090`) with no token, while a container-mode agent needs the
Docker bridge gateway address plus a matching bearer token (`target_token` /
`--token` / `STATE_STORE_TOKEN`), because a container cannot reach the host's
loopback.
(`127.0.0.1:9090`), while a container-mode agent needs the Docker bridge
gateway address, because a container cannot reach the host's loopback. A
non-loopback address needs `[tls]` certificates from your own CA; see
`config.example.toml`.
## Running the dashboard
The dashboard is served by the standalone UI Service (`archie-ui`), not by
`archied` (UI cutover, `archie-core-8cda.5.4`; `docs/prds/ui-service-boundary.md`).
`archied`.
It reads the same `config.toml`, dials the Gateway and State Store targets
already configured there, and binds `[web].listen` (`127.0.0.1:8484` by
default). Start it after the Gateway and the State Store:
@@ -69,24 +66,29 @@ default). Start it after the Gateway and the State Store:
archie-ui -config ~/.config/archie/config.toml
```
A non-loopback `[web].listen` requires a dashboard token (`-token`, or
`-token-file` to mint and persist one); a loopback bind needs none.
Open the dashboard to configure the organisation, workspace and first administrator account.
Use HTTPS through a reverse proxy for remote access, and complete setup before exposing it publicly.
`archied` runs no dashboard listener at all, so webhook capture
(`POST /webhooks/capture/{source}`) is received by archie-ui and the
binding-dispatch loop in `archied` consumes what arrives from the shared
State Store.
Auth note: unlike `archied`, archie-ui has no secret registry --
`GATEWAY_TOKEN`/`STATE_STORE_TOKEN` resolve from its process environment
only (or from `[services.*].target_token` in `config.toml`), so whatever
starts archie-ui must export those tokens into its environment. See the UI
Service unit in `systemd-user-service.md` for the worked example.
The dashboard speaks plain HTTP. A non-loopback bind therefore carries the
session cookie and the provider token in clear over the network, and
archie-ui warns about exactly that at startup. Terminate TLS in front of it
(a reverse proxy or the tunnel itself) and set
`[web].trust_forwarded_headers = true` to declare the proxy and silence the
warning; leaving it off while exposing the port directly is the case the
warning names.
Auth note: archie-ui authenticates to its dependencies with its `[tls]`
certificate (`archie-ui.pem`).
```bash
# loopback (host-only agent)
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
# or container-mode: bind the bridge gateway with a token
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090 -token <token>
# or container-mode: bind the bridge gateway ([tls] required)
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090
```
## Verifying the daemon
@@ -117,28 +119,10 @@ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/healthz #
curl -s http://127.0.0.1:9091/health/detailed # state_db component -> 200, or 503 when degraded
```
A running State Store owns exactly one task SQLite file (`<db_path>-tasks.sqlite`);
`archied` and `archie-gateway` never open `archie.db` directly, so a second
store process on the same `db_path`, or a consumer that opens the task file,
indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/8).
A running State Store holds the `state-store` ownership lock on its database;
`archied` and `archie-gateway` never open the task tables directly, so a second
store process on the same `database_url` refuses to start, and a consumer that
opens the task tables indicates dual-store ownership.
The readiness probe is the single-writer check the runbook has against a
degraded store: a `503` from `/health/detailed` means `archied` should be
started only after the store is healthy.
### Inspecting the store
`-admin-addr` starts a read-only operator dashboard on the same process, over
the file it already owns:
```bash
archie-state-store -admin-addr 127.0.0.1:8686 # dashboard on http://127.0.0.1:8686/_/
```
It co-tenants on `<db_path>-tasks.sqlite` rather than opening a second
database, so it does not disturb the single-writer rule above: it runs inside
the process that holds the ownership claim, and every archie table is exposed
as a read-only view collection. The routes that could write past those views
(`POST /api/sql`, `/api/backups`) are refused, so the gRPC contract stays the
only writer and `archie-state-store backup` stays the only snapshot path.
Leave the flag off and no dashboard listener is started.
+33 -5
View File
@@ -1,13 +1,21 @@
# Development overlay for `task dev` and `task dev:dashboard`.
#
# Match Vite's API/event proxy without changing the installed configuration.
# After the UI cutover (archie-core-8cda.5.4) the dashboard on :8484 is the
# The dashboard on :8484 is the
# archie-ui process's listener, not archied's; this overlay is what both
# `go run ./cmd/archied -config-overlay deployments/dev.toml` and
# `go run ./cmd/archie-ui -config-overlay deployments/dev.toml` read. Only
# [web], [services.*] and [capture] land in archie-ui; the daemon ignores
# [web] entirely.
# `task dev` runs archie-state-store against this overlay, and the State Store
# fails closed without a PostgreSQL URL. This must reach the `postgres`
# service in docker-compose.yml, which `task dev` brings up first via
# dev:postgres -- keep the URL and that service in agreement.
bot_user = "archie-dev"
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[web]
listen = "127.0.0.1:8484"
@@ -17,14 +25,34 @@ listen = "127.0.0.1:8484"
# when a port is already taken on the host -- before the
# listen key existed the collision could only be worked around by hand-writing
# a matching target and passing -listen, and it read as a code fault.
# (docs/prds/state-store-contract.md §12 step 7).
#
# Task containers dial the target over the Docker bridge gateway, so the store
# listens on every interface and [tls] (issued by `task dev:tls`) is required.
[services.state]
target = "127.0.0.1:9091"
listen = "127.0.0.1:9091"
target = "172.17.0.1:9091"
listen = "0.0.0.0:9091"
[tls]
ca_file = "tmp/dev-tls/ca.pem"
cert_dir = "tmp/dev-tls"
# `task dev` runs archie-gateway via dev:gateway, which also passes no -listen:
# the listen below is what it binds. Stated explicitly so the value archie-ui
# dials is visible next to the State Store one.
[services.gateway]
target = "127.0.0.1:8585"
listen = "127.0.0.1:8585"
listen = "127.0.0.1:8585"
[services.daemon]
target = "127.0.0.1:8587"
listen = "127.0.0.1:8587"
# Dry-run self-intake curator (#1770): surveys recent runs and reports
# candidate follow-up issues as pass summaries; declares no issue-creating
# tool, so it cannot file. Needs a chat model configured to run at all.
[[curators]]
name = "self-intake"
interval = "1h"
tools = ["run_list", "run_events", "issue_list"]
instructions = """
You are archie's self-intake curator, in dry run. Each pass: list recent task runs with run_list, inspect anything parked or failed with run_events, check issue_list for each repo so nothing already open is repeated, then report candidate follow-up issues — concrete, each tied to the run that produced it. Do not create issues; this pass reports only (no issue-creating tool is declared, so it cannot). End your reply with the report.
"""
+21 -22
View File
@@ -13,22 +13,27 @@
poll_interval = "60s"
bot_user = "archie"
diff_cap_lines = 0
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (PostgreSQL 18, required).
# `docker compose up -d postgres` provides this local default; point it at
# your own Postgres 18 server otherwise.
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file; archied
# and archie-gateway dial it and never open archie.db themselves (§12 step 7).
# This deployment runs the agent in containers, so target is the Docker bridge
# gateway (172.17.0.1) the container can reach, with a matching target_token
# that archie-state-store validates. Host-only agent: use 127.0.0.1:9090 with
# no token.
# The State Store gRPC service owns the PostgreSQL task data; archied and
# archie-gateway dial it and never open those tables themselves.
# This deployment runs the agent in containers, so the target is the Docker
# bridge gateway (172.17.0.1) the container can reach. A non-loopback address
# needs [tls]; see config.example.toml.
[services.state]
target = "172.17.0.1:9090"
target_token = "change-me-state-store-token"
[tls]
ca_file = "/etc/archie/tls/ca.pem"
cert_dir = "/etc/archie/tls"
[forge]
type = "gitea"
@@ -42,13 +47,6 @@ key = "ARCHIE_GITEA_TOKEN"
trigger = "assignee"
ack_reaction = "eyes"
[dispatch.labels]
queued = "agent:queued"
working = "agent:working"
waiting = "agent:waiting"
pr = "agent:pr"
parked = "agent:parked"
# Stages run in sandboxed archie-agent containers over NATS. archied only
# orchestrates: the agent image carries the toolchain and makes the model
# calls, so gate commands resolve there, not in the native daemon.
@@ -63,19 +61,20 @@ url = "nats://172.19.0.1:4222"
network = "archie-core_default"
# Pin your own registry's tag/digest -- never deploy against a bare
# ":latest" reference, which can change under a running deployment with no
# warning. See deployments/systemd-user-service.md#pinning-the-archie-agent-image
# for the pinning convention this repo follows for its own GHCR image.
# warning. See deployments/systemd-user-service.md#6-pinning-the-archie-agent-image
# for the pinning convention this repo follows for its own agent image.
image = "git.example.com/you/archie-agent:v1.21.0" # or "@sha256:..." for a production digest pin
max_concurrency = 4
max_uptime = "60m"
# Must outlast the whole-task limit (default 4h), or the reaper ends a run the
# task budget would have parked.
max_uptime = "5h"
# "missing": pull only when the image is absent locally. "always" against a
# private registry answers 401 because the daemon sends no credentials, so
# refresh the agent by hand: docker compose pull agent
pull_policy = "missing"
[web]
# Bound by the archie-ui process (the host-run dashboard after the UI
# cutover, archie-core-8cda.5.4); it dials the [services.*] targets above --
# Bound by the archie-ui process; it dials the [services.*] targets above --
# the bridge-gateway State Store address works from the host too.
listen = "127.0.0.1:8484"
# Trust X-Forwarded-Proto when fronted by a reverse proxy (e.g. Traefik)
@@ -118,6 +117,6 @@ gate = [
# Every env var named here must be present in the environment of the host
# archied process, normally through its configured supervisor or launch shell.
[chat.telegram]
token_env = "TELEGRAM_BOT_TOKEN"
token = { engine = "env", key = "TELEGRAM_BOT_TOKEN" }
# Empty list denies everyone.
allowed_user_ids = []
-46
View File
@@ -1,46 +0,0 @@
# ==============================================================================
# Self-Hosted Ollama + Standalone Mode Deployment Example
#
# Runs local open-weights models via Ollama (e.g. llama3, qwen2.5) with forge
# polling disabled (standalone execution mode).
# ==============================================================================
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file; archied
# and archie-gateway dial it and never open archie.db themselves (§12 step 7).
# Host-only deployment: the agent runs on the host, so the loopback target
# 127.0.0.1:9090 needs no token. Start archie-state-store with the matching
# `-listen 127.0.0.1:9090`.
[services.state]
target = "127.0.0.1:9090"
# Standalone execution: Forge polling is disabled
[forge]
type = "none"
[models]
triage = "ollama/llama3:latest"
planner = "ollama/llama3:latest"
builder = "ollama/llama3:latest"
[providers.ollama]
class = "ollama"
# Optional chat workspace configuration
[chat]
operator = "Local Operator"
workspace = "~/.local/share/archie/workspace"
max_steps = 100
models = [
"ollama/llama3:latest",
"ollama/qwen2.5:7b"
]
[budgets]
max_steps = 60
wall_clock = "30m"
-100
View File
@@ -1,100 +0,0 @@
# ==============================================================================
# Multi-Forge (GitHub + Gitea) Deployment Example
#
# Runs GitHub and a self-hosted Gitea instance simultaneously.
# Each [[identities]] entry defines its own forge, token, and repository list.
# Each identity runs in an isolated background goroutine and worktree directory.
# ==============================================================================
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file; archied
# and archie-gateway dial it and never open archie.db themselves (§12 step 7).
# This deployment runs the agent in containers, so target is the Docker bridge
# gateway (172.17.0.1) the container can reach, with a matching target_token
# that archie-state-store validates. Host-only agent: use 127.0.0.1:9090 with
# no token.
[services.state]
target = "172.17.0.1:9090"
target_token = "change-me-state-store-token"
[models]
triage = "openai/gpt-4o"
planner = "openai/gpt-4o"
builder = "openai/gpt-4o"
[providers.openai]
class = "openai"
api_key_env = "OPENAI_API_KEY"
[nats]
mode = "embedded"
[containers]
# Pinned to a verified digest -- archie-agent has no published semver tag
# yet (CI only pushes :latest). See
# deployments/systemd-user-service.md#pinning-the-archie-agent-image.
image = "ghcr.io/samcharles93/archie-agent@sha256:870f1b1357979cfea23fccacb24166ebeb9ab321708ef2c2b218a763ed99b090"
pull_policy = "missing"
[budgets]
max_steps = 60
wall_clock = "30m"
# ------------------------------------------------------------------------------
# Identity 1: GitHub Bot
# ------------------------------------------------------------------------------
[[identities]]
name = "github-bot"
bot_user = "archie-github"
bot_email = "archie-github@users.noreply.github.com"
[identities.forge]
type = "github"
host = "https://github.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
[identities.dispatch]
trigger = "assignee"
ack_reaction = "eyes"
[[identities.repos]]
owner = "my-org"
name = "github-repo-one"
ecosystem = "go"
[[identities.repos]]
owner = "my-org"
name = "github-repo-two"
ecosystem = "node"
# ------------------------------------------------------------------------------
# Identity 2: Self-Hosted Gitea Bot
# ------------------------------------------------------------------------------
[[identities]]
name = "gitea-bot"
bot_user = "archie-gitea"
bot_email = "archie-gitea@example.com"
[identities.forge]
type = "gitea"
host = "https://gitea.example.com"
token = { engine = "env", key = "ARCHIE_GITEA_TOKEN" }
[identities.dispatch]
trigger = "label"
ack_reaction = "eyes"
[[identities.repos]]
owner = "internal-team"
name = "gitea-repo-alpha"
ecosystem = "go"
[[identities.repos]]
owner = "internal-team"
name = "gitea-repo-beta"
ecosystem = "python"
Loaded 100 of 2923 files, more files were not shown because too many files have changed in this diff. Show more