Repository navigation
v0.3.0-alpha.22
Pre-release
Pre-release
·
51 commits
to main
since this release
Added
http_resource_matchestakessettleMs(0 to 3,600,000), read by reconciliation only: how long after a task first parked a miss is a write the provider may not show yet rather than a no. A task whose outcome is unknown records when it first parked asrecovery_requiredinparkedAt, which later writes leave alone. A request or workflow definition that setssettleMsis not readable by0.3.0-alpha.21or earlier sharing theMELRA_HOME: upgrade every process sharing the home before setting it (left out, the 30 s default applies).- A workflow
human_inputnode can declare"answeredBy": "operator"; left out, it isany, as before. In enforced mode such a node takes its answer only frommelra workflow advance <workflow-id> --input <node-id>=<value>, and an answer for it sent withmelra_workflow_advanceis refused withworkflow_input_in_band_refused:<node-id>before anything in the run moves (#419). Everyhuman_inputanswer now records who gave it (answeredBy:cli:plusMELRA_APPROVERfor an operator, otherwise the agent's principal), thechannel(out_of_bandonly for an operator in an enforced process) andansweredAton itsworkflow.node_changedevent; the node itself keeps the shape older releases read. A definition that declaresansweredByis not readable by0.3.0-alpha.21or earlier: such a process sharing theMELRA_HOMEcannot advance a run planned from it, and refuses to start while that run is planned, running, awaiting approval orrecovery_required. Upgrade every process sharing the home together before declaring it. ComputerRuntimeOptions.withheldEnvironmentnames environment variables, matched ignoring case, that the helpers computer actions start go without, beyondMELRA_PAYLOAD_KEYandMELRA_HTTP_TOKEN, which none ever gets. The server sets it to every variable a credential'ssource.envnames; a library embedder can name more (#420).- Every policy decision, receipt (
policyDecision.policyDigest) and certificate recordspolicyDigestbesidepolicyVersion:sha256:and the SHA-256 of the policy file's bytes, whichsha256sumreproduces, ordefault:<version>when no file is loaded.policyVersionis a label that defaults to"1", so an edit that kept it left no trace; the digest changes with any edit (#425). It covers the file's bytes only. Keys the file leaves out take the running version's defaults. The workspace root comes fromMELRA_WORKSPACE, else aMELRA_POLICYfile'sworkspaceRoot(relative to the file), else the current directory (a policy file'sworkspaceRootcan also only narrow it to a folder inside), and is in neither the digest nor the receipt.--mode,MELRA_MODEand unsafe-local are recorded on their own. So a digest and the MELRA version that ran it name a policy, except that a servermelra launchstarts leavesnode,npm,npxandpnpmout of the defaults under the same digest.melra_capabilities(policy.digest),melra policy test,melra status(policyDigest),melra doctorand the console show it. INSTALLATION.md no longer says apolicyVersionpin is refused whenever the policy changes: it follows the label. melra doctorreports (policy-write) when the user MELRA runs as can change the policy: when that user can write, or owns, the file or any folder above it, along the path as given and the one its links resolve to. With no policy file it checks where the next start would load one from. In enforced mode that is a warning, and the advice is to pointMELRA_POLICYat a file another account owns, never to makeMELRA_HOMEread-only, which MELRA must write. In developer mode, where a default setup keeps its policy inMELRA_HOME, it passes and names the paths, somelra setupgives noMELRA_POLICYadvice there. It is not checked on Windows.melra launch claude-code [-- <claude arguments>]starts Claude Code 2.1.296 or later with Read, Glob and Grep as its only built-in tools, melra as its only MCP server and its user, project and local settings files ignored (--tools,--strict-mcp-config,--mcp-config,--restricted), so the only tools it has that change anything are MELRA's. The MCP entry runs the samemelraby absolute path, withMELRA_HARNESS_TOOLS=1, on the workspace, policy and mode every other command reads, developer by default. Before claude starts it prints what the session can and cannot do and how a change is approved, and it exits with claude's exit code. After--it passes on only prompt arguments,-p/--print,--model,--output-format,--verbose,-c/--continueand-r/--resume; any other flag, and a first prompt argument of one lowercase word, which claude could read as one of its subcommands, is refused withlaunch_argument_refused.--dry-runprints the claude command and its MCP config as JSON instead of running them, andCLAUDE_BINor--claude-binnames the claude to run, so a test can use a stand-in. That claude is run by absolute path: a named path from the current directory, a bare name only fromPATH's absolute directories, never from the directory claude starts in. The server it configures is opened and closed first, so one that would refuse to start stopslaunchbefore claude starts. Aclaudestarted any other way is unchanged.- A server
melra launchstarts hasMELRA_LAUNCHED=1, which leavesnode,npm,npxandpnpmout of the defaultallowedCommands, since each runs any program with the OS user's rights. A policy file's ownallowedCommandsis kept as written, and the launch summary warns when it lists one of them, as apolicy.jsonthatmelra initormelra setupwrote does. Every other setup keeps the defaults it had. This narrows the list without making the rest harmless: any allowed command run as an approved change has the OS user's rights, and in developer mode the agent approves its own changes, so--mode enforcedis how a person decides each one.
Changed
- Reconciliation settles a parked mutation
failedonly on a miss after its settle window: 30 s for anhttp_resource_matchespredicate that does not setsettleMs, none for any other predicate. Inside the window a404, a410or a value that does not match yet leaves the taskrecovery_requiredwithreconciliation_settlingand no receipt. The recovery pass, at startup and in the 30 s sweep, asks such a task again, asmelra_executeon it does, and the first miss asked after the window settles it. SetsettleMs: 0for a provider whose reads always show its latest writes. - Breaking:
melra workflow advance --inputnow recordsMELRA_APPROVERas who answered, and fails on a value it does not accept before answering anything (#419). Without--inputit does not read the variable, as before. - Breaking:
createSystemComputerAdapterin@melra/computer-runtimerequires the environment variables its helpers start without, beyondMELRA_PAYLOAD_KEYandMELRA_HTTP_TOKEN; pass[]for none. An adapter passed asComputerRuntimeOptions.adapterwithholds only what it was built with, not the runtime'swithheldEnvironment. - Breaking: Receipts, workflow events, approval decisions, capability grant draws and idempotency commits are append-only: SQLite triggers (migration 7) refuse, with
record_append_only, anUPDATEorDELETEof any of them and anINSERT OR REPLACEthat would take a stored row's place on its rowid or key, from any process or script, an older MELRA sharing the home included (no version ever made one). Incertified_tasksand the three written withINSERT OR IGNORE, an insert under a stored key is ignored instead, as a repeat already was. A certificate is never removed and changes only in place on its own task, the way every version replaces one when a task is judged or settled: a write that would take another certificate's place, insert a second one for a task or move one to another task is refused. Each certificate an update replaces is kept in a newcertificate_historytable, append-only like the rest, besidecertified_tasks, which records each task that has had one. This catches bugs, stray scripts and naive edits. Anyone who can writemelra.sqlitecan still add rows, update a certificate in place (the old one is kept) or drop the triggers, so it is not tamper-evidence, as ARCHITECTURE.md and THREAT_MODEL.md now say. - Breaking: The file capability refuses to change the settings files a coding agent's harness loads its permissions, hooks, tasks or MCP servers from when a session starts (
.mcp.json,.claude/settings.jsonandsettings.local.json,.vscode/settings.json,tasks.jsonandmcp.json,.codex/config.tomlwith the Codex directory's other config files, every file in.codex/rulesand.continue/mcpServers,.gemini/settings.json,.cursor/mcp.json, and every filemelra setupwrites for a client at its default location; a client home moved by its own variable is recognised only while it keeps the default folder name). Awrite,mkdir,deleteor either end of amovenaming one is refused in every mode withpath_harness_config, which names the path: edit the file yourself, outside the agent. They are known by name, at any depth, in any case and through a link, so a file of the same name in an unrelated folder is refused too, and so is adeleteormoveof a folder named like one that holds them (.claude,.vscode,.codex, a client's own folder), even an empty one; not the project folder holding.mcp.json. Reading them, and the rest of.claudeor.vscode, is unchanged. - In enforced mode the server's instructions for a model waiting on
approval_awaiting_operatornow say thatmelra_task_statuskeeps showingawaiting_approvaluntil the task runs, to callmelra_executeagain later, that only the operator's decision lets the task run, and not to reach the same effect through another tool. - ARCHITECTURE.md, INSTALLATION.md and the type docs of
ActionReceipt.modeandLocalPolicy.modeno longer say enforced mode makes MELRA the only path, or that a receipt'smodetells "the only door" from one of several: enforced mode assumes the operator has taken the alternatives away, andmodeis the deployment the operator declared, not evidence that no other path existed. The root and@melra/serverpackage descriptions and the systemd unit call MELRA an autonomy kernel for the effects routed through it, and the Claude Code setup hint namesmelra launch claude-code.
Fixed
- A mutation whose reply was lost, reconciled straight away (on the caller's retry, at startup recovery or in the sweep) against a provider that did not show the write yet, was settled
failedwith aFAILEDcertificate though the effect ran, which invited running it again; a workflow run failed and unwound past it. It now stays parked until its settle window has passed (#418). - The
human_inputnode schema's comments no longer say a later node can read or branch on an answer (#419): none can, and any answer withinmaxLengthandchoicescompletes the node and releases what depends on it, so a "no" stops nothing. The schema,melra_workflow_advanceand ARCHITECTURE.md now say so; gate a step on an approval instead. - The programs computer actions start (
osascript,screencapture,ioreg,xdotool,gnome-screenshot,scrot, PowerShell, andtesseractor a configured OCR program) no longer inheritMELRA_PAYLOAD_KEY,MELRA_HTTP_TOKENor the variables credentials are read from (#420). The rest of the server's environment still reaches them. - README.md, ARCHITECTURE.md and the README's pipeline diagram no longer call receipts hash-linked, since nothing links them by hash. They describe what exists: append-only receipts and a certificate per task that carries its own digest.
Security
- In enforced mode a workflow question meant for an operator can no longer be answered by the agent, and every answer to a workflow question records who gave it and through which channel.
- Computer-use helper programs no longer receive the payload key, the HTTP token or credential values from the server's environment.
- A brokered credential of 8 characters or more that the far end echoes back in a common fixed encoding (base64, base64url, hex, or percent-encoded the way
encodeURIComponent, RFC 3986 (Go, PHP) or Python'squotespell it, with upper- or lower-case escapes) is now masked in the result like an unchanged copy. Inside a longer base64 string, such as an encoded header value or HTTP Basic pair, all of it goes but the character at either edge it shares with its neighbours. One configured for theBasicscheme, as the base64 of a printableuser:password, is also masked as the decoded pair, as its password and as its user name, each when it is 8 characters or more: a long user name is masked too, not only the password. A body cut at the size cap is masked to the length of the longest such form. A shorter credential is still masked only as sent. - MELRA's file capability no longer writes, creates, removes or moves the settings files listed under Changed, which a coding agent's harness loads at the next session start, or a folder named like the one they sit in, so an agent cannot use it to rewrite them for its next session. Deleting or moving a folder further up, such as a project folder, still takes them along. The refusal is a fixed check, not policy, so it holds in every mode, unsafe-local included. It covers those files only: other files a harness loads, such as agent, skill and command definitions, are not refused, and an approved terminal command can still write any of them.