Harness laws: settings and directors #

The shared rules (what a law secures, the adversary, H1 to H6) are in harness.md.

S4. Settings as console variables #

Each setting is a console variable (a cvar). One table declares each cvar once: its id, its type, its scope, two flags and its default. The id is the dotted path of the key in settings.json (retry.enabled).

1. The registry holds each id once. A second declaration of an id, or a default that does not have the type of its cvar, stops eukhe at startup (RegistryError).
2. The scope is Global or Local. A Global cvar has one value for every agent: only the global config sets it. A Local cvar can have a different value in each agent.
3. persist: an agent can write its sets of the cvar to its cfg. replicate: clients see the value of the cvar.

The value of a cvar comes from layers. A higher layer wins:

default < config < each agent of the family, root first:
                   its profile < its own sets

• The config is settings.json (global, then project) and then config.cfg (global <agent dir>/config.cfg, then project .eukhe/config.cfg). The project files obey the project trust rules of settings.json. A project file never sets a Global cvar.
• The profile of a subagent is subagent.cfg, then agents/<name>.cfg for a named agent. The root session is the agent main.
• The sets of an agent are its runtime sets (/set, /toggle, the session switches). They are session state: the conversation document eukhe.cvar.agent, committed on each change. So the state tree shows them, and a rewind or a fork restores them.

In each layer, the last valid set of a cvar wins. A set is valid when its cvar is declared and its value has the type of the cvar. In a profile or an agent's sets, the cvar must also be Local. A set that is not valid is rejected with a typed error (CvarError): Undeclared, BadValue, Global, NotBool.

A subagent starts from the family of its parent: the spawn carries the parent's layers. Its own profile and sets go on top of them.

The session switches (transport, steering mode, follow-up mode, auto retry, auto compaction, service tier) are sets of the session's own agent. They do not change another session. A session cannot set a Global cvar: /set --global writes it to the global config.cfg. A toggle in /set --global flips the value of the global layer only (the global settings.json, then the global config.cfg). A project file never changes what it flips. The read, the change and the write of a cfg file hold the lock of the file, so two sessions that write at the same time do not lose a set. A cfg file that exists but eukhe cannot read is a settings error, and eukhe does not write it. The errors of a profile file and of an alias in the agent state that does not parse are settings errors too. The eukhe.settings service shows the settings errors of a session as an eukhe.settings_error row of its main conversation (display-only: the model does not see it). It shows the errors at open, and after a reload it shows each new error. It shows each distinct error one time for each session that eukhe opens.

The command language is the same in the cfg files, in the /set slash command family and in key binds. A line is a list of commands, separated by ;. A word in double quotes keeps its spaces.

Command	Does
set <id> <value>	Sets the cvar.
toggle <id>	Sets a Bool cvar to the opposite of its value in the agent, with the values the agent inherits.
alias <name> "<cmds>"	Gives a name to a list of commands.
bind <key> "<cmds>"	Gives the commands that a key press runs.
action <id>	Runs a built-in client action (in a bind).
<name>	Runs the alias <name>.

4. An expansion replaces each run of an alias with its commands. It nests at most one level per alias of the table and one more. A deeper nest repeats an alias, so it is a cycle (ExpandError::Cycle). A run of an alias that does not exist is ExpandError::Unknown. An expansion that fails runs nothing.
5. The key binds are in <agent dir>/binds.cfg. The first bind of a key wins: the user's binds come before the default binds. A key with no bind runs nothing; an empty bind (bind <key> "") turns off a default. The default actions that share a key share one bind; the screen that gets the key runs its own action. A key press sends its set, toggle and alias commands to the session and runs its action commands in the client. eukhe writes binds.cfg one time from keybindings.json when binds.cfg does not exist; the binds it writes give each key the actions that keybindings.json gave it. A binds.cfg that eukhe cannot read, or an import that eukhe cannot write, shows a warning at startup and at /reload.
6. /cvar save writes the agent's sets of persist cvars to its agents/<name>.cfg. Read back as the profile, they give the same values.

Model: bend/cvar.bend (registry, value, written, toggle, expand, press). Laws: LAWS.bend section (S4). Proofs: PROOF.bend section cvar. Every input is free: any declarations (with duplicate ids and wrong defaults), any config, any family of agents with any profiles and sets (wrong types, Global cvars, undeclared ids), any alias table and any binds.

Law	Says
cvar_registry_unique	The registry holds each id once (S4.1).
cvar_registry_typed	Each default of the registry has its type (S4.1).
cvar_value_typed	Each value has the type of its cvar in each agent; an undeclared cvar has no value.
cvar_inherits	A subagent with no profile and no sets has its parent's values.
cvar_set_wins	The last valid set of a subagent wins over its parent's value.
cvar_global_uniform	A Global cvar has one value in each agent: the config on the default (S4.2).
cvar_written_flagged	An agent writes to its cfg only persist cvars and replicates only replicate cvars (S4.3).
cvar_persist_roundtrip	The written cfg, read back as the profile, gives the same value of each persisting cvar (S4.6).
cvar_toggle_twice	Two toggles give back the value.
alias_expands_fully	An expansion leaves no alias to run, or it reports a cycle or an unknown alias (S4.4).
alias_self_cycle	An alias that runs itself is a cycle (S4.4).
alias_unknown_reported	A run of an alias that does not exist is reported (S4.4).
alias_runs_body	An alias of plain commands runs exactly its commands (S4.4).
bind_press_plain	A key press runs only plain commands (S4.5).
bind_unbound_runs_nothing	A key with no bind runs nothing (S4.5).
bind_first_wins	A key press runs the commands of the first bind of the key (S4.5).

Code: eukhe-types/src/cvar.rs (the command language: parse_list, parse_script, Aliases, expand, Binds::press); eukhe-core/src/settings/cvar.rs (Registry, Cvars::value, Cvars::execute, Sets::written, document_sets) and settings/cvar/table.rs (the declarations); settings/cfg.rs (the config layer: settings.json, then the config.cfg files under the trust rules); settings/manager.rs and settings/getters.rs (the getters, all through Cvars); eukhe-core/src/durable/cvar_agent.rs (the session's agent: CvarAgent, the eukhe.cvar.agent document, run_cvar_line, save_agent_cfg) and durable/settings.rs (EukheSettings: the family of the session over its config). The daemon commands cvar { line, global } and cvar_save run them (eukhe-daemon/src/setting_switches.rs); a refused command answers its CvarError with data: { kind, id?, message }. A spawn carries the parent's family in the create config (cvarFamily). The TUI sends /set, /toggle, /alias and /cvar as cvar lines (eukhe-tui/src/session_ui/cvar.rs).

Ties: the bridge test settings::cvar::bridge::the_rust_cvars_equal_the_bend_model compares transcripts with bend/bridge_cvar.bend byte for byte. It runs 300 generated scenarios: registries (with duplicate ids and wrong defaults), values over a config and a family (wrong types, Global cvars, undeclared ids, profiles and sets), toggles of the last agent of a family (a subagent toggles a value that it inherits), the written sets (persist and replicate), expansions (cycles, unknown aliases) and key presses. The scenarios reach every rule.

Regression tests: a_switch_changes_only_its_own_session (daemon: two workers over one agent dir; the switches of one do not change the other or settings.json); a_setter_never_clobbers_a_global_settings_file_that_failed_to_parse (a setter refuses to write over a settings.json that did not parse); cvar_rejects_a_global_cvar_from_a_session; a_subagent_inherits_its_parents_family_under_its_profile; a_fork_starts_from_the_agent_state_at_its_fork_point; an_unreadable_cfg_file_is_reported_and_never_overwritten; concurrent_global_sets_both_land; a_global_toggle_flips_the_global_value_not_the_projects; profile_and_agent_alias_errors_reach_the_manager; settings_errors_show_as_a_row_of_the_session; unreadable_binds_cfg_and_failed_import_are_warnings; the keybindings::tests of the binds.cfg import and of the presses.

S4b. Config documents #

The config documents are settings.json (global and project), mcp-connections.json and auth.json. No input of these documents is lost in silence.

1. A writer reads the document under its lock, applies its change, and writes the result. When the read fails (the file cannot be read, it is not valid JSON or not an object, or its version is not known), the writer writes nothing and returns the error. Only a file that is not there reads as empty. Each key that the change does not touch keeps its value. This applies to eukhe mcp add and eukhe mcp remove, to each settings setter, to the connection records and to AuthStorage set and remove. set and remove return the error to the caller.
2. A settings setter writes the document that is on disk when it writes, not the copy that it loaded. A key that failed to load stays, and a key that another writer added stays. The setter refuses a value that its setting does not hold. When a higher layer sets the same setting (the global config.cfg, the project settings.json or the project config.cfg), the setter says which file sets it (Persisted::Shadowed), and the client shows it. The daemon shows a default model or thinking level that it could not save as a settings error row.
3. Each leaf of a settings.json applies or is named by a settings error. A leaf is a value that is not an object, or the whole value of a cvar. A value that its setting does not hold is BadValue; a key that no setting declares is Undeclared. These are the same CvarErrors as for config.cfg, and they show in the same row. One bad leaf drops only that leaf. The known top-level keys come from the Settings type.
4. A malformed limit fails closed. A providerMaxInFlight entry that is not a whole number limits its provider to 1 request; a value that is not a map limits each provider to 1. idleEvictionMinutes and the session archive rules are a whole number, off or none (NatOrOff); another value is a settings error.
5. An untrusted project does not change a limit, a system prompt or a credential: maxToolRounds, subagentMaxConcurrency, subagentStallMs, toolBlockingBudgetMs, autonomous, directors, thinkingBudgets, retry.maxRetries and retry.failover.maxRetries are withheld with the keys that run code, and so are the project SYSTEM.md and APPEND_SYSTEM.md. The trust warning names them. trustedProjects comes from the global layer only (the global settings.json, then the global config.cfg).
6. An mcpServers entry is a unit: a project entry replaces the global entry of its name, and it never takes a URL or a credential from it. kernelTransport is a unit too.
7. The sessions directory has one precedence for each reader (the CLI, the dashboard, the gateway and the daemon, settings::resolve_session_dir): the --session-dir flag, then EUKHE_SESSION_DIR (or the legacy EUKHE_CODING_AGENT_SESSION_DIR), then the sessionDir setting, then <agent dir>/sessions.

Model: bend/config.bend. Laws: LAWS.bend section config. Proofs: PROOF.bend section config.

Law	Says
rmw_refuses_broken	A document that could not be read or parsed is never written (S4b.1).
rmw_keeps_others	A write keeps each key that the change does not touch (S4b.1).
rmw_applies_change	The key that the change sets has the value that it sets.
settings_save_preserves	A setter writes the document on disk with its key changed, whatever copy it loaded (S4b.2).
leaf_applied_or_reported	Each leaf applies or is named by a diagnostic (S4b.3).
leaf_not_both	No leaf both applies and is named.
limit_malformed_fails_closed	A malformed in-flight limit limits to 1, never "no limit" (S4b.4).
limit_number_applies	A whole-number entry is its provider's limit.
untrusted_changes_nothing_guarded	An untrusted project changes no limit, prompt or credential (S4b.5).
trusted_project_applies	A trusted project's item applies.
project_entry_never_merges	A project MCP entry applies whole (S4b.6).
global_entry_kept	A global entry that the project does not name stays whole.

The laws of the saved default model are in inference.md ("S6 models.json and the saved default model") and in LAWS.bend section config.

Ties: the bridge test settings::bridge::the_rust_config_code_equals_the_bend_model compares transcripts with bend/bridge_config.bend byte for byte. It runs 360 generated scenarios: each writer over a missing, valid, invalid, unreadable and other-version file; setters after another writer changed the file; documents with good, wrong-typed and undeclared leaves; providerMaxInFlight values; projects under each trust; and global and project mcpServers entries.

Regression tests: add_refuses_a_settings_file_that_does_not_parse; a_setter_keeps_a_field_that_failed_to_load_and_a_concurrent_edit; another_version_is_refused_and_never_rewritten; set_over_an_unreadable_auth_file_is_refused_and_writes_nothing; a_bad_leaf_drops_only_itself_and_is_named; a_setting_a_cfg_file_shadows_says_so; a_project_mcp_entry_never_takes_global_credentials.

S5. The Director stack #

After each final answer, the agent loop asks a stack of Directors what to do. A Director is one layer of the stack. A layer has a kind and a budget: the loop steps that it can still ask for. The kinds are the goal, the autonomous run, a reminder, and a forced tool call.

1. The top layer decides first. Each layer gives one verdict:
   • Defer: the next layer down decides. The layer stays.
   • Again: the loop continues. This costs the layer 1 unit of its budget. A layer with no budget yields.
   • Yield: the loop stops and gives control back to the user.
   • Stack{l}: the layer puts l on top of itself, and the loop continues. This costs 1 unit of budget. A layer with no budget yields. A push needs room in the full stack: the layers above the layer (also the layers that deferred or left), the layer, and the layers below must be fewer than the cap. With no room, the loop fails.
   • Leave: the layer removes itself. The next layer down decides.
   • Abort: the loop stops with a failure.
2. When no layer decides, the loop gives control back to the user.
3. The loop of one run has a global budget of steps. Each continuation costs 1 step. When no step is left, a continuation yields.
4. The verdict of each kind comes from the session state:
   • Goal: an active goal mints a continuation (Again), unless its progress check stops it (8). A paused, budget-limited, complete, or failed goal yields. A cleared goal leaves. An empty reply never gets to the goal: the harness fails it as a model error (harness.md H4.7), and the goal fails with that error.
   • Autonomous: it defers while a goal drives continuations, so the goal keeps its priority. A disabled run leaves. Else its gates and limits continue the run (Again) or stop it (Yield).
   • Reminder: its text goes first in the continuation of the step. Then it leaves. When the step does not continue (no layer below continues, or no step is left), the reminder defers: it stays on the stack until a continuation comes. A reminder never makes its own continuation, so it waits for the goal or the autonomous run.
   • Forced tool call: each request forces its tool (stream.forceTool, S6) until a response calls the tool. Then the layer leaves at the next final answer. Each response to a forced request without the call is a miss. The miss after the tries retries fails the generation with ForcedToolError::NotCalled (S6.3), with the real number of requests. That miss removes the layer and appends a display row with the error (eukhe.director, not in the model context) in one commit, so the next request is not forced. When a run ends before a request forced the tool, the layer continues the run (Again) while it has budget. The continuation only names the forced call; the soft prompt of the forced request asks for the call. With no budget, the layer aborts with ForcedToolError::NotCalled and the same display row.
5. A step evaluates the layers from the top until one decides. The autonomous gates run before the commit of the step. The step commits the stack, the goal and autonomous changes, the goal context row, and its decision in one commit. A rerun of the same generation repeats the decision.
6. A run that has a new first input starts a new loop: the global budget (directors.maxSteps, default 200) comes back, the goal layer gets that budget, and the autonomous layer gets its remaining continuations (autonomous.maxContinuations minus the used ones). The goal and the autonomous run come on the stack (the goal above the autonomous run) when they drive continuations and have no layer. They go below the pushed layers (reminders and forced calls), so the pushed layers decide first. directors.stackCap (default 8) caps the pushed layers only. The stack keeps 2 more places, one for the goal and one for the autonomous run, so these always have room: a stack holds at most directors.stackCap + 2 layers, and each decision gets that cap. A push past the cap is refused with an error. With no layer, a final answer writes nothing.
7. Reminders and forced calls come on the stack from these entry points: the /remind <text> and /force <tool> [--tries <n>] session slash commands (the TUI sends them through the daemon), and the kernel host request directors.push (goal.remind(text) and goal.force_tool(tool, tries=1) in the Python REPL). A forced call gets 1 unit of budget and tries 1 when not given.
8. The stack is the conversation document eukhe.directors. It is rewindable: a fork or a branch move starts from the stack as of its fork entry, so a rewind removes the Directors added after that entry and brings back the ones removed. A resume reads the stored stack. The document is a node of the state tree (S1), under its conversation.

Model: bend/director.bend. Laws: LAWS.bend section (S5). Proofs: PROOF.bend section director. Every verdict is free: each layer of each step says what the adversary picks.

Law	Says
dir_stack_bounded	A decision never grows the stack past its cap (S5.1).
dir_loop_stack_bounded	So the loop never does, whatever its steps (S5.1).
dir_loop_ends	The loop ends (gives control back or fails) after at most n + 1 steps, with n its global budget, whatever every layer says (S5.3).
dir_end_is_final	An ended loop stays as it ended (S5.3).
dir_encode_sound	The stack in the tree is a sound tree (S5.8).
dir_resume_restores	A resume reads back the stack that the tree holds, exactly (S5.8).
dir_rewind_restores	A rewind of a sound tree to the tree of a stack restores that stack, exactly (S5.8).

Code: eukhe-core/src/durable/directors/stack.rs decide, Loop::tick, Layer, LayerKind, Verdict; directors/mod.rs DIRECTORS_DOC, DirectorState, DirectorLimits (bound), push_director, DIRECTOR_NOTICE_CUSTOM_TYPE; durable/goals/hooks.rs (the on_yield step: begin, judge, commit_step; the forced tool of before_request; the call or the miss of after_response, mark_forced_response); durable/goals/host.rs (directors.push); durable/session_commands.rs (/remind, /force); skills/goal/src/goal/__init__.py (remind, force_tool); eukhe-durable/src/harness/generation.rs (the before_request hooks may set the forced tool of a request, RequestMessages::force_tool); eukhe-core/src/settings directors.

Tie: the bridge test durable::directors::bridge::the_rust_director_stack_equals_the_bend_model runs decide, Loop::tick, and the persisted eukhe.directors value against bend/bridge_director.bend on 300 generated scenarios (stacks, verdict lists per step, caps, global budgets; the model's decide, tick, run, encode, and decode), and compares the transcripts byte for byte. The scenarios reach every rule of the model (a push with room, a push that fits only the layers below, a full stack, no budget, a leave, all layers defer, no step left, a tick after the end). Regression tests: durable::directors::tests (the goal layer until the goal completes, the global budget, a reminder, a reminder that waits on the stack for a continuation, a forced tool call, a forced call that is never made and a next run that is not forced, the goal on a full stack, the stack after a reopen and in a fork); durable::session_commands::tests (/remind and /force on the stack, a /force that fails once); durable::goals::tests. Not modelled: the map from the session state to the verdicts (S5.4), begin (S5.6), the reminder that defers when no continuation follows, and the kind data of a layer (the model keeps a number for the kind). Their tests tie them.

S5.8. A goal without progress stops #

8. At each continuation of an active goal, the progress check looks at the work of the session: the number of its distinct acts (a tool call with its result, by tool name, arguments, result text and error flag; or an accepted progress note). Call ids, timestamps, and the text and thinking around a call are no work. The check compares the work with the work at the last continuation of the same run and goal:

   • The work grew: the count of continuations in a row with no new work goes back to 0, and the goal continues.
   • The work did not grow: the count grows by 1. Under the cap, the goal continues, and its continuation tells the model how many continuations in a row did no new work and that the goal pauses at the cap. At the cap (directors.stallSteps, default 3; 0 takes the default), the goal pauses with the reason (No progress: <n> goal continuations in a row made no tool call with a new result), the run yields, and a display row (eukhe.director, not in the model context) tells the user why and how to go on.
   • The first continuation of a run, or of a new goal, starts the count: a new user input or a resume gives the goal the full cap again.

   Before this check, an active goal with no token budget got up to directors.maxSteps (200) continuations when the model only answered (for example "waiting for the build"), each a request with the full context. The default 3: the first continuation can be an answer that only states a plan, the second carries the note that asks for one concrete step, and the third shows that the model did not act on it. (An earlier strike counted replies with no text and no tool call. Such a reply is now a model error, H4.7, so that strike was removed. This check counts work, not replies.)

Model: bend/progress.bend (work, check, goal). Laws (LAWS.bend section progress): goal_stops_without_progress (continuations in a row whose acts the session did before, at least as many as the cap, stop the goal from any count) and goal_progress_continues (a continuation with an act the session never did before clears the count). Proofs: PROOF.bend section progress.

Rust: eukhe-core/src/durable/children/work.rs (WorkLedger), durable/goals/state.rs (stall_check), durable/goals/hooks.rs (goal_check, the work read in on_yield, the pause and its row in commit_step), durable/directors/mod.rs (DEFAULT_STALL_STEPS).

Tie: the bridge test durable::goals::hooks::bridge::the_rust_progress_check_equals_the_bend_model runs the ledger over real transcripts and goal_check against bend/bridge_progress.bend. Regression test: durable::goals::tests::a_goal_without_progress_pauses_at_the_stall_cap.