Release Notes¶

What changed in the surface you use, and what to do about it.

Binaries, checksums and the per-tag changelog are published as GitHub Releases in engineering-runtime-releases. This page is the technical companion to those tags: which parts of the runtime you interact with moved, and which of your files need attention.

Just looking for the download?

Releases on the Engineering Runtime site, or straight to the GitHub Releases page. Then follow Installation.

v0.9.8¶

Enterprise-managed commands now bind their audit evidence to the verified policy digest and governance generation revision installed by registration or Portal sync. This fixes v0.9.7, where enrollment and signed synchronization succeeded but the first governed command refused while constructing its audit policy projection.

On upgrade, no configuration, policy or capability document changes are required. Enterprise users should upgrade Runtime agents from v0.9.7 to v0.9.8 before exercising managed operations. Community/local execution is unchanged.

v0.9.7¶

The optional Portal client is being narrowed to three authenticated Enterprise operations: explicit registration, at-most-once-per-process heartbeat, and manual signed policy/config sync. Community/local mode remains the default and disabled portal sync performs no network or audit work.

First registration binds one show-once RUNTIME_PORTAL_API_KEY to one stable Runtime installation, pins the Control Plane organization and Ed25519 public signing key, verifies the first atomic governance generation, and only then commits sticky Enterprise-managed state. Later local config/policy sources cannot override it; outage uses last-known-good and invalid state fails closed. Replacement keys recover the same Runtime identity without replacing signing trust.

Portal audit upload and the Runtime repository's reverse app-api contract vendoring are removed. Local audit remains unchanged; external audit delivery will be a separately released OpenTelemetry integration. /api/v1 is now the only Portal prefix.

v0.9.6¶

Capability and command audit evidence is now attributable, correlated and safe under parallel execution.

Direct operations carry a unique invocation ID. Capability runs add durable start/completion frames and repeat the exact capability source, SHA-256 byte digest, run ID, execute/preview mode and ordered step position. A successful step followed by a denied step remains visible as two distinct outcomes and closes the overall capability run as failed.

Audit identity separates the caller class (human, ci or ai), optional self-asserted actor label, observed OS executor and optional session ID. CI, agents and pods can set RUNTIME_CONSUMER, RUNTIME_ACTOR_NAME and RUNTIME_SESSION_ID; these labels support correlation and are never accepted as authorization identity.

RUNTIME_HOME is now the canonical Runtime Home variable. The pre-v1 ENGINEERING_RUNTIME_HOME and ENGINEERING_RUNTIME_CONSUMER aliases remain temporarily accepted for migration. Equal dual values work; conflicting values refuse. Update active automation to the canonical names.

Cross-process locking serializes durable evidence appends. Broken or torn chains refuse new governed work, JSON audit output includes integrity state, and recovery is explicit after confirming no Runtime process still uses the Home. The compiled environment-variable reference is machine-checked and installed version-exact for operators and agents.

On upgrade, no provider operation, transport, configuration/policy schema or capability grammar changes. Capabilities remain version: v1; no document migration is required. Existing enterprise audit ingestion remains compatible with engineeringruntime.audit/v1:runtime-execution.

v0.9.5¶

Repository-list output is now useful to humans and stable for automation.

runtime github repo list now renders repository, visibility, update time and description columns followed by a repository count. Default text no longer serializes the complete REST response.

runtime --output json github repo list retains the complete typed GitHub API objects exactly once under .data, so it can be piped directly to tools such as jq. The accidental duplicate .output field has been removed. If an automation read .output, change that selector to .data.

Identity output now reports only the provider, authentication mode and whether a subject resolved. Text and JSON no longer expose the account name or a masked token fingerprint.

On upgrade, no provider operation, transport, configuration/policy schema or capability grammar changes. Capabilities remain version: v1; no configuration migration is required.

v0.9.4¶

Native CLI parity and governed bulk file editing are now released together.

The Command Engine admits the exact semantic mode gh repo list. When no Runtime token is configured, it delegates to the GitHub CLI's existing native authentication, host and account context; when RUNTIME_GITHUB_TOKEN is configured, the Auth Engine validates and brokers that credential. Runtime never runs gh auth login. Text and raw modes preserve familiar CLI output, while JSON mode separates typed data, stdout/stderr, exit code and media type. Other raw gh shapes remain context-unsupported until their semantic mode is registered.

The File Engine now performs bounded selective edits across text, YAML, JSON, Terraform, CODEOWNERS, Dockerfiles and Markdown. It supports one file or a recursive filtered directory set, expected-count preconditions, whole-batch preflight, --dry-run, human tables/diffs, typed JSON, pre-image race checks, atomic per-file replacement, rollback states and content-free per-file audit digests. runtime capability execute <path> --dry-run validates every step's preview contract before step one. No plan file or plan digest is required, and File Engine never performs Git or external validation implicitly.

On upgrade, existing policy schema remains v3. The new file_policy.max_edit_* values are optional and may only narrow compiled limits. Existing direct file commands behave as before. A policy must grant read roots for preview and both read and write roots for applying structured edits.

v0.9.3¶

The agent contract no longer contradicts itself. RUNTIME-AGENT.md — the file Runtime writes into your Home, and the one it tells an assistant outranks anything it already knows — carried two authoring loops about a hundred lines apart. They disagreed on three things: whether to write a capability through runtime files write or with ordinary file tools, whether file_policy.write_roots must grant the write, and whether RUNTIME_CAPABILITIES_DIR is authoritative.

The first of each pair was the pre-0.9.2 model, left behind when the one-directory change shipped. The last was the damaging one: the contract said never to treat that directory as authoritative, while the binary beside it reports Authoring source: capabilities-dir and authors there by default. An assistant reading top to bottom met the stale instruction first.

There is now one authoring loop, and it says more than either did:

check runtime version and stop if Runtime is not installed, rather than guessing
treat runtime --output json capability authoring-context as the source of truth for every path — so a Home moved with RUNTIME_HOME resolves correctly instead of being reconstructed from ~
never invent an organisation, repository, namespace or credential
treat a policy denial as a design signal, not something to work around
execute read-only work; wait for approval before changing an external system
report a shared Runtime or provider gap separately instead of hiding it behind a workaround in the capability

It also states the trap that costs the most time: validation passing is not evidence a capability works, and neither is execution passing if nobody reads the output — an empty result can be a successful call against a target that has nothing to report.

Nothing else changed. No new command, no schema change, no difference at execution time. Config is still schema v2 and policy still schema v3.

On upgrade, Runtime rewrites RUNTIME-AGENT.md in your Home. Your own capabilities, config.yaml and policy document are untouched. If you had copied the old contract somewhere, replace it — the two disagreed.

v0.9.2¶

Writing your first capability no longer starts with a configuration file. On v0.9.1 a fresh install could not author at all: the target had to be named by capabilities.authoring_source, which had to match an entry in capabilities.sources — and that list ships empty. capability authoring-context reported authoring_ready: false even with RUNTIME_CAPABILITIES_DIR pointing at a directory full of capabilities.

One directory is now the whole setup:

git clone https://github.com/engineeringruntime/engineering-runtime-capabilities
export RUNTIME_CAPABILITIES_DIR=$PWD/engineering-runtime-capabilities/capabilities
runtime capability authoring-context

That directory is read from and written to, and capability list reports it as capabilities-dir — an authoritative source, not the "non-authoritative cache" a directory you deliberately chose was previously called. Only the unset fallback inside Runtime Home is still a cache.

Authoring no longer depends on file_policy.write_roots. Those roots govern what the File Engine may touch on your behalf; writing a capability is you, or your assistant, editing a file with your own tools. A fleet that narrows its write roots to one tree keeps the ability to author, and the File Engine still refuses a files write outside them.

Nothing to change on upgrade. capabilities.authoring_source still parses and still wins when set, so an existing configuration behaves exactly as it did. It is simply no longer required: with several directories configured, Runtime asks which is yours instead of guessing. Config and policy schema versions are unchanged.

The 47 capability samples that were compiled into the binary are gone. Nothing read them, they were never installed into your Home, and every one lives in the public store the clone above fetches.

v0.9.1¶

Two dead execution paths, repaired. No new features; both fixes restore behaviour that was already documented.

Every GitHub operation whose transport is the gh CLI — pr list, pr view, pr create, issue create, workflow list, workflow run, run list, run view — was refused with "gh reached the Command Engine with no pinned artifact". The provider path built its request without the pinned executable the Command Engine requires. Sixteen published capabilities depended on that transport and failed at execution while still validating cleanly.

Tools that delegate authentication to a helper binary could not authenticate: docker push to a registry using a credential helper failed inside Runtime while the identical push succeeded outside it. New command_policy.admitted_helpers admits named helper executables — absolute paths, scoped to one parent binary, exposing only the named files rather than their directory, and empty by default.

Policy schema is now v3. The 2→3 migration is behaviour-preserving and rewrites nothing, so an existing v2 document is read unchanged and needs no action.

What to do: upgrade normally. If you use docker push, git over HTTPS, or any tool with a credential helper, see the policy page — admitting a helper is now possible and is still opt-in.

Neither fix loosened a boundary. The Command Engine still refuses an unpinned request, and every gcloud change is still denied at selector_bound strength; both are now asserted by the install proof, which executes one real operation per transport.

v0.9.0¶

Reliable capability authoring from one ask. Runtime now makes the two facts an author must not guess directly inspectable: which authoritative worktree is selected for writes, and whether a capability with representative inputs would pass effective policy before its first side effect.

Config schema v2 adds optional capabilities.authoring_source. It must name exactly one configured source with an absolute directory. Runtime never chooses the first source, never falls back to the Home/RUNTIME_CAPABILITIES_DIR compatibility cache, and never fetches, creates, commits or publishes the worktree. Existing config v1 remains readable with unchanged behaviour.

New commands:

runtime --output json capability authoring-context
runtime capability plan <path|name> --input key=value

authoring-context reports the version-matched installed contracts and digests, config/policy provenance, exact selected source, provider surface, allowed binaries and File Engine write readiness. Source selection grants no write permission; policy must independently grant the directory.

capability plan validates, substitutes inputs and applies context, File Engine grants, the compiled safety floor and declarative policy to every step. It reports every denial and exits non-zero for denial or missing required inputs, while performing no authentication, command/network execution, mutation or audit write. File-write payloads and GitHub content are omitted. Identity allow-list evaluation is deferred until separately authorized execution resolves an identity.

What to do: existing execution-only setups need no config change. For managed authoring, migrate or create config v2, select one named source, grant its absolute directory narrowly under file_policy.write_roots, then follow authoring-context → write through runtime files → validate → plan → review. A successful plan is evidence for review, not permission to publish or execute.

v0.8.0¶

The supported recovery release. v0.8.0 restores the Runtime-first architecture shipped in v0.6.1 after the v0.7.0 Control Plane governance preview was withdrawn. The v0.7.0 artifacts remain available only as a historical implementation reference; do not use them for production.

This release removes the 0.7-only signed composite bundle, centrally selected capability-source activation, persistent Runtime rollout identity and Control-Plane-requested automatic sync path. Runtime continues to own local policy evaluation and execution, and the optional explicit runtime portal sync path remains the earlier local-policy delivery contract. The v0.6.1 config v1, policy v2, schema, audit-evidence and Runtime Home contracts remain in force.

What to do: users upgrading from v0.6.1 or earlier can upgrade normally and run runtime config validate. If you evaluated v0.7.0, install v0.8.0, keep a backup of any 0.7-only enterprise/rollout state for reference, and validate the effective config and policy before executing governed work. v0.8.0 does not consume the withdrawn 0.7 bundle contract.

v0.7.0 — withdrawn reference¶

v0.7.0 was the 07b Control Plane bundle preview. Its release and source tag are retained so the experiment can be inspected, but it is superseded by v0.8.0, is not the supported release line, and should not be deployed to production.

v0.6.1¶

Closes the 07a functional release gate. Runtime now ships explicit config v1 and policy v2 JSON Schemas in both Runtime Home and release archives. Policy v2 removes the retired top-level enabled key; legacy v1 with the key absent or true migrates in memory without changing the file, while enabled: false blocks for an operator decision.

This patch also reserves durable execution evidence before portal sync performs either its network request or local policy write, and rejects a newer signed enterprise generation that tries to lower required audit delivery back to local. Bootstrap wording now matches the executable: every Runtime command prepares Runtime Home automatically; runtime bootstrap is the explicit report, not a prerequisite.

What to do: upgrade normally, run runtime config validate, and inspect <Runtime Home>/specs/schema-contract.json. If a legacy policy contains top-level enabled: false, remove that key deliberately and validate again.

v0.6.0¶

The release with breaking changes in it. Three things that used to work will stop, each deliberately, and each with a one-line fix.

Customer-facing surface: github gains one operation — file put, which creates or updates a file through the Contents API and is how a capability is published without a raw API call (github 20 · files 5 — verify with runtime config validate). What else changed is what a governed operation is allowed to reach.

Change	Why	What to do
The File Engine is default-deny. A policy document with no `file_policy` block grants no file access at all, and read and write are separate authorities	`files read ~/.ssh/id_rsa` used to return a private key to whatever asked — which in an AI-driven workflow means into a context window	Add a `file_policy` block naming the roots you actually work in. `runtime config validate` reports what your document grants
A tool no longer inherits your environment. A variable exported in your shell reaches a `command run` tool only if the runtime carries a contract naming it for that tool and your policy permits it	An approved binary received every ambient secret the shell held — unrelated tokens, session credentials, and the loader variables that turn any binary into a launcher for unreviewed code	Add the name to `command_policy.rules.<binary>.environment`. See what a tool receives
`gh`, `aws` and `az` are refused through `command run`	Each resolves its target from ambient state Runtime cannot observe, so it could not say which repository, account or subscription an operation would reach	Use `runtime github ...` for GitHub, which takes the repository as an argument. For AWS and Azure there is no adapter yet; run them outside Runtime until there is

Two more refusals you may meet, both compiled into the binary and not removable by any policy:

Credential export — an operation whose output is a secret (gcloud auth print-access-token, kubectl get secret, vault kv get, sops -d). Using a credential is untouched; kubectl apply is fine.
Tool reconfiguration — an operation that changes the tool rather than your systems (gcloud config set, gcloud components install, kubectl config use-context, oc login, git config --global). Reading the same configuration still works. Do these in your own shell, deliberately.

Also in this release: a command run process starts in a private empty working directory, so a command that depended on the directory you ran runtime from (a git repository, a Terraform project) will not see it; results and error text pass a size and redaction boundary before they reach output, a capability step or the audit log; the audit record carries your account as a keyed digest rather than in the clear; and runtime context observes where your tools point rather than keeping a context.yaml of its own — a leftover one now blocks, and runtime context retire says what each value maps to.

None of this is a sandbox, and the documentation does not claim it is. An approved tool still handles its own credentials and makes its own network calls. See command run for exactly what is and is not bounded.

What to do: install or upgrade with Installation / Upgrading, then run runtime config validate before your first real command — it reports the policy in force, what it grants, and anything left in your Runtime Home that no longer governs.

v0.5.4¶

Published: GitHub Release v0.5.4.

Customer-facing surface: same provider operation counts as 0.5.3 (github 19 · files 5 — verify with runtime config validate). No new CLI verbs in this tag.

What to do: install or upgrade with Installation / Upgrading. If you pin CI versions, bump the pin to v0.5.4 when you want this binary.

Internal packaging and Control Plane contract-vendoring work landed around this release; it does not change day-to-day runtime github / runtime files usage.

v0.5.3¶

Published: GitHub Release v0.5.3.

Historical Portal topology

The API prefixes and api.engineeringruntime.com backend mapping below describe v0.5.3 only. The v0.9.7 candidate retires /api/public; api. is a static reference and an Enterprise deployment supplies its own Portal base URL.

Customer-facing surface (relative to 0.5.2):

Change	What to do
Optional Control Plane client matured (`runtime portal status` / `sync`, audited sync, correct path when `RUNTIME_POLICY_FILE` is set)	Read Control Plane (Portal) if you uplink; otherwise ignore — still off by default
Dual API prefixes: `portal.path_prefix` `/api/public` (demo) or `/api/v1` (enterprise)	Set the prefix to match the UI you watch (demo vs app)
Demo hostname is `demo.engineeringruntime.com` (not `portal.`)	Update bookmarks and any old `portal.` URLs
Recipes point at `api.engineeringruntime.com` as `portal.base_url`	Do not point `base_url` at a UI host

Provider counts unchanged vs prior 0.5.x (github 19 · files 5).

The binary is always the authority¶

Operational examples on this site are verified against Runtime 0.9.1 unless a page states otherwise. This is the site's single verification claim: pages do not repeat the version, and updating this line is an assertion that the examples were re-run — not a version bump. If a release ships without that work, this sentence should name the version they were verified against and say so. Install examples install latest by default. When a page and your installed binary disagree, your binary wins — check it directly:

runtime version
runtime config validate
runtime github --help
runtime files --help

runtime <provider> --help is generated from the provider's real operation surface, so it can never drift from what you have installed.

After every upgrade¶

Three checks, about ten seconds, that catch the overwhelming majority of post-upgrade surprises:

# 1. Does the active configuration still resolve?
runtime config validate

# 2. How does the effective policy differ from this release's default?
runtime config diff policy

# 3. Do capabilities in the selected source still validate?
find /path/to/pinned-capability-source -name '*.md' -print0 |
  while IFS= read -r -d '' f; do
    runtime capability validate "$f" >/dev/null || echo "FAILED: $f"
  done

The policy comparison matters more than it looks — see the trap below.

Capability definitions do not ship with 0.6.0¶

A fresh Home has an empty capability inventory, and that is success. Runtime fetches nothing and Bootstrap writes no executable workflow definitions. Repositories or catalogs own capabilities; select an exact checkout through capabilities.sources, or execute a reviewed file by path.

Homes upgraded from v0.5.x may still contain the examples that those releases seeded. Runtime leaves them untouched and reports that location as a non-authoritative compatibility cache. Move definitions you own to an external source deliberately; do not treat the leftover copy as the repository.

What an upgrade touches¶

Path	On upgrade
`specs/`, `commands/`	Replaced to match the new binary; files it no longer ships are deleted
`version`	Updated
`config.yaml`, `policy-config.yaml`	Never touched (and never created — the compiled defaults apply with no document)
capabilities directory	Untouched. No definitions are added; a fresh directory is empty and non-authoritative
`logs/`, `cache/`	Untouched

Full mechanics: Upgrading.

New defaults never reach an existing install

An explicitly selected policy-config.yaml is yours, so a release that adds allowed_binaries entries or new deny rules does not replace it. This has bitten real installs: a laptop sat at 6 allowed binaries while the release compiled 21, and runtime command run helm was denied for no apparent reason.

This is a deliberate trade — never clobbering your policy is worth more than auto-delivering defaults — use runtime config diff policy to see the exact allowed_binaries difference. Merge by hand; replacing the file wholesale discards your own rules.

Where to look when something changed¶

You noticed	Read
An operation no longer validates	`runtime capability`, then `runtime <provider> --help`
A command is suddenly denied	Policy and the trap above
A config key moved or was renamed	`config.yaml`, Environment Variables
A capability step key is now rejected	Capability Authoring
Something structural changed between versions	Migration Guides
A brand-new provider appeared	Providers
A `portal:` block appeared in `config.yaml`, or `runtime portal` in `--help`	Control Plane (Portal) — optional, off by default, safe to ignore

Migration Guides documents breaking changes in detail — the retired allowed_commands block, the move from a central command registry to the Provider layer, and stricter capability parsing.

Downgrading¶

Supported and symmetric: specs/ and commands/ refresh back down to what the older binary ships, because the refresh triggers on any version difference. Your user-owned files are untouched in that direction too.

The one thing to re-check is capabilities — one written against an operation that exists only in the newer binary will fail validation after a downgrade. That is the intended behaviour, caught before execution rather than during it.

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.