Skip to content

Release Notes

Current stable: v0.14.0, released November 17, 2026. See Installation for the shell installer, Homebrew and manual archives, and Upgrading for migration guidance.

v0.14.0 — GitHub execution and audit hardening

v0.14.0 was published on November 17, 2026 for macOS, Linux and Windows on amd64 and arm64. Config v2, policy v3 and version: v1 capabilities remain unchanged. See Upgrading and the v0.14.0 operations guide.

  • Curated GitHub observation reads no longer treat 404 as proof of absence. Dependent writes stop when an observation is not authoritative.
  • Native command classification covers additional flag, alias and endpoint forms without expanding raw gh admission beyond gh repo list.
  • Audit verification separates retained-chain consistency from completeness against an anchor or independently held checkpoint. Malformed security configuration can retain explicit collector-required debt; repairing the configuration does not erase that obligation.
  • Recognized private-key envelopes receive broader bounded redaction, truncated raw output is labelled, and operation help is available before admission.

Known limits: full first-run convergence and missing-resource repair remain unsupported. End-to-end repository-onboarding verification and manual operator acceptance observations were accepted as incomplete for this release. These are not PASS results. Outbound MCP, expanded raw gh modes and live GKE are excluded. See the operations guide for recovery, credential-store and redaction limits.

v0.13.0 — destructive effects refused, and every refusal says why

v0.13.0 was published on October 21, 2026 from qualified source bc0099a, for macOS, Linux and Windows on amd64 and arm64. It keeps config v2, policy v3 and version: v1 capabilities. See Upgrading.

What you will notice:

  • Destructive effects are refused on every route. Repository deletion, remote ref deletion, forced pushes and other history rewriting, and removal of branch protection and rulesets are refused by the compiled safety profile (now v4) on REST, GraphQL, command run git, raw gh and capability paths, even under a policy that allows them. See command run and the GitHub provider.
  • Refusals are truthful. Each one names its class (policy, compiled_safety, context_unsupported, argument_invalid, auth), its rule, a reason and a recovery hint, in the terminal and in --output json. Audit records of refusals add the class, the rule, dispatch_attempted: false, and for REST and GraphQL the method and a value-free path template.
  • Nested request bodies. key:=<json> carries an object, array or other JSON value into a REST body or GraphQL variable, for example a repository ruleset.
  • GitHub authentication. Raw gh with a GitHub Actions job token now reaches the installation proof. Hosts without an OS secure store are told which store-free sources work. A Kubernetes secret-volume token file (a symlinked ..data path) is read by the file source.
  • CLI and MCP. engrt resolve --help and engrt command run --help print help; an oversized MCP message gets a JSON-RPC error and the session continues; id-token: write is visible in dry-run diffs.

Compatibility changes to check before upgrading: newly refused destructive forms, changed denial wording, command run <binary> -- … refused, repeated fields refused, and callers that declare nothing recorded as undeclared. All are listed in Upgrading.

Known limitations: the destructive catalog is finite and lexical, not a sandbox, and Git aliases or push settings in repository or user config files are not visible to it; audit records no keyed per-request target digest; live GKE was not qualified; release archives do not yet bundle third-party licence notices.

v0.12.0 — governed authority

v0.12.0 was published on October 15, 2026 from qualified source 222c16e, for macOS, Linux and Windows on amd64 and arm64. It keeps config v2, policy v3 and version: v1 capabilities. See Upgrading.

ENGRT now resolves GitHub authority independently of the caller and reports the actual source, context and proof without returning credentials:

  • Explicitly selected GitHub sources: an ENGRT session created by engrt auth login github (OS secure store), GitHub App, Actions job token, protected token file and environment token. Ambiguous inputs refuse; there is no silent fallback. See Governed authority and the GitHub setup guide.
  • User and installation principals stay distinct; an installation never satisfies a user-only operation.
  • Execution context (declared and observed surface, source, proof, self-asserted caller labels) is reported through direct, capability, MCP and audit paths.
  • Compatibility change: raw engrt command run gh and binary: gh steps no longer receive ENGRT's token; they use your own native gh login.

Known limitations: raw command run gh cannot use a GitHub Actions job token (use engrt github … with the github_actions source); GCP denial cases and live GKE were not qualified; OS-store isolation differs by platform (see Governed authority).

v0.11.0 — capability execution result and live verification

v0.11.0 was published on October 3, 2026 from qualified source e10b093, for macOS, Linux and Windows on amd64 and arm64. Capabilities that use the new result grammar declare engrt_version: ">=0.11.0"; released v0.10.0 does not run them. See Upgrading.

v0.11.0 stabilizes one contract: capability execution result + live verification.

  • Capability execution result and exit codes. capability execute returns one run envelope:

    • run ID and capability identity;
    • every declared step with its step_status (success, denied, failure, not_required, not_executed);
    • typed reasons;
    • logical operation outcomes.

    validate and plan keep their own result shapes. All three exit 0, 1, 2, 3 or 4. Direct operations keep exit 0/1. - Declared outputs, step references and live verification. These features are available only to capabilities that declare engrt_version: ">=0.11.0": - typed outputs; - ${steps.<id>.outputs.<name>} and ${steps.<id>.observation} references; - when gates and expect verification.

    Reruns observe live state and report SATISFIED, APPLIED or RECONCILED. Runtime keeps no resource-state database.

    Verification steps must be read-only invocations. Credential-shaped comparison values are refused before any step runs, and comparison inputs are part of the invocation identity. - GitHub file get, label get and release get, plus an observation mapping on repo view. Inside result-grammar capabilities, an authoritative 404 from these reads is the ABSENT observation. Permission, rate-limit and server failures stay failures. - A trailing --output is honored after REST/GraphQL operations and in resolve. It is never scanned after command run or gh-backed operations. Conflicting values refuse instead of being silently ignored. - Grouped root and provider help. - Step-result audit evidence. Each evaluated result-grammar step adds a hash-chained step-result record: status, observation, verification, outcome and keyed output digests, never raw values. - An experimental MCP proof. engrt mcp serve --stdio exposes one read-only GitHub tool through the same Runtime authority. It is not a stable MCP contract. - Policy: an empty or whitespace-only rule entry refuses the policy at load, naming the list. allowed: [""] previously admitted every operation. - Behaviour change: a repeated --input key is refused as invalid_input (exit 2) instead of silently keeping the last value. A malformed --input also exits 2 (previously 1). Scripts that appended defaults and relied on last-wins must pass each input once. - Corrections from real v0.10.0 use: - refusal detail in text output; - run and step identity in capability JSON; - exact large integers; - capability inspect reports "not found"; - consistent decode diagnostics that report the version first; - an honest label for the Home capabilities cache; - inspect lists gh for gh-backed operations.

Released v0.10.0 fails closed on result-grammar capabilities with a field decode error, before any step runs. v0.11.0 reports an unmet engrt_version before any grammar error. Legacy capabilities keep their exact meaning on v0.11.0.

v0.10.0 — capability contracts, safety and native platforms

v0.10.0 adds the following features and corrections. The published archives passed exact-byte native qualification on all six supported platforms.

  • The executable is engrt, its default Home is ~/.engrt, and Runtime-owned variables use ENGRT_*. Old Runtime variable names are not aliases, and the old Home is not read or migrated automatically. Provider-native variables remain owned by their tools.
  • Optional capability SemVer and step dependencies retain grammar version: v1. capability_version is metadata; id/needs name only earlier steps and preserve sequential, globally fail-fast execution. Legacy workflows retain their compiled identity. v0.10.0 installs and packages a version-matched capability compatibility contract.
  • New audit lineage includes declared capability_version, explicit step IDs/dependencies, actual engrt_version, engrt_platform, engrt_go_version and available engrt_commit/engrt_modified. Historical bytes and legacy omission remain unchanged.
  • Local search and inspect preserve configured source precedence, report shadowed sources, and return explicit incomplete results when a bounded scan cannot finish. They perform no authentication, network fetch or execution; normal Home refresh is allowed.
  • Git safety corrections close global/system config flag-order/subcommand/abbreviation gaps and refuse direct git credential-<helper> get export (store, cache and keychain), including when global options consume a separate value before the operation. The existing compiled safety profile remains v3; these denials also apply inside capabilities and under permissive policy.

Released v0.9.9 rejects the new fields. Shared default capability sources must have an explicit cutover or immutable older-consumer pins. The maintained catalog's owner approved a release-bound 0.10.0 cutover; retained 0.9.9 runs use compatible immutable revisions. Legacy capabilities run on 0.10.0 unchanged. Installing a new Runtime does not upgrade every consumer following a source branch. The maintained catalog targets v0.10.0; older consumers must use their retained compatible revision. Windows amd64 and arm64 join the four macOS/Linux platforms. Windows installation uses checksum-verified published engrt.exe ZIPs. Provider support remains limited to the documented native tool and authentication contracts.

Breaking changes

  • The executable is engrt (engrt.exe on Windows); no runtime alias ships. macOS/Linux archives are engrt-<version>-<os>-<arch>.tar.gz and contain engrt; Windows ZIPs contain engrt.exe.
  • The default Runtime Home is ~/.engrt; ENGRT_HOME overrides it.
  • Every Runtime-owned variable uses the ENGRT_ prefix: ENGRT_HOME, ENGRT_CONFIG_FILE, ENGRT_POLICY_FILE, ENGRT_CAPABILITIES_DIR, ENGRT_GITHUB_TOKEN, ENGRT_PORTAL_*, ENGRT_AUTHENTICATION_*, ENGRT_AUDIT_*, ENGRT_CONSUMER, ENGRT_ACTOR_NAME, ENGRT_SESSION_ID.
  • The runtime.* config overrides map onto the prefix itself: RUNTIME_RUNTIME_NAME → ENGRT_NAME and RUNTIME_RUNTIME_LOG_LEVEL → ENGRT_LOG_LEVEL. The config keys runtime.name and runtime.log_level are unchanged.
  • The default authentication.github.token_env is ENGRT_GITHUB_TOKEN; ENGRT_AUTHENTICATION_GITHUB_TOKEN_ENV redirects it.

Retained and retired behavior

  • Old RUNTIME_* / ENGINEERING_RUNTIME_* names are ignored: no alias and no refusal. ~/.engineering-runtime is not read or migrated by default; copy it to ~/.engrt to keep its state (or set ENGRT_HOME to it to upgrade it in place). Unless it is the active Home, it stays protected from File Engine reads and writes.
  • RUNTIME_CONTEXT_FILE remains retired and still refuses governed execution; engrt context retire now reports it. There is no ENGRT_CONTEXT_FILE.
  • Native variables keep their names: CI, GITHUB_ACTIONS, GITLAB_CI, KUBECONFIG, KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT, USER, USERNAME.

Other changes

  • engrt config init creates a missing output folder (owner-only).
  • Without HOME, the Home error names ENGRT_HOME.

See Upgrading from v0.9.x to v0.10.0.

v0.9.9 — governed execution hardening

Engineering Runtime v0.9.9 provides governed execution hardening for macOS and Linux.

Security and trust boundary

  • Compiled safety cannot be relaxed by configurable policy. v0.9.9 retains compiled-safety-profile/v3; the profile version changes only when an invariant is added, removed or changes meaning.
  • Terraform's secret-export-operation floor covers JSON/raw/named output, state pull, state show, and actual show rendering with or without a path. Human and JSON rendering can expose secret-bearing state/output values even when individual values are not marked sensitive. show -json=false and show -json=0 remain rendering operations and refuse. Reviewed flag-order, global-option and empty-leading forms cannot bypass the floor. Help-only forms intentionally remain eligible. state list, unnamed non-JSON output, plan, apply, init, validate, fmt and providers remain subject to normal admission/policy gates; this does not block all Terraform.
  • GraphQL policy uses parsed operation semantics and canonical query/mutation classes, including generic API paths. Whitespace, comments and formatting cannot turn a mutation into an allowed query. Existing query-text rules must migrate to graphql query / graphql mutation classes.
  • File protection follows effective configured kubeconfig and credential paths, including absent protected paths and applicable alias/identity checks. Read, write and structured-edit grants cannot override these protections.
  • REST, GraphQL, Command and File results cross one shared sanitizer before becoming the canonical safe Runtime result. Structured sensitive fields, including temp_clone_token, complete Bearer values, nested secret assignments and known granted values are protected on success and failure. Sanitized results feed CLI, JSON, compatibility payloads, errors, capability aggregation and evidence. This recognizes supported structures and credential shapes; it is not universal secret detection or general DLP.
  • Audit detail is sanitized before it is recorded; a write that would alter a correlation identifier refuses rather than unlinking evidence.

Execution and result integrity

Overall status, observed execution and evidence are separate. An operation can succeed while required evidence fails: overall status is then failure, but completed side effects remain. Reconcile the target and evidence; blindly retrying a side-effecting operation can duplicate its effects.

HTTP failures, GraphQL partial data/errors, native exit/timeout/cancellation, File results and capability failures retain safe structured observations. Sanitization failure withholds unsafe payloads without inventing an execution failure. Capability steps inherit semantics, compiled safety, policy, auth/context, engines, sanitization and audit/evidence. Strict bounded v1 admission, literal single-pass inputs and immutable source snapshots reject ambiguous definitions and preserve failed-step truth.

Bootstrap refreshes embedded contracts under a cross-process lock, repairs same-version drift and recovers interrupted publication from the binary. It creates no user governance, credentials or capability definitions. Audit privacy-key/journal operations protect private state and report persistence failures rather than silently proceeding.

CLI and agent contract

  • cli is the default bounded human presentation. Large values may be previewed, summarized or truncated; presentation limits are separate from execution and security admission limits.
  • json is the canonical machine/agent contract and contains the complete admitted sanitized result. CLI presentation does not change canonical JSON.
  • text remains a deprecated CLI alias. raw remains a deprecated sanitized single-operation payload projection, never untouched provider bytes.
  • The generic renderer works across providers. Optional provider-owned labels, field order/selection and simple display mappings affect presentation only, not execution, security, sanitization or canonical JSON.
  • Logs, INI, YAML-like text and arbitrary command strings remain opaque unless the engine has reliable structure/content evidence; a leading { or [ is insufficient. Explicit JSON null remains distinct from no content.

Authentication and native context

Runtime preserves provider-native sources and targets rather than owning a profile system. GitHub brokered/native credentials and explicit host/repository binding are hardened; environment narrowing cannot silently select another identity. GCP preserves the admitted credential source through native probes, Command and REST execution, including explicit credential-file federation and named metadata-service-account modes. Native gcloud CLI credentials and ADC remain distinct; no ADC-only HTTP authentication mode is added.

GCP project reads bind the positional project consistently with explicit flags. Maintained GCP capabilities require explicit project inputs and JSON output. Kubernetes supports bounded configured kubeconfig selection and an explicit in-cluster read-only source. GKE workload identity/IAM and Kubernetes RBAC are separate authorization surfaces. Environment markers alone grant no authority.

Platforms

v0.9.9 supports macOS and Linux on amd64 and arm64. Windows support is not yet available in this release and remains under validation.

Installation and release integrity

Archive checksums identify the exact release bytes. Verify the checksum before installing or upgrading, and use a binary matching your OS and architecture. Binary users need no Go installation. See Installation for Homebrew and manual install steps.

Compatibility and accepted limitations

Intentional security tightening can refuse previously executable Terraform, GraphQL, native-context or capability forms. Review affected automation and use JSON for machine consumers. Config remains schema v2, policy v3 and capabilities v1. For rollback to v0.9.8, use a separate Home and retain newer audit history; do not mix v0.9.8 and v0.9.9 evidence writers in one Home.

Local verification establishes integrity of retained frames. Without an external trusted terminal checkpoint, complete trailing-frame deletion cannot be detected. Such trailing-frame removal requires no recomputation of remaining hashes. Intact: true establishes internal consistency, not historical completeness. The local journal is tamper-evident, not tamper-proof.

An external audit checkpoint and broader compiled-safety coverage for other providers and tools are planned after v0.9.9; neither is part of this release. Execution support is not equivalent to trusted support; this release does not claim semantic compiled-safety coverage for every CLI or provider command.

Installation · Upgrading · Migration

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 is 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 a Control Plane governance 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

Explicit configuration and policy schemas. 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

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.

v0.5.3

Historical Portal topology

The API prefixes and api.engineeringruntime.com backend mapping below describe v0.5.3 only. v0.9.7 retired /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.

Prepared v0.10.0 capability Runtime requirements

Optional top-level engrt_version declares which installed binary can run this capability, for example engrt_version: ">=0.10.0 <1.0.0". It first requires Runtime 0.10.0. Omission keeps legacy behavior and adds no implicit minimum. The string accepts at most eight whitespace-separated SemVer 2.0.0 comparators (=, >, >=, <, <=, or a bare exact version), at most 512 bytes. There is no space between operator and version; all bounds must match. No v prefix, OR, wildcard, caret, tilde, comma or interpolation is supported. Build metadata does not affect ordering. Prereleases use SemVer precedence: 0.10.0-rc.1 does not satisfy >=0.10.0; explicitly declare a prerelease bound when appropriate. Contradictory bounds match no version.

Validate, plan, preview and execute check the binary-owned release version before policy/config/auth probes, effects or capability evidence. A mismatch refuses with an installation hint; it never downloads or selects a binary. Inspect/search expose the declaration and incompatibility without authentication. The requirement cannot override grammar, provider availability or policy and does not change compiled invocation identity; the source digest binds its exact bytes. Older binaries safely reject this new field. Old capabilities without it continue to work on v0.10.0; they need no bulk rewrite.

Prepared v0.10.0 names the optional capability requirement engrt_version. The earlier development spelling runtime_version refuses with a rename hint.

When a capability declares capability_version, audit lineage records that exact SemVer as capability_version on capability start/completion, every step intent/completion and ordinary audit records, including preview and failed runs. It comes from the same loaded snapshot as capability_digest; it is an author label, not proof of immutable publication. Missing declarations remain omitted for legacy capabilities. Source and compiled invocation digests keep their existing meanings; declaring a version does not select historical content.

v0.10.0 also records the actual executing release as engrt_version, with engrt_platform and engrt_go_version. When available, engrt_commit and engrt_modified identify the VCS build. This audit version is an exact release; the capability declaration’s engrt_version is a compatibility requirement. Run/step intent, completion and ordinary records retain the same build identity. Recovery preserves original provenance. Old records omit these fields and remain unchanged; credentials and raw capability inputs are not added to audit.

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