Ergonex MUST know a persona (ergonex:Persona), the closed set human and agent, and MUST resolve it for a run from, in this order, the option --persona, the variable ERGONEX_PERSONA, the persona of the manifest and human; a word that is none of the two MUST end the run with ergonex:Usage naming both.
Enforced (none): draft: no code exists, so nothing proves it
Ergonex MUST know a harness (ergonex:Harness), the closed set claude-code, codex, herdr and other, resolved from the option --harness, the variable ERGONEX_HARNESS and other, with an optional session identifier from --session or ERGONEX_SESSION (text of at most 128 characters with no control character); herdr names the runtime that hosts agents and not an agent, so that WHERE a run reports HERDR_ENV=1 and a harness other than herdr, the evidence record MUST name both.
Enforced (none): draft: no code exists, so nothing proves it
WHILE the persona is agent, a command MUST NOT prompt and MUST NOT read a terminal; WHERE it would ask, it MUST end with ergonex:Usage naming the option or the entry of the agents policy that answers the question; its default output MUST be the JSON envelope (headless.envelope/1), and the text form MUST be had only with --text.
Enforced (none): draft: no code exists, so nothing proves it
WHILE the persona is agent, a command that changes the host or the workspace (setup, apply, render without --dry-run or --check, repos add|remove|delete|adopt without --dry-run, worktree create|prune, remote bootstrap) MUST be refused with E-AGENT-DENIED and the status ergonex:Findings unless the agents policy of the manifest allows it; a command that only reads MUST be allowed.
Enforced (none): draft: no code exists, so nothing proves it
The manifest MUST take an optional typed agents policy: allow (a closed list of the command names of FR-004), repos ("all" or a list of remotes the persona may change), tier (public, operator or administrator, the ladder of Headless, public where absent), commit (the name, email and trailer of FR-008), disposable (a boolean) and remote (the list of hosts remote may reach); the decoder MUST refuse an unknown key and a value outside its set, naming the key, and an absent policy MUST mean that nothing of FR-004 is allowed.
Enforced (none): draft: no code exists, so nothing proves it
WHILE the persona is agent, the evidence record of every run (0002-workspace-modelFR-041) MUST also name the persona, the harness, the runtime where there is one and the session.
Enforced (none): draft: no code exists, so nothing proves it
Ergonex MUST read the token for the Git host and the package registry from, in this order, ERGONEX_GITHUB_TOKEN, then the file named by ERGONEX_GITHUB_TOKEN_FILE, then the file ergonex/token of the configuration folder ($XDG_CONFIG_HOME, commons 0031-install-locations); a file MUST be refused where it is readable by anyone but its owner; a token MUST NOT be accepted as an argument of any command; no output (the report, the problems, the evidence record, the log, the answer of a tool) MUST hold the value of a token it read: it MUST be written [secret]; and WHILE the persona is agent a token found in the environment MUST be accepted for the run and agent doctor MUST give it as a warning, because a secret in the environment of an agent is an ambient secret (estate 0008-estate-workstationsFR-015).
Enforced (none): draft: no code exists, so nothing proves it
WHERE the agents policy gives a commit, ergonex apply MUST set user.name and user.email in the local Git configuration of each repository the policy lets the persona change, and the generated commit-msg hook (0003-hostFR-014) MUST refuse, WHILE the persona is agent, a commit message that lacks the trailer line; agent doctor MUST give a warning where a repository it may change has no such identity.
Enforced (none): draft: no code exists, so nothing proves it
ergonex agent brief MUST be a report that changes nothing and gives the map of the workspace: the root and its area, each repository (path, remote, branch, state, worktrees), the pinned tools and whether each is present, the hooks, the policy including agents, the commands the persona may run and those it may not (FR-004), how to run the checks of each repository where its AGENTS.md says so, and the rules of commit of FR-008; in Markdown with --format md and in JSON with --json, with the same bytes for the same state, with no secret and no content of a repository's files but the lines it takes from AGENTS.md.
Enforced (none): draft: no code exists, so nothing proves it
The Markdown of the brief MUST NOT be longer than 32 KiB (the size that Codex reads as instructions by default, project_doc_max_bytes), and WHERE the map is larger it MUST list the repositories by the time of their last change, newest first, and name how many it omitted.
Enforced (none): draft: no code exists, so nothing proves it
ergonex agent init --harness H [--scope user|project] MUST write only the files that the adapter of the harness H names, MUST be a report with --dry-run, and MUST know the adapters claude-code, codex, herdr and other as a closed set, each reaching its harness only through the public files and commands of that harness (a file the harness reads, or its own command); the adapters MUST be instances of one port, ergonex:HarnessAdapter, and WHERE Ergonex becomes a Kanon host (OQ-1) they MUST be the instances of its Physical layer.
Enforced (none): draft: no code exists, so nothing proves it
Every file agent init writes MUST be written whole beside the old one and renamed over it, MUST touch only what is its own (a block between two marker lines in Markdown, an entry of its own name in JSON and TOML, the keys it owns in a settings file) and MUST keep every other key, entry and hook, including those that another tool wrote, such as the SessionStart hook of herdr; run twice with nothing changed it MUST change nothing and say so; and it MUST write no secret.
Enforced (none): draft: no code exists, so nothing proves it
The adapter claude-code MUST write the brief as a block of AGENTS.md and, WHERE there is no CLAUDE.md in the folder, a CLAUDE.md that imports it (@AGENTS.md); MUST register ergonex mcp as the server ergonex of .mcp.json with the absolute path of the installed command and add ergonex to enabledMcpjsonServers of the user's ~/.claude/settings.json, so that a project server needs no interactive approval; and MUST add a SessionStart command hook that runs ergonex agent brief --harness claude-code --format md in under a second, its plain-text output being the context Claude Code adds.
Enforced (none): draft: no code exists, so nothing proves it
The adapter codex MUST write the brief as a block of AGENTS.md (the project's, or ~/.codex/AGENTS.md at the user scope) and the table [mcp_servers.ergonex] of ~/.codex/config.toml or the project's .codex/config.toml with the command as the absolute path and a startup_timeout_sec of at least 30, and MUST NOT claim a server works from codex mcp list, which reads the configuration and does not connect.
Enforced (none): draft: no code exists, so nothing proves it
The adapter herdr MUST make sure that herdr is installed by the checked installer of herdr or by mise (never by running a script it has not checked), MUST run herdr integration install <agent> for each coding agent on the PATH that herdr names, and MUST NOT write herdr's own files itself.
Enforced (none): draft: no code exists, so nothing proves it
WHERE the host is Omarchy, the adapters MUST write the personal rules into the block of ~/.agents/AGENTS.md, which Omarchy links into each harness that exists (omarchy agent instructions), and MUST NOT make the directory of a harness that was never used.
Enforced (none): draft: no code exists, so nothing proves it
ergonex agent doctor MUST be a report that changes nothing and says, each as a finding of ergonex:Error, ergonex:Warning or ergonex:Informational: whether a token is there and may read packages (0004-onboardingFR-006) and, where its expiry is recorded (FR-029), how long it has left; the Git identity (FR-008); the pinned tools; whether the registry and the Git host answer; which of the harnesses are installed and their versions; whether the configuration that agent init wrote is still there and agrees with the brief; whether ergonex mcp answers a handshake; and the state of jobs (FR-024).
Enforced (none): draft: no code exists, so nothing proves it
agent doctor MUST say, as an informational finding, whether the machine is a disposable environment (ergonex:DisposableEnvironment: a virtual machine or container, or disposable: true in the policy); and WHERE the host is Omarchy and not disposable it MUST recommend, in these words, "run agents on a disposable Omarchy virtual machine or a spare machine, not on a machine you live in", and name the published virtual machine image and omarchy-setup-security-sshd --key=KEY, the Omarchy command that turns the SSH server on, as the way in.
Enforced (none): draft: no code exists, so nothing proves it
ergonex mcp MUST serve the verbs of the program that the held tier may see as the tools of a tool server on standard input and standard output through the surface of Headless (serve, stdioTransport), with nothing else on standard output, the logs on standard error, the descriptions made from the command declarations and no second list of them, and MUST be the one way a harness reaches Ergonex as a server.
Enforced (none): draft: no code exists, so nothing proves it
The tier of ergonex mcp MUST be the lower of the tier the policy gives (agents.tier, public where absent) and the tier of ERGONEX_TIER, and a call MUST be refused as a tool result with isError and a refusal, never a prompt, where the tier, FR-004 or the option --read-only (or ERGONEX_READ_ONLY) forbids it; and a destructive action MUST go only as a preview.
Enforced (none): draft: no code exists, so nothing proves it
ergonex agent keys line --public-key FILE --role read-only|full MUST print, as text only and writing no file, the authorized_keys line that forces a key to ergonex mcp (with --read-only for the role read-only) and the Match block of sshd_config, made by ssh-inbound of Headless, and MUST refuse a text that is not one public key line without naming any part of it.
Enforced (none): draft: no code exists, so nothing proves it
The tool server MUST answer the revision of the protocol that Headless serves (2025-06-18, with initialize), and MUST be proved with at least one client that Ergonex did not write (FR-040); WHEN a client of the revision 2026-07-28 (no handshake) is found that does not accept the earlier one, the server MUST be made dual-era (OQ-3).
Enforced (none): draft: no code exists, so nothing proves it
WHILE the persona is agent, a command run with --job MUST write a record of the job under <workspace area>/jobs/<id>/ (a sortable unique identifier, the command line without any secret, its state queued, running, succeeded, failed or abandoned, its exit status and the path of its evidence record), MUST run in a process that has no controlling terminal and outlives the end of the SSH session that started it, and MUST print the identifier at once; ergonex agent jobs list|show|wait|cancel MUST read and act on them, wait --timeout ending with ergonex:Pending where the job has not ended.
Enforced (none): draft: no code exists, so nothing proves it
A job that changes the host MUST be started only with the hash of the plan it carries out (--plan-hash, the hash ergonex plan printed, 0002-workspace-modelFR-042), and a hash that is not the plan's MUST refuse it and change nothing.
Enforced (none): draft: no code exists, so nothing proves it
WHEN a job is read and its process is not alive and it did not write an end, it MUST be abandoned and its record and evidence MUST stay, never be removed or made to look as if they succeeded.
Enforced (none): draft: no code exists, so nothing proves it
ergonex remote bootstrap TARGET and ergonex remote run TARGET -- ARGS MUST take a target as ssh://user@host:port or a host name of the SSH configuration, MUST refuse a target the policy's remote list does not name, and MUST reach it only with BatchMode, no terminal, StrictHostKeyChecking=yes, and a file of known hosts of its own (<workspace area>/known_hosts).
Enforced (none): draft: no code exists, so nothing proves it
Before it reaches a host for the first time, remote bootstrap MUST have the host's key: from --fingerprint SHA256:... given by the caller, or, with --trust-on-first-use, from a scan whose fingerprint it prints and records; with neither it MUST refuse, ending with ergonex:Usage and printing the fingerprint so that it can be checked by another way; a changed key MUST refuse and say so (RFC 4251, section 4.1: the client must know the server's key beforehand).
Enforced (none): draft: no code exists, so nothing proves it
remote bootstrap MUST: probe the host (uname, /etc/os-release, the architecture) and refuse root unless --allow-root; make sure Bun, or Node 26, is there as 0004-onboardingFR-008 says; install the pinned Ergonex of this version from the package registry by a script it sends over the SSH channel on standard input with its SHA-256 checked, never from an address of a script it has not checked; write the token to a file of mode 0600 from standard input (--token-stdin), never from an argument or the environment of the local command, with, where it is given, the expiry it records beside it (--expires-at); run ergonex init --persona agent with the policy of --policy FILE, which it decodes locally before sending; run agent init for each --harness; run agent doctor --json and return its report; and prove ergonex mcp by a handshake over the same SSH connection.
Enforced (none): draft: no code exists, so nothing proves it
remote bootstrap run again with nothing changed MUST change nothing and say unchanged for each step, and with --dry-run it MUST probe the host and print the steps and change nothing; the token of a GitHub App installation lasts one hour, so ergonex remote token refresh TARGET --token-stdin MUST rewrite the file atomically, and the private key of the App MUST never go to the machine.
Enforced (none): draft: no code exists, so nothing proves it
remote run MUST run exactly one ergonex command on the target without a terminal, bounded by --timeout, and give its status and its JSON envelope, and MUST refuse any other program unless the policy says remote may run raw commands.
Enforced (none): draft: no code exists, so nothing proves it
Where the target is not Linux, remote bootstrap and remote run MUST refuse with ergonex:Environment naming the phase in which that system comes (macOS, then Windows OpenSSH) and change nothing.
Enforced (none): draft: no code exists, so nothing proves it
Everything that differs by distribution (the package manager, the service manager, how the SSH server is turned on, the PATH of a command run over SSH, how a distribution is recognized) MUST be behind one interface, ergonex:Distro, whose reference implementation is Omarchy and which has a generic fallback, and no other code MUST test for a distribution by name.
Enforced (none): draft: no code exists, so nothing proves it
The Omarchy implementation MUST recognize Omarchy by ID=omarchy in /etc/os-release (read in Omarchy 4.5.0), MUST NOT rely on OMARCHY_PATH (the desktop session sets it and an SSH command does not), MUST put the installed ergonex where an SSH command finds it (~/.local/bin, which Omarchy puts on the PATH of SSH commands through pam_env) and write the absolute path into the files of FR-013 and FR-014 all the same, MUST install tools with mise and not with pacman unless the policy allows the package manager, MUST NOT treat a mise shim that exists as proof that a tool is installed (in Omarchy 4.5.0 node, gh, claude and codex are shims whose first run starts an install over the network) and so MUST ask mise which tools are installed without running a shim, and MUST NOT change a configuration of Omarchy that Omarchy's own commands own.
Enforced (none): draft: no code exists, so nothing proves it
The site MUST have a how-to page, "Give an agent a machine", that explains the flow of FR-027 to FR-030, the policy, the tiers, the forced-command key and why a disposable Omarchy virtual machine or a spare machine is the place for agentic work, and an AI guide for an agent that is given a machine, each linking to the specifications and not copying them (commons 0011-documentation).
Enforced (none): draft: no code exists, so nothing proves it
This specification amends 0001-ergonexFR-030: the tree of the program MUST also hold the commands agent (brief, init, doctor, jobs, keys), mcp and remote (bootstrap, run, token), each declared as 0001-ergonexFR-007 says with its action (a report for agent brief, agent doctor, agent jobs list|show|wait and agent keys line; an action for agent init, agent jobs cancel, remote bootstrap, remote run and remote token refresh), and ergonex mcp MUST be reachable from the local channel and from SSH only.
Enforced (none): draft: no code exists, so nothing proves it
This specification amends 0001-ergonexFR-022: every command MUST accept --persona, --harness and --session, resolved once at the boundary into a typed value, and the evidence record of 0001-ergonexFR-023 MUST carry them as FR-006 says; and it amends 0004-onboardingFR-004 and FR-006 for the persona agent: the token is read as FR-007 says, so that they hold on a machine on which gh is not signed in.
Enforced (none): draft: no code exists, so nothing proves it
ergonex agent register MUST be an action that writes the declaration of this machine as an asset of the kind workstation (estate 0008-estate-workstationsFR-020), origin self, state adopted unless the person gives another, with the attributes the probe-free facts give (coordinator, persona, harnesses, agents-policy, and os-family and distro from /etc/os-release), to fleets/<fleet>/hosts/<id>.ts of the tenant repository the person names, written whole beside the old one, and MUST refuse a name the estate does not accept or a file that is there already with other content.
Enforced (none): draft: no code exists, so nothing proves it
Given the persona agent and a manifest with no agents policy, When the harness runs ergonex setup, Then it is refused with E-AGENT-DENIED and nothing changes, and ergonex status still runs, per FR-003 and FR-004.
Given a manifest whose policy allows apply for one repository, When the persona runs ergonex apply and then ergonex apply again, Then that repository is cloned and the second run changes nothing, per FR-004 and FR-005.
GivenERGONEX_GITHUB_TOKEN_FILE naming a file readable by another user, When any command runs, Then it is refused naming the mode, and with the file at 0600 no output holds the value, per FR-007.
Given a workspace and a .claude/settings.json that already holds a SessionStart hook of herdr, Whenergonex agent init --harness claude-code runs twice, Then the hook of herdr is still there, Ergonex's own entries are there once, and the second run says it changed nothing, per FR-012 and FR-013.
Givencodex is installed and ergonex agent init --harness codex has run, When the server named in config.toml cannot start, Thenagent doctor finds it by a handshake and codex mcp list is not the proof, per FR-014 and FR-018.
Given a key forced to ergonex mcp --read-only, When a client over SSH calls a tool that changes the host, Then it gets a tool result that refuses with the reason, and a tool that reads gives its answer, per FR-021 and FR-022.
Given a machine with an SSH server and a key, Whenergonex remote bootstrap ssh://agent@host:22 --fingerprint SHA256:... --token-stdin runs, Then Ergonex is installed there, agent doctor --json is returned, ssh host ergonex mcp answers a handshake, and run again it says unchanged, per FR-027 to FR-030.
Given a host whose key differs from the pinned one, Whenremote run is tried, Then it refuses and no command runs, per FR-028.
Givensetup --job --plan-hash H started over SSH and the SSH session ending, When the job is read later, Then it is succeeded or failed with its evidence, and with a hash that is not the plan's nothing is started, per FR-024 and FR-025.
Given an Omarchy host that is not a virtual machine, Whenagent doctor runs, Then it recommends a disposable Omarchy virtual machine and names omarchy-setup-security-sshd, per FR-019 and FR-034.
Given a target that is not Linux, Whenremote bootstrap runs, Then it refuses naming the phase, per FR-032.
This specification MUST carry the alignment of its terms to the standards that name something near them (commons 0018-standards-firstFR-001), each row saying what was read, how close the term is or that it is unaligned, and what was not verified.
Term
Standard and term
Relation
Verified
Tool server over standard streams (ergonex mcp)
Model Context Protocol, revision 2026-07-28, the stdio transport: newline-delimited JSON-RPC; the server writes only messages to stdout
closeMatch for the transport; the revision served is 2025-06-18 (FR-023)
the stdio and versioning pages of 2026-07-28 were read; the text of 2025-06-18 was not: its name is Headless' constant
Host key pinned before the first connection (FR-028)
real files in a temporary home, including a settings.json that herdr's own installer wrote (the real herdr 0.9.5 binary) and a config.toml that codex mcp add wrote (the real Codex CLI)
detection by ID=omarchy, the PATH of a non-login SSH command, a shim that is not installed, the recommendation
the real Omarchy 4.5.0 virtual machine image (observed here: ID=omarchy, the PATH, the shims; software emulation, about two minutes to SSH; hardware acceleration on a machine with KVM is not verified)
Not verifiable here, and so never claimed: a full agent session of Claude Code, Codex or herdr (it needs an account of each); herdr's remote machines against our host (they are herdr's own feature: this work does not exercise them); Omarchy on real hardware and with a desktop session; macOS and Windows OpenSSH (nothing was run); the GitHub App installation token itself (it needs the owner's App: the tests use a file with a made-up value and record that).
Two harnesses on one machine: each adapter writes its own block and entry, and the AGENTS.md block is one, per FR-012.
A CLAUDE.md that exists and does not import AGENTS.md: Claude Code reads only it, so the adapter adds the import line in a block of its own and never rewrites the file, per FR-012 and FR-013.
ERGONEX_PERSONA set to agent in a login shell by mistake: the person's commands are refused with the answer FR-003 gives, which names --persona human.
A token file that is a symbolic link to a file of another mode: the mode of the target is the mode, per FR-007.
The SSH connection drops during remote bootstrap: the next run finds each step unchanged or finishes it, per FR-030.
The harness has SSH access to the machine with a key, as the person gave it; Ergonex does not make users or open ports (on Omarchy that is omarchy-setup-security-sshd).
A harness that is run by a person on their own machine is the human persona: the persona is for an agent given a machine.
Whether the harness adapters become a Kanon family (ergonex-harness-<name>, packages in the Physical layer of Ergonex). Ergonex does not declare kanon today and its root files are not in folders, so it would have to be restructured first; until it is, the adapters are folder instances behind one port (FR-011) so that they can be lifted. The owner leans to the family.
Whether the ergonex: terms of this specification (Persona, Harness, Distro, Job, Agent policy, Disposable environment) become an ontology namespace ergonex. There is none today: the ergonex: names are defined by the specifications. Unaligned terms need Decisions of the owner.
Whether the adapter herdr is a harness at all: herdr hosts agents and the integrations are per agent. FR-002 and FR-015 treat it as the runtime, as the owner's list names it; the evidence records both.
Who makes the installation token (the controller holds the App's private key and passes the token on standard input) and where that key lives: the owner's.
Whether claude-code should register the server with claude mcp add --scope user where the command exists, instead of .mcp.json and enabledMcpjsonServers; both are documented ways.
A harness given an SSH machine and a key installs Ergonex with one command, reads the brief and works through the tool server within its tier, and each step is proved by a test that names what it ran against.