ota-run/ota](https:

improved workspace command observability for JSON usage: ota workspace doctor,
ota workspace check, ota workspace status, ota workspace receipt,
ota workspace diff, ota workspace run, ota workspace up, and
ota workspace refresh now accept --progress-json to emit live machine-readable stderr
progress while preserving the final JSON report on stdout; workspace-run progress now surfaces
both task and resolved repo_task when a workspace task binding rewrites the local task name,
all workspace progress events now also carry a command field so machine consumers can
distinguish workspace.doctor, workspace.check, workspace.diff, workspace.status,
workspace.receipt, workspace.run, workspace.up, and workspace.refresh without relying
on out-of-band stream context, workspace-status / workspace-receipt progress uses tail for
the repo drift state, and
workspace-diff progress uses status for the diff verdict plus tail for the machine
drift_kind

added workspace-owned repo task bindings under repos.<name>.tasks.<workspace_task>.task, so
ota workspace run <task> no longer requires every repo to share the same local task name;
workspaces can now map one shared workspace verb such as prepare-dev onto repo-local tasks
like generate-sdk, while ota workspace tasks and workspace run receipts expose the resolved
repo task truth instead of leaving mixed-name cross-repo execution buried in shell or tribal
knowledge

widened prepare.kind: sequence from structural prepare-only chaining to mixed structured setup
ownership: ordered prepare.steps can now combine typed prepare lanes such as
dependency_hydration and tool_bootstrap with deterministic native bootstrap mutations such
as ensure_env_file, ensure_file, ensure_directory, ensure_git_checkout,
ensure_container_network, and reset_compose_service_volume, so repos can model multi-step
browser/setup truth like env materialization plus browser bootstrap without collapsing back to
shell glue

widened prepare.kind: tool_bootstrap with prepare.tool: playwright_browsers and
prepare.source.kind: node_package_manager and prepare.source.kind: poetry, so repos can own
documented playwright install browser bootstrap lanes structurally under npm, pnpm, yarn, bun,
or Poetry instead of falling back to repo-local shell glue or leaving browser-runtime proof
half-modeled

tightened active repo-execution conflict ownership so Ota now derives shared writable-path
ownership from the full selected task path, not just the requested leaf task; overlapping runs
that converge on the same declared effects.writes path now fail fast with a write_path
conflict instead of racing through dependency setup and corrupting shared state like
node_modules

widened structured compose.kind: down with compose.timeout_seconds, so graceful shutdown
timeout truth like docker compose down -t 2 no longer has to fall back to raw command bodies
when a repo needs deterministic Compose teardown ownership

widened structured Compose control tasks with compose.kind: ps, so staged inspection lanes like
docker compose ps main can stay on the same first-class compose surface as up, down,
build, stop, restart, rm, and logs instead of falling back to raw host command glue

widened prepare.kind: dependency_hydration for source.kind: docker_compose with ordered
prepare.source.files and prepare.source.env_files, while keeping prepare.source.file as a
compatibility alias; Compose-backed image hydration can now own the same multi-file and
interpolation env-file truth as the rest of Ota’s Compose surfaces instead of collapsing back to
single-file-only pull glue

widened services.<name>.manager.kind: compose with ordered manager.files and
manager.env_files, while keeping manager.file and manager.env_file as compatibility
aliases; compose-managed services can now own the same multi-file and multi-env-file overlay
stacks that task/workflow adapter inputs already support, which closes the split-brain between
overlay-aware compose tasks and single-file-only service ownership on repo contracts such as
Open WebUI's Playwright sidecar runtime

added first-class action.kind: ensure_git_checkout, so deterministic repo bootstrap can now
materialize sibling or vendored Git checkouts under the same native setup/action surface as
ensure_file, ensure_env_file, and ensure_bundle; Ota clones a declared Git source only
when the repo-relative checkout path is missing, optionally checks out a declared ref, and
intentionally leaves existing directories untouched instead of smuggling fetch/reset/update
semantics into bootstrap; ota validate / ota doctor now also warn when checkout
materialization omits source.ref, so moving-head pressure bootstrap does not silently read as
deterministic proof truth

added first-class tasks.<name>.effects.adapter_state for durable adapter-owned task state such
as Compose volumes, and widened typed dependency hydration so prepare.kind: dependency_hydration
can declare durable state through effects.writes or effects.adapter_state instead of being
forced back to shell or fake repo writes on volume-backed Compose lanes

added Unix host OTA_HOST_GID interpolation alongside OTA_HOST_UID so native and compose task
env can truthfully model host user/group projections like CURRENT_UID=<uid>:<gid> without shell
id -g glue

widened tasks.<name>.variants so OS-scoped variants can declare env, env_files,
env_bindings, inputs, requirements, and adapter_inputs without cloning the task body,
which lets one structured task keep a single executable shape while specializing process,
prerequisite, and Compose/Bake/Helm overlays per OS

fixed persistent runtime ownership regeneration so recreated .ota/state/ownership-id files no
longer mint a fresh repo identity and strand Ota-managed containers or dependency-isolation
assets outside repo-scoped cleanup; repo ownership now regenerates deterministically from the
working directory when state metadata is rebuilt

fixed starter agent-boundary inference so ota init and ota detect no longer implicitly mark
dependency-hydration setup lanes as agent.safe_tasks; setup can still remain the truthful
agent entrypoint, but only genuinely safe verification tasks are inferred into the starter
safe-task surface by default

added first-class launch.kind: compose for long-running docker|podman compose up runtime
starts, so repos can model persistent Compose-owned runtime launch truth under launch instead
of forcing packaged stack startup through launch.kind: command; the same pass teaches opaque
service-start governance to prefer launch.kind: compose when the shell lane is really
docker|podman compose up

fixed native structured Compose execution so adapter-owned compose working directories stay owned
by the task adapter surface instead of being duplicated onto projected command cwd; native
compose task bodies and launch.kind: compose no longer double-join adapter roots like
docker/docker during spawn

widened ota proof runtime with --host-port, so runtime proof can now consume the same
projected host-listener override surface as ota run and ota up when concurrent pressure or
host-port conflict isolation needs a remapped publication

widened native structured Docker Compose host-port remap from generic container publication
only to explicit native Compose publication ownership, so ota run, ota up, and
ota proof runtime can now remap docker compose up listener publications through
tasks.<name>.runtime.listeners.<listener>.project.publication.compose.service instead of
failing early on native bind conflicts; validator now requires that publication owner truth to
stay explicit and governed

tightened native Compose bind-conflict guidance so ota up and run/proof failure surfaces now
state explicitly when a listener is being published through native docker|podman compose and
why --host-port is not available on that lane today, instead of implying the conflict should
be solved through the generic projected-listener override path

widened tasks.<name>.compose with first-class compose.kind: up, compose.kind: down,
compose.kind: build, and compose.remove_volumes: true for compose down -v, so repos can
model staged docker|podman compose up [-d] <services...>, project-scoped compose down,
compose down -v, and compose build [services...] lanes without falling back to opaque
host-shell docker compose ... glue; the same pass also widened workflow prepare.task to
accept finite native compose bodies and tightened ota up --dry-run --json action text so
command and compose tasks publish the actual structured execution preview instead of generic
task placeholders

widened tasks.<name>.compose again with first-class compose.kind: restart,
compose.kind: rm, compose.kind: logs, compose.force_recreate: true for
compose up --force-recreate, compose.force: true for compose rm -f, and
compose.follow: true for compose logs -f, so repos can model Compose control lanes without
falling back to opaque host-shell docker|podman compose ... glue

widened tasks.<name>.compose again with first-class compose.kind: stop, so repos can own
truthful stopped-container preconditions such as docker|podman compose stop <services...>
structurally before compose rm cleanup instead of falling back to repo-local shell glue

fixed runtime-proof workflow-instance selection and container Corepack run-path fulfillment, so
ota proof runtime --workflow <name>@<instance> now preserves instance overlays in topology,
cleanup, and proof artifacts, and container-mode setup/run lanes now honor selected container
mode contexts while executing Corepack-owned package managers through the selected run path

fixed container backend fulfillment for Corepack-owned package managers, so tasks that declare
toolchains.node.fulfillment.source: corepack no longer fail preflight just because fresh
container images do not already ship pnpm or yarn; ota now treats those package managers as
source-managed task capabilities instead of image preconditions

added first-class workflow-instance selection with workflow@instance, so one declared workflow
can now own named instance overlays for task env, adapter inputs, and surfaced host ports without
splitting that runtime family into pseudo-workflows; ota now also injects OTA_HOST_HOME for
truthful host-home clone/cache derivation, and Penpot can model ws0/ws1/ws2 as one governed
workflow family instead of one flattened ws0-only contract

widened workflow instances with topology.requires_instances, so ota up --workflow <name>@<instance>
can now honor declared sibling-instance bring-up order such as ws1+ requiring ws0 first, and
validator now rejects broken or cyclic instance-topology declarations

widened workflow env rendering with env.profiles.<name>.render.files[], so selected workflows
can now materialize structured json and toml artifacts from ordered merge sources with
instance-aware placeholder substitution and optional merge_into_existing; Penpot can now model
per-workspace MCP/client config generation as contract truth instead of a repo-local merge helper

widened workflow-instance task overlays with workflows.<name>.instances.<instance>.tasks.<task>.runtime,
so selected workflow instances can now specialize existing task runtime listeners and readiness
fields without inventing a parallel workflow-local listener model; instance-scoped bind/project
port truth now merges onto the base task runtime and stays visible to validation, dry-run, and
runtime proof

fixed runtime surface/listener split-brain by allowing one explicit task listener to share the
same name as one attached published surface; surface-backed runtime proof and workflow exposure
now align with the validator instead of forcing duplicate or renamed publication truth

added first-class interactive workflow attach ownership with workflows.<name>.attach.task and
tasks.<name>.compose.kind: attach, so detached session workflows can declare one canonical
re-attach lane and ota up --attach now keeps the service runtime running, proves readiness, and
then enters the declared interactive session instead of assuming the run task itself stays
foreground

fixed workflow-instance cleanup topology detection so shared Compose projects such as instance
prerequisites or shared infra no longer count as dependent instance presence; runtime proof and
workflow cleanup now only block on instance-specific dependent projects that are actually present

hardened unreleased git installs in the official shell and PowerShell installers by defaulting
CARGO_NET_GIT_FETCH_WITH_CLI=true on --from-git lanes, so contract-owned git revision and
branch bootstrap paths no longer depend on Cargo's flakier libgit transport on hosted runners

added first-class tasks.<name>.compose.detach for detached docker|podman compose exec
lanes, so repos can model truthful in-service bootstrap/start commands without opaque shell
docker exec -d ... glue

added first-class tasks.<name>.compose execution bodies for structured docker|podman compose exec/run lanes, so repos can model finite service-side commands without falling back to opaque shell argv

widened prepare.kind: dependency_hydration with optional prepare.source.compose invocation wrappers, so typed package hydration lanes such as npm, Bundler, uv, Poetry, Maven, Gradle, Cargo, and dotnet restore can execute through declared Compose service truth as structured compose wrapper execution instead of raw task-body shell glue

fixed V10 receipt-diff correlation fallback so ota receipt --baseline latest now marks
resolved blockers as likely related when contract drift clearly explains a resolved finding and
no new material blockers were introduced; semantic snapshot diffs no longer collapse to
no_clear_correlation just because the change fixed one blocker while other unrelated blockers
still remain

tightened V10 likely-related ordering for missing env drift so adjacent metadata siblings such
as secret no longer ride along with causal required changes; receipt diff now publishes the
sharpest env assumption instead of same-owner noise

fixed ota receipt --snapshot latest and --baseline latest fallback for archived repo
receipts that predate workflow-scoped identity widening, so Ota now resolves the newest
matching contract lineage first by exact identity and then by same-contract lineage instead of
failing archived snapshot and baseline lookup on valid older receipt archives

added first-class action.kind: reset_compose_service_volume, so destructive Compose-managed
data reset lanes can be modeled as structured Ota actions instead of shell docker compose /
docker volume rm glue

widened effects.network_kind with first-class integration_test, so live or staging-backed
verification lanes no longer need to collapse into broad; doctor findings, policy effect
governance, and contract docs now carry a dedicated network classification for real-service test
paths

fixed integration_test effect-kind aggregation so agent-safe advisories and selected-task
effect closure reporting preserve real-service verification lanes instead of collapsing them into
dependency hydration, and validate now nudges service-backed test tasks onto
effects.network_kind: integration_test

fixed native ota proof runtime post-run diagnosis to activate the same mise path surface as
ota doctor, ota up, and ota run, so proof no longer re-checks toolchain-owned runtimes on
an older parent PATH after the child ota up --stream path already resolved through
HOME/.local/bin / mise-owned host toolchain truth

injected OTA_HOST_WORKSPACE and OTA_HOST_UID into task execution so host-launched tasks can
pass real repo-root and host-user identity through contract env truth instead of shell glue such
as pwd or id -u

fixed detached service-start readiness proof in ota up and ota proof runtime: when a
service launcher such as docker compose up -d exits successfully before the runtime itself is
ready, ota now keeps probing until the declared readiness budget expires instead of treating the
launcher exit as the failure boundary

deduped identical doctor findings and widened .gitignore hygiene recognition so parent .ota/
ignore entries satisfy the repo-artifact protection checks

widened task mode branches with first-class execution.modes.<mode>.depends_on, so one task can
keep stable identity while truthfully switching prerequisite chains per execution plane; planner,
runner, previews, ota up setup adjustment, task summaries, and boundary advisories now all
resolve selected dependencies from the active mode branch instead of silently falling back to the
task-level list

added machine-readable dependency-plane provenance to ota run --dry-run --json, so
plan.dependency_steps[] now reports each planned task step's parent task, selected backend,
selected context, and backend-selection source including inherited parent backend resolution

widened the same dependency-plane provenance into validate advisories and execution receipts, so
warning_details[].provenance now explains selected dependency-boundary source lanes and
task-backed receipt.dependency_steps[] preserves the backend-selection truth ota actually ran

refined ota proof runtime artifact diagnostics so proof/*/doctor.json now upgrades generic
run-exit blockers to concrete container-engine-unavailable execution findings when the captured
up.log shows Docker or Podman backend reachability failures

widened ota receipt with first-class workflow selection, so ota receipt --workflow <name>
now reuses the selected workflow's env-profile/readiness lane and keeps latest, promoted,
and archived receipt/snapshot selection scoped to that workflow instead of mixing receipt
history across unrelated workflow baselines

tightened V10 selected task-path external-state correlation so task
effects.external_state drift is published as likely related instead of falling back to
no_clear_correlation

tightened V10 native prerequisite correlation so selected task-path
requirements.native and requirements.any_of[..].native ownership outranks broad
native_prerequisites.* declaration drift in semantic snapshot comparisons

fixed selected-path standalone tool acquisition version trust across ota doctor, ota up,
and ota run: task-local wildcard requirements such as tools: { yq: "*" } now preserve the
exact owned version declared under tools.<name> when the selected path resolves through
tools.<name>.acquisition, instead of collapsing that selected acquisition lane back to *

fixed native post-fulfillment diagnosis for source-managed standalone tools: when Ota acquires a
tool through tools.<name>.acquisition.provider: release_asset, follow-up ota doctor and
ota up diagnosis now probe the repo-managed .ota/state/source-managed/bin path too instead of
falsely saying the tool is unavailable on PATH after fulfillment already succeeded

fixed repo-managed release-asset probe execution across provisioning and doctor: follow-up
vale --version style probes now execute the managed binary correctly from the repo working
directory instead of tripping over relative .ota/state/source-managed/bin/... paths during
post-fulfillment verification

Normalize detected Node engine unions like 22 || 24 into explicit semver branches and honor
those unions during runtime/toolchain matching, so detector-owned Node version truth no longer
misclassifies valid installed Node majors.

added semantic contract snapshot identity to repo and workspace receipts, so
ota receipt --json and ota workspace receipt --json now emit a normalized
receipt.contract_snapshot_hash on every successful receipt and archive the matching
normalized contract JSON under .ota/contracts/sha256-....json when --archive is used

widened shipped ota diff onto normalized semantic contract truth, so diff no longer compares
raw YAML structure; it now compares normalized assumption keys, accepts archived receipt JSON
plus archived .ota/contracts/... snapshot JSON as inputs, and emits additive category /
risk metadata per changed assumption

added receipt-to-receipt semantic contract drift correlation, so ota receipt --json --baseline
now compares the selected archived baseline snapshot against current normalized contract truth
when available and emits additive summary.comparison.contract_snapshot_changed,
contract_changes[], and likely_related_changes[]; the initial correlation lane now covers
env, tool, runtime, check, task, and required-service blockers instead of only the narrowest
missing-env cases

clarified semantic diff input identity, so ota diff text output now shows each side's resolved
semantic input kind and any archive-backed snapshot path, while ota diff --json publishes
additive base_input / target_input metadata instead of forcing operators to infer archived
receipt snapshots from path patterns alone

added first-class archived snapshot inspection under ota receipt --snapshot, so operators can
read archived normalized contract truth directly from latest, promoted, archived receipt
JSON, or archived .ota/contracts/... snapshot files without routing that inspection through
ota diff or receipt-correlation output

widened ota receipt --snapshot inspection evidence, so snapshot text and JSON now publish the
canonical extracted assumption-set hash plus assumption count alongside the whole-snapshot hash
and archived normalized contract JSON instead of forcing operators to derive semantic snapshot
identity indirectly from the payload

added additive receipt.assumption_set_hash identity for repo and workspace receipts, so
archived and live receipt JSON now fingerprint the canonical extracted semantic assumption map
separately from whole-snapshot identity and receipt diff can surface the same identity on both
baseline and current sides

refined receipt diff correlation with an explicit advisory verdict under
summary.comparison.correlation, so automation can distinguish likely_related,
possibly_related, and no_clear_correlation without inferring correlation posture from
likely_related_changes[] alone; possibly_related is now reserved for coarse same-family
overlap, while unrelated contract drift stays no_clear_correlation

fixed archived receipt finding identity round-trip for V10 compare, so
ota receipt --json --baseline ... no longer emits phantom introduced[] / resolved[]
findings when the archived baseline and current receipt are semantically unchanged; archived
flat code / category / owner finding fields now deserialize back into stable finding
identity instead of collapsing to anonymous OTA_DOCTOR_FINDING_UNKNOWN matches

tightened likely_related_changes[] ordering across adjacent plausible lanes, so receipt diff
now ranks the published contract-change evidence globally by semantic match strength instead of
emitting changes in finding-visit order when multiple adjacent assumptions all look plausible

tightened missing tool/runtime correlation ordering across broad declaration vs selected-path
requirement truth, so likely_related_changes[] now prefers
tasks.<name>.requirements.tools.<tool> / .requirements.runtimes.<runtime> /
.requirements.toolchains.<toolchain> over broader tools.<name> or toolchains.<name>
catalog drift when the selected task path is the sharper operational owner of the failure

moved more receipt diff entity recovery into declared doctor finding metadata, so env, tool,
runtime, check, and service correlation matches now prefer published owner/entity truth over
CLI-side summary parsing when ranking exact owner, requirement-reference, and name-reference
contract changes

tightened likely_related_changes[] ordering inside the same semantic owner lane, so receipt
diff now prefers the nearer declared owner subtree before generic path-depth tie-breaks and
publishes root kind-level evidence ahead of deeper nested detail when both changes are
plausible for the same finding

reduced residual receipt-diff fallback taxonomy for named-entity findings, so tool, runtime,
check, and service correlation now stays on declared doctor owner/entity metadata instead of
duplicating those lanes in CLI-only fallback matching; only the broad undeclared task-family
fallback remains

widened declared receipt-diff workflow correlation for named probes and surfaces, so workflow
readiness failures now match top-level probe definitions, reusable top-level surface owners,
workflow probe/surface references, and runtime surface definitions before falling back to broad
workflow-family drift

refined same-lane receipt-diff evidence ordering for workflow probes and surfaces, so adjacent
endpoint drift such as probe path or surface port now publishes ahead of weaker success-rule,
path, or metadata changes when multiple nearby assumptions are all plausible

widened coarse receipt-diff overlap recovery to respect declared owner roots too, so broad
correlation posture now still recognizes reusable top-level surfaces.* and
readiness.probes.* drift as the same semantic family when exact workflow matching is not
available

widened runtime receipt-drift correlation to include execution-context runtime requirements, so
runtime version-mismatch blockers can now correlate directly to
execution.contexts.<name>.requirements.runtimes.<runtime> instead of falling back to
no_clear_correlation

added a dedicated local core spec for semantic snapshots and receipt correlation, so the V10
operator path is documented inside docs/spec/ instead of only through dispersed command pages
and the public site reference

documented the public semantic snapshot operator path in core README and command/spec docs, so
humans and agents now have one canonical page for archived semantic truth, ota diff,
ota receipt --snapshot, and receipt-to-receipt drift correlation

refined receipt diff check-correlation ordering with current-contract check-name recovery, so
named check failures can resolve checks[<index>] from the current contract even when the diff
did not change checks[...].name, and the changed check body now outranks adjacent task-body
drift instead of losing because array-index ownership was not recoverable from diff paths alone

widened declared check-correlation ordering across adjacent reference lanes, so named check
failures now treat explicit check-reference changes such as tasks.<name>.requirements.checks[]
and workflow check-reference lanes as stronger evidence than a nearby generic task-body change

widened declared service-correlation ordering across workflow reference lanes, so named service
findings now treat workflows.<name>.services.required[] as stronger evidence than a nearby
generic workflow change instead of flattening both into the same broad workflow lane

widened declared env-correlation ordering across path-scoped requirement lanes, so named env
findings now treat tasks.<name>.requirements.env[] as stronger evidence than a nearby generic
task-body change instead of flattening both into the same broad task lane