Skip to content

v0.3.0-alpha.22

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 25 Oct 16:11
· 51 commits to main since this release
487cf08

Added

  • http_resource_matches takes settleMs (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 as recovery_required in parkedAt, which later writes leave alone. A request or workflow definition that sets settleMs is not readable by 0.3.0-alpha.21 or earlier sharing the MELRA_HOME: upgrade every process sharing the home before setting it (left out, the 30 s default applies).
  • A workflow human_input node can declare "answeredBy": "operator"; left out, it is any, as before. In enforced mode such a node takes its answer only from melra workflow advance <workflow-id> --input <node-id>=<value>, and an answer for it sent with melra_workflow_advance is refused with workflow_input_in_band_refused:<node-id> before anything in the run moves (#419). Every human_input answer now records who gave it (answeredBy: cli: plus MELRA_APPROVER for an operator, otherwise the agent's principal), the channel (out_of_band only for an operator in an enforced process) and answeredAt on its workflow.node_changed event; the node itself keeps the shape older releases read. A definition that declares answeredBy is not readable by 0.3.0-alpha.21 or earlier: such a process sharing the MELRA_HOME cannot advance a run planned from it, and refuses to start while that run is planned, running, awaiting approval or recovery_required. Upgrade every process sharing the home together before declaring it.
  • ComputerRuntimeOptions.withheldEnvironment names environment variables, matched ignoring case, that the helpers computer actions start go without, beyond MELRA_PAYLOAD_KEY and MELRA_HTTP_TOKEN, which none ever gets. The server sets it to every variable a credential's source.env names; a library embedder can name more (#420).
  • Every policy decision, receipt (policyDecision.policyDigest) and certificate records policyDigest beside policyVersion: sha256: and the SHA-256 of the policy file's bytes, which sha256sum reproduces, or default:<version> when no file is loaded. policyVersion is 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 from MELRA_WORKSPACE, else a MELRA_POLICY file's workspaceRoot (relative to the file), else the current directory (a policy file's workspaceRoot can also only narrow it to a folder inside), and is in neither the digest nor the receipt. --mode, MELRA_MODE and unsafe-local are recorded on their own. So a digest and the MELRA version that ran it name a policy, except that a server melra launch starts leaves node, npm, npx and pnpm out of the defaults under the same digest. melra_capabilities (policy.digest), melra policy test, melra status (policyDigest), melra doctor and the console show it. INSTALLATION.md no longer says a policyVersion pin is refused whenever the policy changes: it follows the label.
  • melra doctor reports (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 point MELRA_POLICY at a file another account owns, never to make MELRA_HOME read-only, which MELRA must write. In developer mode, where a default setup keeps its policy in MELRA_HOME, it passes and names the paths, so melra setup gives no MELRA_POLICY advice 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 same melra by absolute path, with MELRA_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/--continue and -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 with launch_argument_refused. --dry-run prints the claude command and its MCP config as JSON instead of running them, and CLAUDE_BIN or --claude-bin names 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 from PATH'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 stops launch before claude starts. A claude started any other way is unchanged.
  • A server melra launch starts has MELRA_LAUNCHED=1, which leaves node, npm, npx and pnpm out of the default allowedCommands, since each runs any program with the OS user's rights. A policy file's own allowedCommands is kept as written, and the launch summary warns when it lists one of them, as a policy.json that melra init or melra setup wrote 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 enforced is how a person decides each one.

Changed

  • Reconciliation settles a parked mutation failed only on a miss after its settle window: 30 s for an http_resource_matches predicate that does not set settleMs, none for any other predicate. Inside the window a 404, a 410 or a value that does not match yet leaves the task recovery_required with reconciliation_settling and no receipt. The recovery pass, at startup and in the 30 s sweep, asks such a task again, as melra_execute on it does, and the first miss asked after the window settles it. Set settleMs: 0 for a provider whose reads always show its latest writes.
  • Breaking: melra workflow advance --input now records MELRA_APPROVER as who answered, and fails on a value it does not accept before answering anything (#419). Without --input it does not read the variable, as before.
  • Breaking: createSystemComputerAdapter in @melra/computer-runtime requires the environment variables its helpers start without, beyond MELRA_PAYLOAD_KEY and MELRA_HTTP_TOKEN; pass [] for none. An adapter passed as ComputerRuntimeOptions.adapter withholds only what it was built with, not the runtime's withheldEnvironment.
  • Breaking: Receipts, workflow events, approval decisions, capability grant draws and idempotency commits are append-only: SQLite triggers (migration 7) refuse, with record_append_only, an UPDATE or DELETE of any of them and an INSERT OR REPLACE that 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). In certified_tasks and the three written with INSERT 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 new certificate_history table, append-only like the rest, beside certified_tasks, which records each task that has had one. This catches bugs, stray scripts and naive edits. Anyone who can write melra.sqlite can 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.json and settings.local.json, .vscode/settings.json, tasks.json and mcp.json, .codex/config.toml with the Codex directory's other config files, every file in .codex/rules and .continue/mcpServers, .gemini/settings.json, .cursor/mcp.json, and every file melra setup writes 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). A write, mkdir, delete or either end of a move naming one is refused in every mode with path_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 a delete or move of 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 .claude or .vscode, is unchanged.
  • In enforced mode the server's instructions for a model waiting on approval_awaiting_operator now say that melra_task_status keeps showing awaiting_approval until the task runs, to call melra_execute again 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.mode and LocalPolicy.mode no longer say enforced mode makes MELRA the only path, or that a receipt's mode tells "the only door" from one of several: enforced mode assumes the operator has taken the alternatives away, and mode is the deployment the operator declared, not evidence that no other path existed. The root and @melra/server package descriptions and the systemd unit call MELRA an autonomy kernel for the effects routed through it, and the Claude Code setup hint names melra 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 failed with a FAILED certificate 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_input node schema's comments no longer say a later node can read or branch on an answer (#419): none can, and any answer within maxLength and choices completes the node and releases what depends on it, so a "no" stops nothing. The schema, melra_workflow_advance and 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, and tesseract or a configured OCR program) no longer inherit MELRA_PAYLOAD_KEY, MELRA_HTTP_TOKEN or 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's quote spell 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 the Basic scheme, as the base64 of a printable user: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.