Operate v0.14.0 safely¶
Engineering Runtime v0.14.0 is released for macOS, Linux and Windows on amd64
and arm64. This guide helps operators use the GitHub execution, audit and output
changes while preserving evidence and recovering safely from incomplete work.
Start with Installation or
Upgrading.
Outbound MCP and expanded raw gh admission are excluded. See the qualification
limits below before relying on an end-to-end repository onboarding workflow.
Goal¶
Understand the changed behavior, inspect an isolated Runtime Home, and preserve truthful evidence when a request is refused or a previous execution is uncertain.
Prerequisites¶
- Obtain the released v0.14.0 binary and verify its checksum using the installation guide.
- Keep your stable binary and Home. Use a new, separate Home for evaluation; do not point an older binary at newer working state.
- For live GitHub requests, use an existing explicitly configured source with permission for the intended repository. Follow GitHub authentication and governed authority. A credential being present is not proof of permission or target visibility.
- The commands below assume
engrtresolves to the released v0.14.0 binary. They do not configure credentials, execute GitHub writes, or authorize recovery.
Inputs¶
| Input | Meaning |
|---|---|
ENGRT_HOME |
A new disposable directory for this evaluation; never overwrite your normal Home |
| Checkpoint file | JSON captured from this Home and retained independently of its journal writer |
| GitHub repository | Explicit owner/name for requests that need one; never infer it from a 404 |
Steps¶
On macOS or Linux, create a separate Home:
On Windows PowerShell:
$env:ENGRT_HOME = Join-Path ([System.IO.Path]::GetTempPath()) ([guid]::NewGuid().ToString())
New-Item -ItemType Directory -Path $env:ENGRT_HOME | Out-Null
engrt --version
engrt audit verify --help
engrt github api --help
These setup commands do not by themselves establish Windows qualification. Operation help resolves no target and dispatches no provider request. Preserve normal bootstrap side effects when using other commands against a Home.
Read local evidence without contacting a collector:
A fresh Home has no execution history: NO_EVIDENCE is expected, not a broken
installation. After recording actual operations, print a checkpoint:
Retain that JSON outside the journal writer's control using your approved storage procedure. A checkpoint stored beside a writable journal is not independent custody. To compare with a separately retained file:
Use your actual checkpoint path; the example path is a placeholder. On Windows, use the corresponding filesystem path. Verification does not repair or rewrite history. It still needs the Home's normal startup and locking prerequisites.
Expected output and behavior¶
The released executable prints:
The audit verify help explicitly states:
| Area | v0.14.0 behavior |
|---|---|
| GitHub 404 | Curated repository, label, release and file observations cannot prove absence from 404. Result-grammar capability steps fail with observation_not_authoritative; dependent writes do not run. |
| Convergence | Already-present matching resources can remain SATISFIED without writes. Missing-resource repair and full first-run convergence are unsupported. Explicit unconditional creation can fail on rerun; it is not an idempotency promise. |
| Native GitHub | Raw command run gh and binary: gh admission still includes only gh repo list. Curated engrt github … CLI operations are a separate brokered route. Policy cannot permit a compiled-floor refusal. |
| REST input | Inline key=value and key:=<json> fields remain supported. Multipart, resumable upload, binary download, polling, caller-selected/request compression and file/stdin body modes are unsupported. A literal body=@file is data, not file loading. |
| REST response | One request does not imply polling or completion of a server-side asynchronous task. Redirects are refused without following them. Existing gzip responses are decoded within response-size limits; this does not enable request compression. |
| Output | Recognized private-key envelopes, including incomplete bodies and selected split-string forms, are redacted. This is bounded defense in depth, not arbitrary-secret detection. PuTTY PPK is not covered by the private-envelope detector. Truncated raw output is explicitly signalled. |
| First use | --version is supported; declared operation help is available before execution admission; missing capability plans return structured errors. Package README checks reject ambiguous encoded local destinations and verify exact archive members. |
| MCP | Existing inbound MCP regression and redaction remain in scope. No outbound MCP client, official-image interoperability or Docker qualification is claimed. |
A local anchor detects missing tail history only while the anchor survives.
An independently held checkpoint covers its own sequence extent. A retained
newer anchor can prove loss beyond an older checkpoint. If both the later frames
and their anchor are erased, the older checkpoint cannot reconstruct that later
history. complete_to_checkpoint is bounded completeness, not a global history
or authenticity guarantee. Existing frames after a checkpoint are uncovered.
Malformed configuration and audit debt¶
Malformed security configuration refuses before credential resolution,
authentication, probes or provider/native/MCP dispatch. When private durable
recording succeeds, it records the fixed configuration_unavailable refusal.
If collector authority cannot be established, that record retains a
collector-required pending obligation as an explicit assumption.
Repairing configuration or switching to valid local mode does not erase the obligation. An installation intended to be local can therefore retain pending collector debt after malformed configuration. Local durable evidence is never proof of remote collector delivery. Existing valid local-mode behavior is unchanged; no synchronous collector acknowledgement is required.
If audit initialization, reservation, persistence, sync, completion or anchor recording fails, the command remains unsuccessful. A pre-dispatch failure does not authorize execution. If execution already started, its actual or unknown effects remain visible; a later evidence failure cannot undo them. Preserve the Home and reported evidence. Do not delete journals, anchors, locks or pending records to bypass a refusal, and do not retry a potentially completed write blindly.
Common failures¶
- 404 after authentication: inspect repository identity and credential permissions through an authorized read. Do not translate 404 into “safe to create.”
- Native mode refused: use an applicable curated operation; changing editable
policy cannot admit another raw
ghmode or bypass the compiled floor. - Audit storage failure: restore the required private storage/access/capacity
without deleting evidence. Inspect
audit statusand verification results. - Unresolved intent: first establish that no process is executing against the
Home. Only then may an operator deliberately run
engrt audit recover. It recordsoutcome_unknown, never success, rollback, collector delivery or replay. - Checkpoint from another Home/segment: use the checkpoint belonging to the recorded segment; do not substitute a convenient checkpoint to get a green result.
Exit codes¶
These are audit verify exits, not the general command or capability exit table:
| Exit | Verification meaning |
|---|---|
| 0 | COMPLETE to the available anchor/checkpoint; inspect completeness and uncovered frames |
| 1 | Storage, read or lock error |
| 2 | Invalid arguments/checkpoint |
| 3 | CHECKPOINT_NOT_APPLICABLE |
| 4 | BROKEN chain |
| 5 | INCOMPLETE_FINAL_LINE |
| 6 | TRUNCATED covered tail |
| 7 | MISSING journal with retained anchor |
| 8 | NO_EVIDENCE |
| 9 | CONSISTENT, completeness unverified |
| 10 | MISMATCH with the held checkpoint |
Qualification status¶
The exact release archives passed native macOS, Linux and Windows checks on amd64 and arm64, selected GitHub/CI checks and the actual-v0.13 audit upgrade check. These results cover the selected assertions, not every deployment or credential-isolation scenario. macOS observed caller-isolated credential-store reads; Linux and Windows observed same-user readability. Live GKE is not claimed.
Release approval accepts incomplete end-to-end repository-onboarding verification and missing manual operator acceptance observations. The tested onboarding flow created and configured its repository, then failed the final CODEOWNERS read. Inspect the actual repository and CODEOWNERS file before any recovery; failure does not roll back earlier effects, and replaying creation is not a repair. Missing-resource repair and full first-run convergence remain unsupported. Published availability is not a claim that these incomplete observations passed.
Next¶
Read Runtime Home preservation and recovery before upgrading or evaluating an existing installation.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.