shell.go relied on exec.CommandContext's default cancellation, which
kills only the process it started. A shell's real work is a child of
that shell, so cancelling `go test ./...` reaped the shell and left the
test binary running, and `nohup x &` was never touched at all.
That made /stop a lie for the case it exists to cover: the turn
unwound, the user was told it stopped, and the command carried on.
Worse than expected, and caught by writing the test first: without a
process group the tool does not merely fail to kill the command, it
hangs. The backgrounded grandchild inherits stdout, so cmd.Wait blocks
until the shell timeout regardless of cancellation. Verified by
reverting the fix -- the new test fails on a 30s hang, not on the
survival assertion.
Run the command as its own process group, signal the group on
cancellation, and bound Wait with WaitDelay so an inherited pipe cannot
hold the turn open. setProcessGroup/signalProcessGroup were already
present in the lifted set, used by tau's agent.go but not its shell
tool; this extends them to the shell and clears the unused-code lint
that was flagging them.
Recorded as a mutation in shell.go's provenance header.
/stop could not reach a running turn, and the reason was worse than a
missing cancel. go-telegram/bot runs one update worker that calls
handlers synchronously (defaultWorkers = 1, never overridden), and the
chat turn ran on it. While a turn streamed -- or sat in a shell tool --
the worker was blocked and /stop sat unread in the update channel until
the turn it was meant to kill had already finished.
Add gateway.Turns: a per-session serial lane that turns are submitted to
and that the event loop never waits on. The worker is free again in
microseconds, so /stop is serviced immediately; ordering comes from the
lane being serial rather than from the loop being blocked.
- Bare /stop cancels the running turn and clears the backlog behind it,
with no approval step. Approval guards destructive commands, and
gating the brake behind a confirmation defeats it. /stop <name> keeps
the existing process-termination behaviour and its approval.
- Cancellation propagates through the turn context, so it reaches the
model stream and any tool underneath -- a shell command built with
exec.CommandContext dies with the turn.
- Queues are unbounded and never shed. A dropped message is a silent
failure that surfaces later as an agent that ignored something.
- Turns are recovered per-lane: the channel's panic middleware wraps the
event-loop goroutine, which no longer runs the turn.
Also raise the chat step budget. It was hardcoded at 8 -- roughly one
read, one grep and two edits -- so turns hit the cap and stopped
mid-task with no indication they had been cut off. It is now
chat.max_steps, defaulting to 100. Interruption is /stop's job.
The chat agent had two tools -- memory_edit and skill_activate -- so it
could not read a file, search a tree or run a command. ai-sdk's runtime
already drives a tool loop for it (MaxSteps 8, toolExecute wired as the
executor), so the loop was never the missing piece: the registry was empty
of anything useful.
Lifted from tau internal/agent/tools at commit f5289ea, per the recorded
copy-and-mutate strategy: every file carries a provenance header naming its
tau source path, the commit, and the mutations made, so refreshing from
upstream is a diff rather than archaeology.
internal/tools/builtin/ the lifted tools, ~3.1k lines
internal/tools/provider/builtin/ the adapter to tools.ToolEntry
Six tools: read, write, edit, shell, grep, find. Tau's own tests came with
them and pass unmodified, which is the evidence that the lift is faithful.
Deliberately not lifted:
- agent.go (1214 lines): subagent spawning, and the only real coupling in
the package -- 10 tau packages including chat, sessions, store and
registry. Nothing the chat agent needs to do work.
- skill.go: depends on tau's skills package; archie has internal/skill and
already exposes skill_activate.
- docs.go: serves tau's own embedded documentation via tau/docs.
Not lifting the coordinator either. It is tau's agent loop (6.4k lines over
ten packages) and archie already has one in the ai-sdk runtime; porting it
would leave two loops competing. Its cancellation and tool events are worth
having, but they are a few hundred lines built against the existing path
rather than six thousand lifted onto a second one.
The adapter bridges two shape differences: archie hands handlers decoded
arguments where tau's executor takes raw JSON, and tau reports tool-level
failure in Result.IsError rather than as an error -- surfaced as a real
error so the runtime and the guardrail engine both see it. Tools are
classified idempotent or mutating for guardrails and budgets; that is
categorisation, not a jail.
chat.workspace roots the tools and defaults to empty, which registers none
of them. They read, write and execute, so the directory has to be a
deliberate choice rather than whatever the daemon started in -- in the
container that is /.
Verified: go build, go vet, gofmt clean; full suite passes.
Three defects found from a real Telegram transcript.
1. The operator's name was compiled into the prompt.
internal/gateway/persona.go and prompt.go both hardcoded "Sam's" into the
default persona and the fallback prompt. The persona renders first into
every system prompt, so a personal name was sent to the model provider on
every turn, and any other deployment got an assistant that believed it
worked for someone else. There was nowhere to put it: Repo.Owner is a repo
owner and config.Config had no operator concept.
ChatConfig.Operator now carries it, rendered in the prompt's <env> block as
runtime metadata and omitted entirely when unset. config.example.toml
documents that setting it sends the name to the model provider.
2. /new claimed to clear history that it had not cleared.
The chat responder keyed history by channel id through a local sessionKey
helper, while the session commands operate on tracked session ids.
sessionTracker.resolve mints deterministic ids so the two agree -- until
/new, /branch or /resume assigns a generated id, after which they address
different histories permanently. /new reported "Conversation history has
been cleared" while the next turn still saw everything, and /undo,
/compress, /resume and /sessions acted on a namespace the conversation
never read.
gateway.Router.ResolveSessionKey already existed for this, and
session_commands.go:104 said outright that main.go should call it instead of
its inline helper. It never got wired. The responder now resolves through
the router and the dead helper is deleted so it cannot come back.
buildTelegramRouter constructs the router before the responder so the
dependency is visible rather than captured by reference.
3. Prompt rules for two behaviours the transcript showed.
The agent offered to accept shell access it has no tool to use, which is
both unhonourable and a request for the user's secrets. It also opened
mid-conversation replies with a greeting, and described its own manner
("no fluff") in stock phrasing. Added core rule 7 and three communication
rules covering greetings, self-description and register.
Note the memory claim in that transcript was NOT a fabrication: the
memory_edit tool's own description names MEMORY.md and USER.md, and tool
descriptions are part of the prompt.
Also added chat-turn logging (session id, channel, thread, history depth).
Chat turns were entirely unlogged, so a report of lost context had no
evidence to check: 76 log lines covered two days and none of them was a
conversation. A separate report of mid-conversation amnesia remains
undiagnosed -- single process, 43h uptime, compression untriggered at three
messages -- and this is what makes it diagnosable next time.
Regression tests: prompt renders/omits the operator and carries no personal
name; the responder resolves via ResolveSessionKey and defines no local
session key helper.
Verified: go build, go vet, gofmt clean; full suite passes.
dependencies-and-contracts.md rule 1 says domains must not import
internal/infrastructure. internal/daemon and internal/agentexec both did,
and for exactly the thing the doc carves out: "internal/eventbus is an
approved shared application contract ... it MUST remain broker-neutral."
The Publisher/Consumer/Requester interfaces existed but lived inside the
NATS package, so a caller could depend on the behaviour yet still had to
import the implementation to name it. They now live in internal/eventbus,
and nats.Client asserts against eventbus.Bus.
The larger violation was ownership of meaning. The doc says "message schemas
stay with their owning domains; the event bus transports messages, it does
not own their meaning." The bus exported TaskEnvelope and a PublishTask
method, so the transport knew what a unit of work was, and it exported the
archie.agent.* subject helpers, so it also owned the agent protocol.
- TaskEnvelope, its routing Kind, the label vocabulary and the task
subjects move to internal/domain/workintake, which encodes and decodes
its own bytes. This starts internal/domain/ per organisation.md.
- The agent request/response/system subjects move to internal/agentexec,
which defines what those messages mean.
- internal/workflow keeps only the kind-to-registry mapping; the label
table stays single and lives with the domain that reads forge issues.
- The bus now carries opaque payloads on plain-string subjects.
Consumers declare the smallest interface they need rather than taking the
whole Bus: daemon.TaskBus is publish-unique/fetch/request, agentexec.
RequestBus is publish-request/reply-inbox, and archie-agent's stageBus is
fetch/respond. None can reach what it does not use.
Two defects this surfaced:
- archie-agent declared its own JetStream stream with a second copy of the
name, subjects, retention, dedup window, MaxDeliver and TTLs that
nats.Connect already sets -- two definitions of one stream, free to
diverge. Config now takes Subjects and FilterSubject from composition,
which is what let the agent use the shared client and delete its
hand-rolled setup.
- Replying to a request needs core NATS, not the JetStream publish path:
a reply inbox is ephemeral and belongs to no stream, so a durable
publish to it fails. The old code hid this by using the raw connection.
The contract now distinguishes Respond from Publish. The agentexec
round-trip test caught it after I had made the same mistake in
archie-agent.
Also translated the SDK's ErrNoResponders into eventbus.ErrNoResponders, so
the daemon's taskrun retry no longer imports the NATS SDK to name a
transient condition. The SDK is now confined to the nats package, the *rpc
packages (themselves NATS infrastructure), and cmd/*.
The agentexec test fake previously hand-rolled a JetStream consumer; it now
drains the client's own consumer, which is both closer to production and
avoids conflicting consumers on a work-queue stream.
Verified: go build, go vet, gofmt clean; full test suite passes.
The gateway work added /whoami, /profile, /sessions, /resume and /agents as
executable commands; TestPublishedCommandsMatchExecutableCommandSurface
correctly caught that they were undiscoverable. Two workers touching a
coupled surface -- the test is the thing that noticed.
These five command handlers were dropped during parallel merges of the
Telegram workers; the Router fields they depend on (Identity, Models,
Sessions, Agents) were already in place.
/new, /reset, /topic, /retry, /undo, /title, /branch, /fork, /compress,
and /compact are executable via the gateway router but were missing
from gatewayCommandSpecs, making them undiscoverable in Telegram's
command menu and /help output.
internal/config both defined the types every package imports and performed
the file I/O to produce them. Importing a settings struct therefore pulled
in a TOML decoder and a YAML decoder, and the shared model owned discovery,
decoding, overlays, defaulting and validation all at once. See
docs/architecture/configuration.md, which requires loading to move out and
internal/config to be dissolved.
internal/config is now types only -- no os, no filepath, no toml. The new
package owns loading, one concern per file:
features.go the closed set of recognised feature files
discovery.go directory scan and classification
decode.go TOML/YAML decoding, format dispatch
defaults.go filling absent values, no errors
validate.go judging supplied values, no mutation
provenance.go which file contributed what
loader.go Loader wiring the above; File/Overlay/Dir
Beyond relocating, this fixes what the old code conflated:
- Defaulting and validation were interleaved. applyAgentDefaults and
applyDispatchDefaults returned validation errors; validateContainers and
validateSingleIdentity quietly mutated the config. There was no point at
which you could see what the operator actually supplied. They are now
separate passes: applyDefaults never fails, validate never writes.
- Errors were fmt.Errorf strings prefixed "config: ", so a caller could not
distinguish operator-fixable input from an unreadable file without
matching message text. Five sentinels now carry that distinction.
- dataHome() read XDG_DATA_HOME directly and discarded the error from
os.UserHomeDir, so defaulting could not be tested without the
environment. It is injectable on Loader and no longer swallows the error.
- Nothing recorded where a value came from. With overlays, feature files
and conf.d/ all able to set the same field, "which file set this?" was
answerable only by re-deriving precedence by hand. Provenance records it.
- Feature files were applied in map iteration order, making load order and
any resulting error arbitrary. Discovery now returns them sorted.
- loadMainConfig reported "no config.yaml or config.toml found in %s" with
an empty string: the directory was lost when it was extracted from
loadDirInto, so the error named no directory.
- Unreadable or malformed conf.d/ extras were skipped silently, which
presents as a setting the operator wrote simply not taking effect.
- Decode errors from the main config were returned bare, without naming
the file that failed to parse.
The 40 loader tests moved with the code and their assertions are unchanged,
so the defaulting and validation rewrite is behaviour-preserving.
Document.Config is the temporary seam: still internal/config.Config, named
as a field so the compromise is visible at each use site, with its deletion
condition recorded in doc.go. Building typed per-domain sections now, while
every consumer still reads config.Config, would mean two shapes kept in sync
by hand with no consumer for the new one; that belongs with the dissolution
work, not ahead of it.
No consumer outside cmd/archied changed.
Verified: go build, go vet, gofmt clean; go test ./internal/config/... and
./internal/infrastructure/configuration/... pass. Pre-existing gateway and
telegram failures are unchanged.
RegisterAll returned as soon as nc.Subscribe had queued each SUB frame on
the client. Delivery to the server is asynchronous, so a caller that
registered a responder and immediately issued a request could beat its own
subscription and get nats.ErrNoResponders from a responder that was, by
then, listening.
This made TestRunTaskExecutesBootstrapWorkflowEndToEnd flaky in CI: it
passed in isolation and failed under full-suite load, when the scheduler
was contended enough for the request to win the race.
Flushing after subscribing gives Register a real guarantee -- a nil error
now means the subjects are reachable. That applies to production startup
too, not just tests: archied registers storerpc, forgerpc and worktreerpc
the same way.
The duplicated rollback loop is now a single unsubscribeAll closure, which
also becomes the returned unsubscribe func.
Verified: three consecutive full-suite runs with no archie-agent failure,
plus five targeted runs of the rpc packages. Remaining gateway and
telegram failures are pre-existing and unrelated.
The event bus was inspecting forge issue labels ("bug", "feature",
"bootstrap") to pick a subject. That put a forge vocabulary inside
infrastructure and duplicated the label table already owned by
workflow.Route -- adding a label meant remembering both places, and
nothing would have caught it if you forgot.
The label table now lives once, in internal/workflow, which already owns
label semantics:
- workflow.Kind names the routing category, with labelKinds as the
single label vocabulary and kindWorkflows mapping kind to registry
entry. Route consumes the ordered kind list so a "bug,feature" task
still falls through to feasibility when no tdd workflow is
registered, exactly as the switch did.
- nats.TaskKind is a closed, validated set of subject tokens.
PublishTask rejects an unknown kind rather than silently delivering
it to the default queue; the zero kind means default, so messages
queued before this field decode unchanged.
- The daemon classifies at the publish site and sets TaskEnvelope.Kind.
Also fixes two defects this exposed:
- drainNATS never reached its SQLite fallback. Replacing the old
(nil, nil) no-message signal with ErrNoMessage in 492ca20 made that
case continue at the top of the loop, but no-message is precisely
when the fallback must run -- requeued tasks (waiting_human approval,
retry-parked) never go through a NATS publish, so nothing would ever
arrive to trigger them. go vet caught it as unreachable code.
- config.classifyFeatureFile silently overwrote duplicate feature
files, so config.gateway.yaml and conf.d/gateway.yaml together
applied one at random. Its own doc comment recorded the bug
("or "" on success/duplicate"). The known-feature list in the error
message is now derived from knownFeatureNames instead of being
spelled out a second time beside it.
A test also called t.Fatalf from a non-test goroutine, where it does not
stop the test.
Verified: go build, go vet, gofmt clean. Pre-existing gateway (18) and
telegram (1) failures are unchanged in count -- they are lost routing
wiring from the parallel telegram merges, tracked separately.
Relocating internal/nats as-is would have cemented its problems into the
approved layout, so this is a rewrite rather than a move.
What was wrong:
- Conn() *nats.Conn, PublishMsg(*nats.Msg) and Fetch() jetstream.Msg pushed
SDK types into all four consumers, so the broker was not replaceable --
the opposite of what dependencies-and-contracts.md requires.
- PublishTask took seven positional parameters, six of them strings, where a
transposed argument was a silent bug.
- Labels travelled as a comma-separated string and were re-split on every
publish.
- Fetch returned (nil, nil) for 'no message', which every caller had to
remember to special-case.
- The logger field was stored and never used.
- Stream name, consumer name and every timeout were hardcoded constants.
- Errors were inconsistently wrapped; several paths returned bare errors.
- Connect repeated nc.Close() on each failure branch.
What replaces it:
- One concern per file: config, errors, subjects, message, client,
publisher, consumer.
- Publisher/Consumer/Requester interfaces with compile-time assertions, so
callers depend on behaviour and can be faked without a broker.
- A Message wrapper keeps jetstream types behind the boundary; consumers no
longer import the NATS SDK at all.
- TaskEnvelope with []string labels and JSON methods preserving the
comma-separated wire form for already-queued messages.
- Sentinel errors (ErrNoMessage, ErrNotConnected, ErrNoReplyAddress,
ErrInvalidConfig) and %w wrapping with operation context throughout.
- Config with validation and defaults; a single deferred cleanup in Connect.
- CoreConn() as the one documented escape hatch, for the *rpc packages that
are themselves NATS infrastructure.
Consumers migrated: cmd/archied, cmd/archie-agent, internal/daemon,
internal/agentexec. Behaviour, subjects and wire format unchanged.
- bodyclose: add deferred resp.Body.Close() in storage_test.go Docker test handler
- contextcheck: thread context through email handleSMTP/processMessage; replace
context.Background() with context.WithoutCancel(ctx) in telegram, webhook, webui
shutdown paths and container pool cleanup; add ctx parameter to Pool.Release
- containedctx: replace ctx context.Context struct field with stopCh chan struct{}
in StdioTransport and SSETransport; thread lifecycle context through goroutine
chains instead of storing it in structs
- fatcontext: lift context deadline derivation out of PrefetchContext loop
Add gateway/runtime-owned commands that remain usable when LLM credits
are exhausted:
- /start — acknowledgement without consuming a reply
- /new [name] (alias: /reset) — create a fresh session
- /topic [off|help|<session-id>] — session switching for threaded chats
- /retry — remove last assistant message, replay last user turn
- /undo [N] — remove last N messages from history (default: 1)
- /title [name] — set or display session title
- /branch [name] (alias: /fork) — create child session with inherited history
- /compress [here N|focus topic|--preview|--dry-run] (alias: /compact)
Design:
- sessionTracker maps channel+thread to active session, auto-creating
implicit sessions with the legacy sessionKey format for backward
compatibility with existing persisted data
- /new and /branch create explicit UUID-backed sessions
- SessionStore extended with DeleteRecentMessages, MessageCount, and
SaveMessages for undo/retry/branch/compress operations
- SessionContext extended with Title, ParentSessionID, BranchName
- All commands report 'not configured' when session store isn't wired
Session resolution is wired into the LLM responder so /new, /branch,
and /topic switches affect subsequent chat turns.
Implement session-scoped goal/subgoal/steer/queue state management
with thread-safe access and prompt injection for standing goals.
Commands:
- /steer <text> — queue a message to inject after the next tool call
- /goal [text|draft|show|pause|resume|clear|status|wait|unwait]
- /subgoal [text|remove N|clear]
- /queue (aliases /q, /bg, /btw, /background) [text|remove N|clear]
Architecture:
- SessionState in internal/gateway holds per-session goals, subgoals,
steer queue, wait flag, and background queue
- Goals are injected into the system prompt via BuildGoalPrompt()
- Steer messages are consumed between agent tool-calling steps via a
MaxSteps=1 loop in the daemon's respond closure
- Commands route through the existing gateway.Router with not-configured
guards when State is nil
Closes: archie-core-alm.1
Extend /model command to support:
- /model [model] (direct switch)
- --provider <name> (provider switch)
- --global (persist scope, with ModelPersist callback)
- --session (explicit session scope, default)
- --refresh (show current active model)
Add /personality command:
- /personality lists available personalities with inline keyboard
- /personality <name> switches directly
- Callback handling for inline keyboard selection
Router changes:
- Add Personas field (wired to PersonaRegistry in main.go)
- Add ModelPersist callback for --global persistence
- Route /personality as a local command
- Extend handleModel to accept full rest text with flag parsing
Gateway-local commands that report from Archie-owned state:
- /whoami: reports the Archie identity the user is talking to
- /profile: shows active Archie profile (identity, provider, model, available models)
- /sessions: lists recent sessions with last-active timestamps
- /resume [id]: resumes a session by ID or prefix match
- /agents: lists active agents and running/waiting tasks
Adds SessionLister and AgentReader interfaces to Router, wired from the
daemon composition root. SessionStore already satisfies SessionLister.
AgentReader is a thin adapter over store.Task list filtered to active
states (running, waiting_human, parked).
All commands are published in Telegram's menu and /help, and respond
with 'not configured' when their backing interface is nil.
Closes archie-core-alm.2
Hide /approve from Telegram's command menu, help text, and discoverability.
Telegraph users can no longer learn about task approvals through the bot.
/approve remains executable in the gateway router for email and webhook
channels; non-Telegram workflow callers are unaffected. Daemon polling of
forged waiting_human tasks and the Requeue(→implement) handoff are untouched.
Auto-fix lint issues and reformat imports across all files.
gci: group imports per project convention
gofumpt: format unused imports with blank lines
gofix: Go standard fixes
goimports: organize imports
Remaining 54 issues require manual judgment (not auto-fixable).
- Remove unnecessary string() conversion on res.Status in workflow/agent.go
(Status is already string in agentexec.Result)
- Fix TestRunWrapsExternalCommand: sh -c only reads the first argument as
the command string. exec.CommandContext("sh", "-c", "echo wrapped")
passes the intent correctly, while the previous split form
(", "", "echo", "wrapped"") treated "wrapped" as /bin/bash.
Move 5 skills (2093 lines) to /work/apps/archie-skills-parked: they
commissioned architecture campaigns, decision ledgers, evidence packets
and acceptance gates on every agent that opened the repo. Twelve factual
skills remain (6376 -> 4283 lines).
Add a CLAUDE.md scope-discipline section stating the architecture docs
are complete and authoritative, so agents implement against them instead
of extending them. Close the two architecture planning issues.
Fold the old docs/ into the VitePress site and rename docs-2 -> docs.
The 12 architecture PRDs become first-class pages at docs/architecture/
with sidebar nav, rather than being buried under an archive path.
Historical material stays at docs/archive/. Rewrites every docs-2 and
docs/prds/architecture reference across the repo. Site builds clean.
Missed in f800e1d, which ported internal/worktree but stopped at "the
sibling package still compiles".
Both NATS handlers ran their work under context.Background(). The client
side has a Timeout and passes a context, but the server discarded it, so
a prepare or push ran unbounded. That was survivable when the work was a
git child process that could be killed; after f800e1d it is an in-process
go-git clone, so an unresponsive forge wedges the handler goroutine
permanently. Removing the per-repo object cache in that same commit made
clones longer, which widens the window further.
Server now has a Timeout (defaulting to 15 minutes, sized for a large
clone over a slow link) applied via handlerContext, with a table test
asserting both the explicit and default paths produce a bounded deadline.
The fixtures also still shelled out to git, so every test in the package
skipped when no git binary was present and the helpers tripped noctx.
Rebuilt on go-git to match internal/worktree's suite, including pinning
commit.gpgSign=false on the seed repo so fixtures do not inherit signing
from the host's global config.
internal/worktree no longer executes the git binary. Clone, fetch,
checkout, commit, push and diff all run in-process through go-git v6,
which also removes the package's 9 noctx findings since the Context
variants are first-class.
Security: the forge token no longer leaves the process. The old
implementation wrote a GIT_ASKPASS shell script to disk and exported the
token into the environment of every git child process. Authentication is
now an in-process credential passed via client.WithHTTPAuth. cloneURL
also stops embedding the bot user in the GitHub URL.
Dropped the per-repo object cache (PreparePersistent, prepareCache,
CleanupExpiredCaches). go-git can clone with shared alternates but has no
equivalent of --dissociate, so a cached bare repo would remain a live
dependency of every worktree built from it, and expiring one would
corrupt running tasks rather than fail cleanly. Every task now gets an
independent full clone. repo.PersistentStorage still governs the
container volume; only the git object cache is gone.
Two real defects surfaced while porting, both caught by the new tests:
- go-git honours the host's global git config and cannot sign commits
(no gpg fallback, only an ObjectSigner plugin). On any machine with
commit.gpgSign=true set globally, every bot commit would have failed
with "cannot auto-sign commit". setIdentity now pins gpgsign=false in
the clone's own config so daemon behaviour does not depend on the
ambient config of whatever host it runs on.
- go-git's Add(All) does NOT honour .git/info/exclude, which is how the
.archie-prepared sentinel was kept untracked. It was being committed
and would have been pushed onto every task branch. The sentinel now
lives at .git/archie-prepared, where nothing can ever track it, and a
regression test asserts it never appears in a commit.
Diff is now merge-base relative via Commit.MergeBase, matching the three
dot semantics of `git diff origin/base...HEAD`; diffing against the remote
tip would attribute commits landed on base since the branch started to
this task and could trip the diff-size cap. Base resolution tries the
remote-tracking ref first and falls back to the short "origin/<base>"
revision, keeping git's more permissive lookup.
The test suite was rebuilt on go-git fixtures and no longer needs a git
binary installed to run.