coleam00/Archon v0.12.0

Archon CLI v0.12.0

on GitHub

Providers become separate installs for release binaries. The SDLC pack gains intake, build and merge queues, a discoveries drain and attention pauses. Runs wait out usage and rate limits. Workflows can run without a database, keep durable state, and answer through one attention queue.

Upgrading a release binary (quick installer, Homebrew, GitHub asset): add your providers. Release binaries no longer include Claude, Codex or Pi. After upgrading, run:

archon provider add claude codex pi   # only the ones you use

or archon setup, which asks. Until you do, a workflow or chat message that needs a provider fails before it starts and prints this command, and archon doctor fails with the same command. Your config, credentials, database and native provider logins are unchanged. Docker images and source checkouts run all three from source and need no step. (#3645)

SDLC forge access remains on gh by default. Set ARCHON_SDLC_FORGE=forge to opt in after installing a plugin that supports every pack operation. Released GitHub plugin v0.11.1 is insufficient; preflight names missing operations before any AI node runs, after worktree setup. On the forge path the host tries GH_TOKEN, GITHUB_TOKEN, then gh auth token; in Docker that login must be inside the container. GitHub App runs refresh through the run's gh shim. Per-user runs without credentials refuse rather than borrowing the host login. (#3433)

Breaking

• Release binaries ship without the Claude, Codex and Pi providers and run only the ones installed with archon provider add. An installed provider whose version differs from the CLI is refused with the reinstall command, so rerun archon provider add <ids> after every upgrade. The binary no longer contains the Claude Agent SDK, Codex or Pi. OpenCode and GitHub Copilot stay bundled. (#3645)

• Archon no longer falls back to claude when no default provider is configured. A default is chosen only when you set one, or when exactly one provider is installed. This affects binary installs where archon setup never ran and Docker deployments whose .env has no DEFAULT_AI_ASSISTANT line, unless a project sets assistant: in its .archon/config.yaml. Workflows fail before they start and chat messages fail with No default provider: set 'defaultAssistant' in ~/.archon/config.yaml or run archon setup. To fix it, add defaultAssistant: claude (or your provider) to ~/.archon/config.yaml, or DEFAULT_AI_ASSISTANT=claude to the Docker .env. (#3645)

• An invalid tiers, aliases, workflows, streaming, attentionNotices or concurrency block in .archon/config.yaml (global or repository), invalid YAML, a top level that is not a map of settings, or a config file Archon cannot read now fails to load with a message naming the file and the key, instead of being logged while every setting in the file was replaced by defaults. Startup, archon doctor, run starts, chat messages and workflow listings such as archon workflow list report the failure. A missing file behaves as before. Fix the named value to recover. (#4363)

• Pi no longer runs Anthropic models on a Claude Pro/Max subscription connected in Archon. Archon stopped delivering the subscription to Pi, in workflows and in chat, and removed the system prompt that hid Pi's identity from Anthropic: a Claude subscription runs only on the Claude provider. A Pi node or chat turn on an anthropic/* model that relied on the connected subscription now fails before it starts, and the error names provider: claude. Switch those nodes, tiers, aliases or the chat default to provider: claude; you do not need to log in again, because the Claude provider already receives the same stored subscription. Or give Pi an ANTHROPIC_API_KEY. archon doctor reports the same. Pi-native Claude Pro/Max OAuth (pi /login) is also unsupported: Anthropic can reject Pi's default system prompt with a subscription token. Pi's native credential files remain intact; use provider: claude or give Pi an ANTHROPIC_API_KEY for Anthropic models. (#4175)

• A workflow whose when: could never be evaluated now fails to load with an error naming the node, instead of loading and skipping that node on every run. This covers grouping parentheses, malformed comparisons, a trailing invalid clause such as A || <garbage>, when: 'false' used to disable a node, and a numeric operator against a non-numeric literal such as $score.output > 'high'. (#3911)

• The legacy bundled workflows are removed. A fresh install ships only the sdlc pack, so run pr and run review each resolve to one workflow again. The legacy archon-* workflows deprecated since v0.10.0 and archon-assist no longer ship, and neither do the commands under .archon/commands/defaults/ or the legacy archon-review-block include block. A run paused before the upgrade still resumes from the source it captured. To keep one, copy its YAML from .archon/workflows/defaults/legacy/ at v0.11.1 into your project or global .archon/workflows/, and copy every command it names from .archon/commands/defaults/ at v0.11.1 into the matching .archon/commands/. archon-idea-to-pr, archon-plan-to-pr and archon-issue-review-full also need archon-review-block.yaml from the same folder, which they include. Save that copy under another name, such as legacy-review-block (its file name and its name:), and point the three workflows' include: at it: the sdlc pack ships its own archon-review-block, and a project or global copy with that name would replace it. A copied workflow whose commands are missing fails with a command-not-found error. (#3526)

  Removed workflow	Use instead
  archon-adversarial-dev	None
  archon-architect	None
  archon-assist	None. Ask in chat: the router answers questions directly. At v0.11.1 its YAML is .archon/workflows/defaults/archon-assist.yaml.
  archon-comprehensive-pr-review	archon-review
  archon-create-issue	None
  archon-feature-development	archon-deliver, with the plan as its input
  archon-fix-github-issue	archon-ship
  archon-idea-to-pr	archon-ship
  archon-interactive-prd	None
  archon-issue-review-full	archon-ship
  archon-piv-loop	None with human checkpoints. archon-plan then archon-deliver covers the same phases without them.
  archon-plan-to-pr	archon-deliver, with the plan as its input
  archon-ralph-dag	archon-implement
  archon-refactor-safely	None
  archon-remotion-generate	None
  archon-resolve-conflicts	None
  archon-smart-pr-review	archon-review
  archon-test-loop-dag	None
  archon-validate-pr	archon-validate runs the project's checks. Nothing replaces the base-versus-branch end-to-end comparison.
  archon-workflow-builder	None

• An attention wait's output is now its answer instead of { status, waited_ms }, so a workflow that reads status or waited_ms from an attention wait fails to load; read text instead. A run paused at such a wait usually resumes from the workflow source it captured, which still reads the old fields, so it cannot resume: abandon it and start a fresh run of the edited workflow. An attention wait paused before the upgrade that nothing reads continues with archon workflow resume, and the web console may send one repeat push notification for it. (#4038)

• An authored gate now offers and accepts only its declared decisions. The console, chat, Slack and the CLI show each declared decision with its label, and every response path refuses an undeclared decision ID with an error listing the allowed ones. A stale gate action fails without changing a later gate. (#3831, #4048)

• The old workflow marketplace is retired. archon workflow search and archon workflow install are removed, archon.diy no longer serves the registry or workflows.json (older binaries report Marketplace fetch failed: HTTP 404), and archon.diy/workflows/ redirects to the installed workflow packs guide. Install someone else's workflows with archon plugin add owner/repo[/path][@tag]; a workflow pack is published by adding archon-plugin.json to its own repository. Workflows the old installer copied into .archon/workflows/ are ordinary project files and keep loading. The CI job that auto-reviewed, merged or closed registry pull requests is gone with it. (#2376)

• Codex workflow nodes no longer load the user's Codex plugins, ChatGPT apps, or the MCP servers in the user's or project's Codex config. A node gets exactly the MCP servers its mcp: file declares; Archon checks the servers Codex loaded before the turn starts and fails the node as misconfigured if an undeclared one is live. A node that needs a plugin names it with plugins: [name@marketplace] and gets that plugin's skills and hooks; its MCP servers come only through mcp:, under the plugin's own server name. A named plugin that is not installed fails the node before its turn, and so does an mcp: server whose name your Codex config.toml already uses: rename it in the mcp: file. Your config.toml settings, hooks and AGENTS.md keep loading, and Archon never writes to your Codex home. A workflow that relied on an ambient Codex plugin or server adds it to plugins: or mcp:. (#1118, #2843)

• Claude workflow nodes no longer load the Claude Code plugins installed on the machine. A node that needs a plugin names it with plugins: [name@marketplace] and gets that plugin's agents, hooks, LSP servers and commands; its skills and MCP servers still come through the node's own skills: and mcp: lists. A node fails before its first model turn when a named plugin is not installed, or when Claude Code loads a plugin the node did not name. Your own settings, hooks, permissions and CLAUDE.md keep loading. Naming plugins on a provider that cannot scope them (every provider except Claude and Codex) fails the run before any node starts, and so does naming MCP servers or skills a provider cannot load; archon validate workflows reports the same mismatch. (#3574, #3578)

• A GitHub trigger binding whose inputMapping copies an event field into a workflow that has no inputs: block is now rejected at preparation: the receipt's binding is recorded as rejected (launch_preparation_failed), and the drain reports Workflow '<name>' declares no inputs; a trigger cannot pass event-mapped input '<input>'. Event content is untrusted, so it reaches only inputs a workflow declares. To fix it, declare each mapped input under the workflow's inputs:. literal mappings and the literal launch.inputs of a binding or timer still pass through to a workflow without inputs:. (#3980)

• When web auth is on or ARCHON_WEB_AUTH_HEADER is set, a web or cli conversation is reachable only by the user who started it. A non-owner gets 404 Conversation not found. Chats that have no recorded owner become unreachable; start a fresh chat. Solo installs behave as before. (#4224)

• Stored project paths that are not absolute now fail with the project name and a /register-project command to recover. Re-registering a legacy project repairs its path and keeps its identity and history. (#3747)

Security

• The Discord adapter no longer installs vulnerable undici and lodash versions: discord.js resolves to 14.27.0, undici to 6.29.1 and lodash to 4.18.1. (#4389)
• A forge token is sent only to its well-known public host (github.com, gitlab.com, gitea.com) or to the exact authority of the matching GITLAB_URL, GITEA_URL or FORGEJO_URL. A host that merely looks like a forge gets no credentials. (#4154)
• Runs and chat turns authenticate only as the identity they were given, or fail naming the credential. Tokens are no longer sent in cleartext or kept in run evidence. (#4282)
• The Gitea webhook signature is checked over the exact received bytes before the body is parsed, and the Gitea route gets the same 32 MiB body limit as GitHub. Oversized GitHub and source webhook deliveries are refused before authentication and create no receipt. (#4031, #4075)
• Diagnostic and failure logs no longer record platform identities, webhook token fragments, SQL bound values or message contents. Chat SSE no longer carries provider session IDs. (#3628, #3888, #3991)

Added

• archon provider add <claude|codex|pi...> installs or replaces a maintained provider from the Archon release matching the CLI version, verified against the release's checksums.txt. archon setup asks which providers to install and installs them; archon setup --providers codex (or ARCHON_PROVIDERS) skips the question. The quick installers ask the same question after installing the CLI, or take --providers (shell), -Providers (PowerShell) or ARCHON_PROVIDERS; without a selection or a terminal to ask on, they install none and print the command. The Homebrew formula names archon setup and archon provider add in its caveats. Providers also run as plugins over the archon-provider/1 protocol, so a third party can publish one. See Installation → Providers. (#3645, #3895, #3903, #3935, #4004, #4078, #4118)
• Every release publishes a standalone server executable, archon-server-<os>-<arch>, beside the CLI. (#3908)
• Workflows can run without a database: set store: files in ~/.archon/config.yaml to run, pause, approve, resume, inspect and list workflows, admit triggers and keep state documents on the file system. The database stays the default. (#3947, #4007, #4089)
• archon state keeps small, durable JSON documents across runs, with revisioned history. Operators and bash:/script: nodes can read, replace, patch (--if-revision for a conditional patch), list (--values returns every document in one call), audit and delete them, at project or install scope (--install). Each revision records the surface or the run and node that wrote it. (#3981, #4066, #4128, #4376)
• archon workflow attention --watch streams the attention queue as JSON lines across every run in scope, including runs started after the stream by triggers, schedules, the server or another session: the open items first, then ready, then a line whenever an item opens or is relabelled (attention), stops needing an answer (resolved), leaves a --label filter (unmatched), a run ends (terminal), is resumed (resumed), or loses its owner (owner_lost). Every line carries its project; --project and --all scope it as they scope the list. --after <cursor> resumes a stream without missing a change; a cursor the store cannot read ends the stream with an error line and exit 4. Idle bookmark lines arrive only while the stream can read the store. Every write that changes the queue now commits an event, including a resume of a paused run (workflow_unpaused) and a wait a resume reached again (wait_continued). See Stream the queue. (#3050, #4309)
• Outside answerers can work the attention queue as JSON. archon workflow attention --json lists every paused run that needs someone in the current project, another one (--project) or the whole install (--all), filtered by exact --label k=v matches and sorted by age or a label; --count-by project|label:<key> counts them, and archon workflow attention <run> --json reads one item, following a blocked parent to its child's. Each item carries its run, occurrence, node, workflow, message, form and options, labels and revision, pausedAt, a typed project whose key is the one archon state uses, a fanOut position for fan-out children, and pointers to its artifacts, transcript, checkout and branch. wait: attention takes labels:, and archon workflow attention label <run> --occurrence <id> --set k=v --unset k lets a handler classify an item; each write bumps revision and records an attention_labeled event. GET /api/runs/attention takes the same parameters, GET /api/runs/<run-id>/attention reads one item, POST /api/runs/<run-id>/attention/labels writes labels, and manage_run gains a label action. See The Attention Queue. (#4039)
• wait: attention takes an answer in a declared form: message (free text), approval, select or multi_select with options, which may be a literal list or one whole $node.output.<field> reference resolved when the wait pauses. Answer it with archon workflow answer <run> --occurrence <id> [--choose <id>]… [--text <t>], POST /api/workflows/runs/<run-id>/answer, or the console; approve, reject and respond work as shorthand, and reject never cancels the run there. The next node reads the answer as { text }, { decision, text } or { decisions, text }, and run-attention reports the wait as one attention kind with its form and options. Every answer records the surface it came through, and every surface can refuse a stale answer. See Attention waits. (#4038, #4063)
• archon workflow wake continues due durable waits from the CLI, with --watch and an optional macOS timer, and archon workflow signal wakes one exact event occurrence. An answered gate is continued by whichever host is running (archon serve, workflow wake, or the native schedule), and the answer response says the run continues on its own. (#3660, #4050, #4188)
• A run whose failed nodes all hit a provider usage limit with a known reset now pauses until the reset and resumes by itself, holding no resource slot while it waits; the wait shows in the attention queue, workflow status, workflow get and the console. autoResumeOnQuotaReset now defaults to true; set it to false to fail instead. quotaFallbackDelayMs, quotaMaxAttempts and quotaDeadlineMs are ignored with a deprecation warning. A node whose provider rate limit outlasts its five retries pauses on the same wait. Pi still fails on usage limits, because it reports no structured limit. (#4225, #4338)
• A provider overload (Codex serverOverloaded, Claude overloaded) is its own failure class with five retries and capped exponential backoff, and each provider retry of a model call shows as a warning in the transcript and CLI. (#3610, #3849)
• A repository can list worktree.postCreate commands that run in order in each new worktree before it is handed out, each with worktree.postCreateTimeout (default 300000 ms). Each command's start, completion and failure are recorded on the run. (#3973)
• Children of one fan_out node can share the parent's checkout and run up to max_parallel at once. A fan-out child that pauses now waits as its own run, and the parent pauses on a fan_out gate listing its unfinished children, instead of the child being cancelled. (#3965, #4125)
• Output references can reach nested fields: $node.output.a.b and $LOOP_PREV.node.output.a.b work in templates, bindings and scalar when: conditions. (#3616, #3675)
• A command or prompt in a loop_group can continue a named pre-loop session with context: { resume: <node> }, forked once and continued across iterations. (#3961)
• archon workflow logs <run-id> --format text prints a run's transcript as readable progress lines, and archon workflow runs --json --verbose reports each run's nodes and what it waits on. Each AI node records the provider session ID it ran, shown by workflow get --verbose. (#3542, #3543, #3595)
• Runs record every provider event unchanged. GET /api/workflows/runs/{runId}/provider-events serves them, and the console shows tool calls paired with their results under the node that made them, plus native hook events in time order. An overdue tool call or background subtask raises advisory attention. (#3576, #3902, #4137)
• The console can alert when a run waits for you or finishes, with a chime and browser notifications that also reach opted-in browsers when the console is closed. It lists every run that needs input, shows token usage per node, shows the workflow's explanation beside the outcome, and can rename a project (PATCH /api/codebases/{id}) without moving its storage. (#3704, #3711, #3830, #3949, #3978, #4015)
• archon doctor tells a working connected credential from a dead one (usable, not_connected, unusable, check_failed), checks each assistant's native login, reports each registered provider's diagnostics and plugin status, and fails with install guidance when the OpenCode executable is missing. Runs check the credentials their AI nodes need before launch. (#3603, #3635, #3695, #3708, #4004)
• archon user link <user-id> <platform>:<platform-user-id> [--move] binds a platform identity to an existing Archon user. (#3977)
• /detach-project "<name>" detaches the current conversation from a project without unregistering it, and a git root can be registered as a folder project that runs in place with no worktree, branch or PR. (#3741, #4027)
• Poll scripts can send a stable delivery key with JSON event inputs; a retried delivery with the same key and content reuses the accepted one instead of starting another run. (#4009)
• Any service that signs webhooks with the Standard Webhooks v1 HMAC scheme can now start a workflow run, through a bundled source plugin you configure with a signing-secret environment variable and trigger bindings. Archon checks the signature over the exact received bytes and a timestamp within 300 seconds before it records anything; an unsigned, tampered or stale delivery gets HTTP 401 and leaves no record. A retried delivery with the same webhook-id and body starts nothing new, and reusing a webhook-id with different content gets HTTP 409. The delivery body can only fill the inputs a binding maps from it with JSON Pointers, and only inputs the workflow declares; the binding alone chooses the workflow, checkout, isolation, host, resource and run-as user. See Start workflows from any signed webhook. (#3975, #3980)
• A workflow node can name its MCP servers as optional with mcp: { path: <file>, optional: true }. When the provider cannot load MCP servers (Pi, OpenCode) or the config file does not exist, the node runs without them instead of failing validation or the run, and its lifecycle rows record mcp_unavailable with the path and reason. A plain mcp: <file> stays required. Codex and Copilot now also report each MCP server's status, so a declared server that fails to start is recorded and warned about as it already was on Claude. See Optional servers. (#3994)
• Chat plugins: the server installs and supervises chat plugins over the archon-chat/1 contract, and the Slack chat plugin posts attention notices to a channel configured as an attentionNotices route: a gate with its decisions, or a wait: attention with its form as buttons, a multi-select menu, or an answer modal for free text and interactive-loop replies. Answers go through the same authorization as every surface and record slack as their surface; a stale answer is refused in the notice's thread. A run's completion follows up in that thread. See Chat plugins. (#2907, #3910, #3922, #3940)
• Forge plugins can merge pinned to a head, rerun failed checks, convert a pull request back to draft, create marked work items, manage and read labels, list items by label, comment on and close issues, and deliver comment and label-actor events. (#3887, #3893, #3894, #4108, #4117)
• archon validate workflows warns about loose output schemas, unsafe bare output references, and a join whose only dependency is conditional. (#3702, #3722, #3847)
• A pack can ship .md documents in its .shared/ directory. They are bundled with the pack's modules, so a binary install has them too, and a script finds them relative to its own location. See Share code within a pack. (#4100)
• POST /api/workflows/runs/<run-id>/approve and /reject accept an optional expectedGate, as /respond does: a node name or { nodeId, pauseId }. When the run is no longer paused at that gate, the request gets HTTP 409 and the later gate stays open; an empty node name, nodeId or pauseId gets HTTP 400. Omitting it behaves as before. (#4162)
• The SDLC pack gains archon-intake, which triages a maintainer's issue, holds an outside author's issue for promotion, and closes a duplicate or already delivered issue with a link to what resolved it. Triage now searches for open duplicates and records type, size, complexity, importance and urgency as separate fields. (#4116, #4127, #4207, #4302)
• The SDLC pack gains archon-build-queue, which takes a triaged work item to a reviewed pull request and asks a person only what a person must decide, and archon-merge-queue, which merges a clear bug fix or small feature pinned to its head and holds everything else as one attention item. An approval survives a clean merge of the default branch. Both are opt-in: bind a trigger to run them. (#4304, #4319, #4348)
• The SDLC pack gains archon-discoveries, which drains finished runs' discoveries into a new issue, evidence on the issue that already covers it, a recorded drop, or a question for a maintainer. (#4283)
• The SDLC pack gains an opt-in archon-worktree-cleanup workflow that releases merged worktrees on CLI-only installs. (#4328)
• SDLC delivery now reads a pull request's unresolved review threads from any reviewer, judges each like a blocking finding, replies, and resolves it, and the CI agent re-runs a flake outside the change once before judging. (#4082, #4358)

Changed

• A bash: or script: node, and an until_bash check, now runs until it exits unless the workflow declares timeout:. The implicit 120 s limit is gone. A declared timeout ends the node's whole process tree, on Windows and on POSIX. (#4307, #4355)
• A public SDLC stage pauses where nothing would take it forward, instead of ending. When archon-deliver ends not ready, archon-plan or archon-triage stops on a question for a person, archon-ship stops for either reason, or archon-review ends Ready on a draft pull request, the run pauses as one attention item labelled stage: <workflow>, with the agent's recommendation, confidence and evidence and the choices it declared. It continues on the answer: rerun runs the stage again with your note, ready takes the pull request out of draft, and finish keeps the outcome as it stands. Each stage's graph is its own -block workflow (archon-deliver-block, archon-plan-block, archon-triage-block, archon-review-block, archon-ship-block), which the queues, intake and upkeep include, so a run a queue started never raises a second item for a decision the queue owns. A project or global copy of the legacy archon-review-block.yaml now replaces the pack's own review block; rename it as the legacy entry under Breaking describes. (#4311)
• SDLC delivery is one round loop of implement, review and CI with a round limit, review depth scales with the change's risk, and archon-deliver and archon-ship always end with a report, including after a failed node. A delivery's pull request closes its issue only when the review finds every required item met; otherwise the body says Refs #N and lists what is left. archon-ship takes a part input to deliver one part of a plan. The pack's prompts now treat a risk no supported path reaches as no reason for a guard or a test. (#3533, #3804, #3869, #4107, #4158, #4180, #4220, #4398)
• The bundled SDLC workflows use the GitHub CLI by default; ARCHON_SDLC_FORGE=forge selects a compatible forge plugin. Standalone archon-review given a pull-request number, URL or branch, or run on a branch with an open pull request, still reads that pull request with gh pr view and gh pr diff; inside delivery it reviews the recorded pull request and reads nothing from the forge. archon-ship, archon-deliver, archon-upkeep and archon-pr check that the selected source can act before any agent runs, and the CI agent acts on the pull request the run recorded rather than one found from the checkout's remote. They no longer declare requires: [github], so per-user GitHub mode no longer refuses a user without a connected GitHub identity before the run starts; a missing credential refuses at that first check instead, naming the connect step. archon doctor checks the selected source and credential. See Use the forge path in the SDLC pack. (#3433)
• SDLC triage reads the project's .archon/sdlc/policy/triage.md and falls back to a default the pack ships. Under the default, triage closes an item without a person only when it duplicates an open item or a merged change already delivered it; any other item that looks closable, such as an obsolete or out-of-scope one, is BLOCKED for a maintainer. Copy the default from the pack's .shared/policy/triage.md to change it. (#4100)
• Branches that change different bundled pack files no longer conflict on a committed generated bundle. A source checkout reads the bundled packs from disk; only the binary build embeds them. The generate:bundled and check:bundled scripts are gone. (#4395)
• A paused run gives back its resource slot while it waits and reacquires one ahead of new starts when it continues. A same-run gate that pauses while another is open is presented when the run resumes. (#3751, #4135)
• A new run resolves its AI configuration (assistant, provider defaults, tiers, aliases, model bindings) from the checkout it was launched from, including uncommitted content, and keeps that configuration for its whole life, including resume and child runs. (#3827, #3899)
• A run on an existing branch continues the branch at its own head instead of resetting it to the base; a branch that has diverged from its remote fails before any work starts. New projects follow the remote's default branch unless you choose a base. Run commits are authored by the initiating user when per-user GitHub is connected. (#3742, #3746, #4123)
• workflow abandon and /reset remove the worktree the abandoned run created, keeping the branch. A completed run releases its own clean, fully pushed worktree, a failed run unlocks its worktree once its outcome is settled, and the age sweep never deletes work that exists nowhere else. archon complete refuses an environment a run can still resume. (#3856, #4152, #4189, #4328)
• GitHub operations prefer GH_TOKEN, then GITHUB_TOKEN, across adapter API calls, clones and forge operations. Inside a workflow, a GitHub token the forge command inherits wins over both .env files. GitHub App credentials now reach CLI workflows, URL registration, clones and worktree Git on any server port. (#3795, #3806, #4111, #4146, #4324)
• archon setup can configure a GitHub App as well as a personal token, and switching to App mode removes stale PAT credentials. (#4149, #4155)
• New projects get separate storage folders, including $STATE_DIR, when their derived names collide. Registering a second clone of an already-registered remote is refused with the registered project's path; use worktrees for parallel checkouts. A new project whose name or storage folder another path already holds registers under the first free suffixed name, such as _local/api-2 for a second no-remote repo called api or my-app-2 for a folder project. archon workflow run no longer continues unregistered under the shared _cwd/<folder name> storage when registration fails, even with --no-worktree; it fails with the registration error. Existing projects keep their names and storage. (#1192)
• A relative mcp: path in a home workflow (~/.archon/workflows/) now also resolves next to that workflow's YAML file when the run's checkout has no such file, so a personal workflow can keep its MCP config beside it. The checkout is still checked first, and project, bundled and installed workflows use only the checkout. An optional declaration (optional: true) that used to run without servers because the checkout had no file now loads the servers from the file next to the workflow if one is there. A missing-file error lists every location tried. See MCP servers. (#1604)
• Chat on Claude, Codex and Pi launches workflows and registers projects through typed invoke_workflow and register_project tools instead of writing /invoke-workflow and /register-project lines into the reply. A launch runs after the reply ends, through the same dispatch as before, so the console and forges behave as they did. manage_run no longer has a start action; invoke_workflow replaces it and applies the dispatch checks start skipped. OpenCode and Copilot still use the command lines. (#1886, #4202, #4236)
• A workflow that can pause now starts with archon workflow run --detach, from the web console's background dispatch, from manage_run, and from a trigger. Before, a workflow with an approval gate, an interactive loop gate, or a gate composed through include: was refused at all four. Its pause waits durably in the attention queue until someone answers, then the run continues. Workflow-level interactive: is deprecated and has no effect: a workflow that declares it loads with a warning, and the web console no longer runs it in the foreground. (#4041)
• Providers, plugins and skills now use archon provider add, archon plugin add and archon skill add. Adding a provider connects Archon to your agent CLI or SDK; it does not install that CLI. The unshipped provider install verb is refused; the shipped plugin and skill install verbs remain deprecated aliases that print a warning. (#4133)
• Slack is available as an optional Socket Mode chat plugin: archon plugin add coleam00/Archon/plugins/chat-slack. Restart the server after installing. In the plugin, /archon connect github now points to the Web UI or archon auth github; the bundled Slack adapter remains available during the transition. (#3646, #4006)
• The CLI no longer bundles the server or chat adapters. archon serve downloads the version-matched server and web UI on first use, verifies embedded checksums, and runs the server as a child. --download-only caches both. (#3644)
• New Archon users are explicitly created as member. Operators can list users with archon user list and designate or demote admins with archon user role <id> admin|member. Existing users keep their roles, and the database default remains admin for older writers. This is role policy only; run-action enforcement ships separately. Existing multi-user installs remain unprotected until enforcement ships and the operator deliberately demotes users who should not be admins. (#3651, #3829)
• The repo-local repo-triage and repo-triage-minimax maintainer workflows are removed; they were no longer used. scripts/migrate-state-dir.ts still moves a legacy .archon/state/ into $STATE_DIR, but no longer writes the .initialized marker, which only those workflows read. (#4000)
• The chat router no longer uses archon-assist as its example or describes it as the fallback: its examples now name archon-ship, archon-plan and archon-investigate, and questions still get a direct answer. (#3525)
• Provider SDKs updated to latest: Claude Agent SDK 0.3.302, Codex 0.163.0 and Pi 1.3.0, with Copilot SDK 1.0.16 and OpenCode SDK 1.18.34. When Claude Code refuses to start, its stated reason now decides the failure class: a sign-in the organization rejects is an auth failure and is not retried, and a configuration problem such as an invalid proxy URL is no longer retried as a crashed process. A Pi node that resumes or forks a session from a node with restricted tools gets a fresh session's tools again. (#3565, #3726, #3798, #4408)
• A provider setup error is now reported as a misconfigured failure and is never retried, even with on_error: all; chat and the run's failure message say to fix the configuration. Claude reports it for a configuration reason it refuses to start with, a missing or unlaunchable executable, and an unknown model. Claude, Codex and Copilot report it for an unreadable MCP config file, Claude and Codex for a binary that cannot be found, and Pi for a missing or malformed model. Claude's provider_not_allowed refusal moves from an auth failure to misconfigured, and Pi with no credentials for its provider is now an auth failure. (#3566)
• persist_session nodes on OpenCode and Copilot no longer continue the session an earlier run saved, because those providers cannot fork a session and two runs would write into one conversation. Each such run starts fresh, says so in chat, and records a node_session_not_continued event; archon validate workflows warns when the provider is written in the workflow file. Claude, Codex and Pi still continue it. (#2667)
• A persist_session node on Codex continues the session an earlier run saved by forking the saved Codex thread into a new one, so two runs never write into one conversation, and the fork keeps the node's scoped MCP servers and plugins. If the saved thread can no longer be forked, for example because its rollout file was deleted, the node fails as unknown with Codex's error on every run until archon workflow reset-sessions clears the saved session. (#3612)
• Codex now runs each turn on codex app-server instead of codex exec, so a failed turn reports a typed failure class from Codex's own error code instead of unknown: missing or rejected credentials are auth, a used-up usage limit is quota_exhausted (with the reset time when Codex reports a full window, so the run can wait for the reset), and rate limits, overload and a crashed Codex process are retried as rate_limited or transient. A Codex that exits before answering (a binary without app-server, or one that rejects a flag) is misconfigured, with its stderr as evidence. A Codex thread that can no longer be resumed fails the node as unknown with Codex's error; the documented fallback to a fresh thread never ran for Codex. Cancelling a Codex node interrupts the turn before stopping the process, and stops the process anyway if Codex does not answer. CODEX_API_KEY still switches Codex to an API key; the key is held in memory and never written into your Codex home. A changed codexBinaryPath now applies to the next turn, and a broken one fails it as misconfigured. Source installs depend on @openai/codex instead of @openai/codex-sdk. (#3564, #3573)
• Whether a failed node is retried now depends only on the kind of failure Archon recorded, never on the error message. A bash: or script: node's output no longer decides retry: a script whose stderr says "timeout" or "503" is no longer retried under the default on_error: transient, and one that prints "unauthorized" is retried under on_error: all. To retry a failing script, set on_error: all. Every timeout is now transient: a script's timeout is retried when retry: is set, and an AI node that idles out after output, or before its structured output, is retried by default; each of those retries can wait another full idle_timeout, so a hung AI node with the defaults can take three idle_timeout windows to fail. Config errors (a missing command file, a bad input reference, an output_format that cannot compile) and cancelled nodes are never retried, even with on_error: all. A provider error without a typed failure class is unknown, whatever its message says; every built-in provider reports typed classes, so this affects only third-party providers. A loop's retry settings now apply to its failed iteration. (#3522, #3528, #3608, #3620, #4023)
• An AI node or loop iteration finishes when its provider settles, after any background work it reported, not at its first result. (#3530, #3740, #3821)
• A chat message that the platform rejects no longer aborts the run, whatever the error says. Before, a send error that read like an auth failure (for example from a revoked Slack token) stopped the run. Now a failed send is logged and the run continues. A pause whose notice cannot be delivered (an approval gate, an interactive loop or loop_group gate, or an attention wait) stays paused and is answered from the attention queue; the failed delivery is recorded on the run as a pause_notice_undelivered event, which the console's run view and the CLI's progress output show. Failure and completion messages are retried on every send failure instead of stopping at an auth-looking one. (#3608, #4041)
• Feedback on an interactive loop's final gate now runs one more iteration with the feedback as $LOOP_USER_INPUT. (#4325)

Deprecated

• Archon's Codex setup variables are renamed to ARCHON_CODEX_ID_TOKEN, ARCHON_CODEX_ACCESS_TOKEN, ARCHON_CODEX_REFRESH_TOKEN and ARCHON_CODEX_ACCOUNT_ID. Archon passes its environment to Codex, and Codex reads CODEX_ACCESS_TOKEN as an auth input, so the old name could override your own Codex login. archon setup now writes the new names, and re-running it moves an old Codex setup in your .env to the new names and removes the old lines. Until the next release, the old CODEX_* names are still read, but only when CODEX_ID_TOKEN is set and no ARCHON_CODEX_* variable is; the server then logs a warning naming each replacement. Old lines left beside new ones are ignored by Archon but still reach Codex, so they are warned about too. A CODEX_ACCESS_TOKEN without CODEX_ID_TOKEN is treated as your own Codex auth and passed to Codex untouched. (#3562)
• approval: gates, approval.decisions, approval.capture_response, approval.on_reject with $REJECTION_REASON, and interactive loop gates (interactive: true with gate_message, and $LOOP_USER_INPUT) are deprecated in favor of wait: attention forms. They still load and run unchanged, and paused runs of these shapes stay answerable with approve, reject and respond. Each workflow file that uses one gets one load warning per shape, naming its nodes and the replacement. One rewrite changes behavior and is not done for you: a legacy reject cancels the run, while form: approval continues with decision reject, so add a cancel: node on reject where rejecting should end the run. The bundled example workflows and the docs use attention forms only, and --dry-run stubs can now answer an attention wait. See Migrating from approval gates. (#4042)
• The OpenCode and Copilot providers are deprecated. No Archon maintainer owns them; they keep working unchanged and stay bundled, with no removal date, until a community owner publishes each as a plugin. archon doctor warns when one is your default assistant, archon ai default prints the notice when you select one, and the first run in a process that uses one prints it once on stderr (the server logs it instead). An install that uses neither never sees the notice: doctor checks their runtimes only when one is your default assistant or has settings under assistants, and does not list them as installed providers. To take one on, see Deprecated providers. (#3684, #4132)
• quotaFallbackDelayMs, quotaMaxAttempts and quotaDeadlineMs are ignored and warn on load; a usage-limit wait now ends at the provider's reported reset. (#4225)

Removed

• Configuration fields that had no effect, unused SQL files and stale docs are removed. Older config files that still set the removed keys keep loading. (#4196)

Fixed

• Cancelling a run under archon serve now ends its running bash: and script: node process trees within about a second. Pressing Ctrl-C on a foreground archon workflow run, workflow resume or trigger execute also ends the process tree of the node that was running, so a later workflow resume no longer runs that node while the interrupted attempt is still alive. The run is still recorded failed with its stop_reason and stays resumable. On macOS and Linux, a terminal hangup or a killed owner also ends that tree. A descendant that starts its own session or process group (setsid, a daemon) escapes this and can still overlap a resume. Worktree setup commands end their process trees too. (#3552, #4014, #4375)
• A run no longer fails when the host running it cannot read its frozen source for a named script: node, a command node, or a composed block (an unreadable scripts directory, a permissions change, a capture missing from that host, exhausted file descriptors). The run pauses with a source_released event, keeps its completed nodes and its resource slot, and is continued about a minute later by workflow wake, the server, or archon workflow resume on any host that can read the source. This includes a quota-resumed run. A container-isolated run is not continued automatically: it appears in the attention queue until you resume it by hand. A script that is missing or changed in the frozen source still fails the run. (#4209, #4227)
• Two worktree setups at the same moment no longer fail one of them on git's global config lock on macOS and Linux, and repeated setup no longer adds duplicate safe.directory entries. (#4184, #4390)
• The Slack card for a parent run waiting on a child workflow shows the command Slack accepts, and its buttons point to the child instead of failing. The web console shows the same guidance without offering parent approval controls. (#3615, #4391)
• A run started from a source checkout whose built-in provider code changed under it now fails with the archon workflow resume <run id> command instead of telling you to update a plugin that isn't installed. (#4422)
• A ChatGPT subscription connected in Archon no longer replaces CODEX_HOME for Codex nodes, so your Codex config, global AGENTS.md, hooks, plugins and MCP servers load as they do for codex itself. Codex now logs in with the subscription in memory, which also makes it work in direct chat. A connected OpenAI API key now reaches Codex as CODEX_API_KEY (it was ignored before), so Codex bills that key instead of your native login. A run started under an older build with a connected ChatGPT subscription cannot continue its earlier Codex threads after upgrading; restart it. (#2841)
• Pi subscription OAuth works in the compiled binary, Pi nodes with extensions run in parallel again, and a timed-out or aborted Pi node no longer wedges the process or blocks its retry. Pi extension errors, including on Windows, fail the node that loaded the extension. (#3537, #3592, #3627, #3634, #3677, #4076, #4122)
• Token and cost totals are now complete: a Codex node counts every request in its turn, a Claude node counts delegated models and resumed sessions in source installs, loop groups keep usage on early exits, and deferred gate spend counts once after resume. (#3618, #3624, #3896, #4020, #4028, #4053)
• The idle watchdog no longer fails nodes when the machine wakes from sleep. (#3589)
• persist_session continues across runs started from the web UI, the node after a structured-output re-ask continues the real session, and a loop_group resumed at its body gate continues the paused iteration's session. (#3534, #3586, #3587)
• Long-lived workflow wake --watch and server processes stop retrying missing, unreadable, or unverifiable frozen workflow source on this host after three attempts per continuation occurrence and warn once per run per process with the run, path when available, and resume or abandon actions. Other hosts can still resume the run; transient failures keep retrying. Installed wake schedules keep one watch process alive to accumulate the bound. Later waits after manual recovery can wake in the same process. The bound resets on process restart; one-shot wakes do not accumulate it. (#3404)
• On a database shared by several machines, archon workflow wait no longer reports owner_lost for a run that another machine, or another user on this machine, is executing. It reports on its waiting line that the owner's liveness is unknown and keeps waiting on the run's stored state. Slow owner handshakes are retried before a run is reported owner_lost, and a slow Windows stop no longer refuses a live owner. (#3531, #3750, #4079)
• A busy SQLite lock now waits instead of failing the run, a run's events commit and read back in order on PostgreSQL and the file store, runs are found by ID prefix on PostgreSQL, and concurrent state-document patches no longer fail under contention. (#3730, #3796, #3993, #3997, #4092, #4121)
• A late failure write after a cancel no longer reports a false storage error, and an all-refused fan-out fails instead of looking finished. (#3803, #4322)
• Template values from users and runs reach a node exactly as written, and a workflow started over HTTP receives the caller's message byte for byte. Loop-body command files get $LOOP_USER_INPUT and $LOOP_PREV, command files resolve include outputs and their own bindings, until_bash checks receive named inputs, and a dry run resolves $LOOP_PREV and stubs a 1:1 child workflow node like a real run. (#3951, #4022, #4029, #4062, #4087, #4179, #4187)
• A when: with a numeric comparison against non-numeric output is false, so a later || clause can still decide whether the node runs. CRLF and LF workflow files load identically. (#3811, #4321)
• A loop group's output is the iteration's work, whether or not it paused to ask. (#4129)
• A chat-launched workflow no longer starts with a truncated task when the agent's --prompt contains an escaped quote. --prompt "Fix the \"login\" bug" used to launch with the task Fix the \. (#1886)
• In GitHub App mode, gh in a long workflow run no longer fails with 401 once the token resolved at run start expires. Runs whose process has ARCHON_PORT (all server-dispatched runs, except on Windows) put a gh shim first on PATH that fetches a current installation token from the server's loopback endpoint on each call. A CLI run without ARCHON_PORT, a run on Windows, and gh called by a Codex agent keep the start-time token; the first two log workflow.gh_token_refresh_unavailable each time the run's GitHub environment is resolved. First GitHub clones succeed and a failed clone can be retried. See Long-running workflow gh. (#3439, #4097)
• Worktree and project cleanup no longer removes the wrong thing: a failed add rolls back only the checkout it created, a failed conversation link no longer marks a live worktree destroyed, cleanup retires only the registration it observed and keeps replacement directories, container environments stay visible for cleanup, and deleting a codebase with missing worktree ancestors works. Reusing an existing worktree warns and is recorded. (#3828, #3919, #4049, #4211, #4228, #4232, #4281)
• Nested repositories resolve as their own projects, a missing registered project directory gets guidance naming the project and path, /workflow run asks which project to use instead of picking the only one, new unpinned projects follow the configured assistant, and chat stops registering a project when Git detection fails. (#3631, #3656, #3698, #3707, #3721, #4139)
• Container runs start Claude without a host binary, and source installs honor CLAUDE_BIN_PATH and assistants.claude.claudeBinaryPath. (#3735, #3813)
• The source CLI starts from any working directory, so trigger-started runs run. (#3950)
• A corrupt process-owner record can no longer release a lock or slot its owner still holds, a stale wait release can no longer free a later pause's slot, and terminating a Windows process tree no longer fails when the root exits mid-kill. (#4051, #4065, #4222)
• Plugin commands: one unreadable plugin receipt no longer blocks every plugin command, a failed update leaves no backup executable behind, and an install no longer fails when Windows briefly locks the new executable. (#3971, #4008, #4094)
• The console builder edits and saves workflows as authored, keeping comments, anchors and formatting, and validates loop completion fields inline. The console shows the engine's node state and cost scope, keeps chat pinned as content grows, keeps dashboards live across tabs and other processes' runs, and shows when personal settings fail to load. (#3378, #3379, #3668, #3674, #3712, #3716, #3844, #3846, #3966, #4054, #4073, #4221)
• Workflow run titles use the small tier's model and effort, and a user without a usable credential keeps the existing title instead of borrowing another user's. (#3877, #4289)
• The console's per-node cost no longer counts a composed fan-out, a loop group or a retried node twice. A node whose cost restates spend other nodes already show now reads total $X instead of looking like its own spend, so the per-node costs that are not marked as totals add up to the run total. (#3657)
• Codex title generation now starts with no ambient skills catalog, plugins, apps or MCP servers and a read-only sandbox. Native guidance and provider settings still load; failures still fall back to a truncated message title. (#3626)
• Workflow nodes whose output only mentions a credit balance or session limit no longer fail as out of credit. Quota failures now come only from the provider's typed failure, and the node error includes the reset time when reported and tells the operator to resume once the limit reopens. (#3619)
• Parallel nodes that all declare mutates_checkout: false now run in parallel instead of one at a time. When one of them changes the checkout, every guarded node running at that moment fails, and the error names the other guarded nodes that ran in the layer, since the change may not be the failing node's alone. A layer that mixes guarded nodes with any node that isn't checkout-guarded still runs one node at a time. (#3606)
• Two overlapping runs of one workflow in one conversation no longer share a persisted session. Each run's persist_session nodes continue from the session saved when that run started, never from one a sibling run saved later, and a node that finishes without a session id no longer erases the saved one. (#2667)
• A script:/bash: node that reads a variable from .archon/.env, ~/.archon/.env, or config.yaml's env: section no longer warns as if it were a typo, on a fresh listing or a real run. The bundled sdlc pack no longer trips this warning for its own ARCHON_SDLC_FORGE operator switch. A name no configured source supplies still warns. (#3509, #3514)
• Invalid STALE_THRESHOLD_DAYS, SESSION_RETENTION_DAYS and CLEANUP_INTERVAL_HOURS values are rejected at startup with the variable and value, the global conversation limit controls server admission, and workflow answer rejects flags it would ignore. (#4183, #4185, #4195)
• Answer commands report an answer that waits for capacity as success, and workflow status/get --verbose show a node reset on resume as pending. (#3611, #4214)
• GitHub webhook deliveries without a repository owner are acknowledged and ignored instead of erroring. (#3802)

Installation

Quick Install (Recommended)

macOS / Linux

curl -fsSL https://archon.diy/install | bash

Windows (PowerShell)

irm https://archon.diy/install.ps1 | iex

Homebrew (macOS / Linux)

brew install coleam00/archon/archon

Docker

docker run --rm -v "$PWD:/workspace" ghcr.io/coleam00/archon:latest workflow list

Manual Installation

macOS (Apple Silicon)

curl -fsSL https://github.com/coleam00/Archon/releases/latest/download/archon-darwin-arm64 -o /usr/local/bin/archon
chmod +x /usr/local/bin/archon

macOS (Intel)

curl -fsSL https://github.com/coleam00/Archon/releases/latest/download/archon-darwin-x64 -o /usr/local/bin/archon
chmod +x /usr/local/bin/archon

Linux (x64)

curl -fsSL https://github.com/coleam00/Archon/releases/latest/download/archon-linux-x64 -o /usr/local/bin/archon
chmod +x /usr/local/bin/archon

Linux (ARM64)

curl -fsSL https://github.com/coleam00/Archon/releases/latest/download/archon-linux-arm64 -o /usr/local/bin/archon
chmod +x /usr/local/bin/archon

Windows (Manual)
Download archon-windows-x64.exe from the assets below, rename to archon.exe, and add to your PATH.

Release assets

Verify installation

archon version