Skip to content

ota-run/ota](https:

v1.6.20 Breaking

This release includes 1 breaking change for platform teams planning a safe upgrade.

Published 1mo Developer Productivity
✓ No known CVEs patched
Read the diff → Tool health → What is this tool? →

✓ No known CVEs patched in this version

Topics

cli configuration contracts developer-tools infrastructure ota
+5 more
productivity repo-readiness rust validation workspace

Affected surfaces

auth rbac breaking_upgrade

Summary

AI summary

Added release-gated skills‑sync governance check requiring docs/policy/skills-sync-status.yaml updates for core schema changes.

Full changelog
  • added a release-gated skills-sync governance check for contract-surface widening: maintainer
    changes to core schema/validator/spec/example surfaces must now update
    docs/policy/skills-sync-status.yaml with either a synced ota-run/skills commit or an
    explicit waiver reason, and the release gate plus repo task surface now enforce that discipline
  • moved published repo/workspace contract schema ownership into a Rust-backed generator module and
    added a sync/export path via cargo run --bin sync_published_contract_schemas; CI compatibility
    tests now fail when docs/spec/json-schemas/contract.json or
    docs/spec/json-schemas/workspace-contract.json drift from that generator, closing the remaining
    hand-edited published-schema split-brain
  • tightened generated-schema governance again: the release gate and repo compat task now rerun
    the published-schema generator and fail on git diff --exit-code drift before the schema/output
    contract tests run, so publication proves regenerated artifacts rather than inferring sync only
    from downstream test coverage
  • tightened the type-model boundary behind the published repo/workspace contract schemas: shipped
    examples and canonical contract docs examples now validate not only as authored YAML, but also
    after loading through the Rust contract types and projecting back to authoring JSON values, so
    the published schemas are exercised against the real Rust-owned authoring-model boundary rather
    than only raw source files
  • published and enforced the full machine-readable workspace contract schema at
    docs/spec/json-schemas/workspace-contract.json /
    https://dist.ota.run/spec/json-schemas/latest/workspace-contract.json; shipped workspace
    examples and canonical workspace contract docs now validate against that published schema, and
    the compatibility surface now treats both repo and workspace contract schemas as release-gated
    public APIs
  • published and enforced the full machine-readable repo contract schema at
    docs/spec/json-schemas/contract.json /
    https://dist.ota.run/spec/json-schemas/latest/contract.json; shipped example contracts and
    canonical repo contract docs now validate against that published schema so contract publication
    is a governed release surface instead of an optional artifact
  • hardened finding identity across governance surfaces: advisory-backed doctor findings now carry
    explicit stable identity, ota explain --json preserves that code through steps[].code
    instead of re-deriving advisory identity from rendered summary text, and ota annotations
    now renders additive Code: segments when input finding JSON includes a stable code; the main
    structured doctor finding families for service readiness, declared checks, runtime/tool
    diagnosis, env value and env-source failures, backend/remote topology blockers, workflow
    probe/surface readiness findings, policy-backed findings, repo hygiene findings, native
    prerequisites, and contract drift now also emit explicit stable code / category / owner
    identity instead of depending on summary parsing; policy-backed version-rule and strict-version
    findings now also preserve policy metadata/provenance consistently in doctor JSON
  • added a representative ota doctor --json contract pack across policy, workflow, service, env,
    provisioning, and remote finding lanes, and CI now fails if a shipped doctor finding is added
    without explicit identity metadata; doctor report-level contract coverage now also locks summary
    verdict/counts, primary-blocker mirroring, ready-without-blocker shape, and published schema
    truth for mode: remote plus summary.primary_blocker.code; the shipped doctor code catalog is
    now published in a generated reference doc synced from src/doctor.rs, and contract-drift
    findings now publish the documented repo_signals provenance instead of falling back to generic
    repo-contract provenance; monorepo aggregate ota doctor --json now also computes
    summary.primary_blocker from the same rewritten emitted findings surfaced in members[]; the
    published workspace doctor/check schemas now also expose top-level summary.primary_blocker and
    blocker code fields in line with the shipped JSON output, and workspace repo acquisition /
    repo-contract findings now also emit explicit stable workspace finding codes instead of falling
    back to anonymous summary-only blockers
  • hardened remaining shipped command finding identity: contractless/onboarding doctor signals,
    inferred starter-agent signals, policy effect-governance decisions, and adapter-bootstrap
    failures now emit explicit stable code / category / owner identity instead of anonymous
    summary-only findings; the shipped finding reference catalog now also covers command-sourced
    production findings, and src/cli/commands.rs is guarded so new shipped command findings
    cannot reintroduce identity: None
  • widened ota env with --workflow selection so the env read path can inspect the selected
    workflow’s env profile truth directly; text and JSON output now report the selected workflow,
    selected profile, and any workflow-owned rendered env artifacts such as rendered dotenv files
  • widened execution-truth reporting for workflow-owned rendered env artifacts: ota execution plan,
    execution receipts, and ota proof runtime --json now surface the selected workflow env
    artifacts plus consuming task/service lanes, and validate/doctor now warn when tasks duplicate
    ownership of a workflow-rendered env file that Ota already auto-projects into the workflow task
    closure
  • added first-class task env_files overlays for run-path process ownership, widened
    action.kind: ensure_env_file with deterministic mode: replace, mode: remove, and
    from_env projection from resolved Ota env truth, and sharpened ota proof runtime --json
    with optional likely_cause hints for high-confidence loopback service drift or detached-run
    failure excerpts discovered in captured proof logs; proof phase reporting now refines blocked
    runs from captured up.log so repo check / precondition failures do not collapse into
    misleading service readiness proof phases; invalid task env_files now fail ota env --task,
    run preview, and task execution before env resolution falls through to misleading missing-env
    diagnostics
  • added first-class env.profiles plus workflows.<name>.env.profile, so selected workflow
    doctor/up/proof paths can prepend workflow-owned declared env sources and inject ordered
    workflow-scoped env_files / literal env overlays without repeating that ownership across task
    shells or task-local duplication
  • widened env.profiles with first-class render.dotenv artifact materialization, so ota up
    can now render workflow-owned dotenv files from selected profile truth before service startup
    and setup, removing the remaining need for a separate ensure_env_file prepare task when the
    workflow only needed a compose/runtime interpolation artifact
  • widened env.profiles.<name>.render.dotenv with optional template support, so workflow-owned
    dotenv artifacts can now be re-rendered from repo example truth plus selected profile overlays
    without hiding that materialization inside a separate setup task or stale shell rewrite glue
  • widened first-class check governance with checks[].kind: env, a deterministic dotenv-backed
    assertion surface for repo-relative env files; contracts can now replace shell grep / findstr
    glue with governed env.path assertions over exact values, host values, or URL hosts using the
    initial policy: not_loopback surface plus first-class state: present|missing assertions, and
    requirements.checks / when.checks now accept those env checks directly; validate/doctor now
    also warn on obvious shell file-state and env-file checks that should be rewritten as
    first-class kind: file or kind: env checks
  • widened checks[].kind: env host governance with host.allowed and url_host.allowed, so
    contracts can now assert one env key or URL/DSN host resolves to one of a small set of truthful
    service hostnames without falling back to shell grep glue
  • widened checks[].kind: env with not_equals, so contracts can ban a small set of known-bad
    exact env values without shell assertions
  • widened workflows.<name>.prepare.task from native action-only to native finite task bodies
    (run, script, prepare, or action) so workflow-scoped normalization and bootstrap steps
    no longer need to hide behind task dependencies; service-like prepare tasks still remain invalid
    through launch, runtime, and requires_services rejection
  • added services.<name>.manager.env_file for manager.kind: compose, so Ota-owned compose
    service start/stop/ps/health command paths can carry one declarative docker compose --env-file
    input instead of forcing repo-local shell duplication
  • validate/doctor now also warn on obvious shell .env* rewrite tasks so deterministic env-file
    mutation can move to action.kind: ensure_env_file with explicit replacement keys instead of
    platform-specific sed / perl glue
  • validate/doctor now warn when task bodies hard-code docker compose --env-file ..., pushing
    compose interpolation ownership toward declarative task env_files or
    services.<name>.manager.env_file
  • widened action.kind: ensure_env_file with action.template_mode: replace, so Ota can
    re-derive an env file from its template on every run before applying explicit key replacements;
    this closes the shell copy-plus-sed env normalization gap with one governed action surface
  • widened managed-service topology modeling so service endpoint identity is no longer forced to
    equal execution-context identity: services.<name>.endpoints.<name>.context,
    services.<name>.readiness.endpoint, and tasks.<name>.env_bindings.<VAR>.from_service.endpoint
    now let one context expose multiple truthful service surfaces without falling back to opaque
    shell glue
  • closed the assist authoring gap for named service endpoints: ota assist declare-service now
    accepts --endpoint-context, projects it into proposal JSON/YAML, and keeps generated readiness
    and replay commands aligned with the authored endpoint context
  • widened Docker Compose service topology detection for explicit host-published ports: ota detect,
    ota init, and detect merge can now infer the canonical host execution slice
    (execution.default_context, execution.contexts.host.backend), plus matching
    services.<name>.endpoints.host and structured readiness.from / readiness.kind: tcp
    when one Compose service exposes exactly one deterministic TCP host-published port candidate;
    when one Compose service exposes multiple deterministic TCP host-published port candidates, Ota
    now emits named host endpoints such as services.<name>.endpoints.host_3000.context: host
    instead of dropping topology entirely, while intentionally withholding ambiguous readiness
    ownership
  • closed the remaining readiness assist gap for multi-endpoint services: ota assist declare-readiness now accepts --endpoint, carries the selector through preview/apply
    JSON/text output, and writes services.<name>.readiness.endpoint plus the matching
    readiness.from context instead of forcing manual YAML edits when one service exposes multiple
    truthful projections
  • fixed detect-merge execution governance for inferred Compose host topology: additive merge no
    longer rewrites an authored execution.default_context, and it now skips host-topology
    additions entirely when the existing contract still uses root shorthand execution
  • upgraded Docker Compose service detection to the canonical managed-service surface: ota detect,
    ota init, detect merge, and detect-owned field tracking now emit services.<name>.manager.*
    and structured readiness.kind: compose_health for Compose-backed services instead of teaching
    legacy provider/start/stop/healthcheck as the inferred contract shape, with updated JSON
    output docs and regressions
  • fixed Python toolchain host requirement projection for Poetry-owned repos: when
    toolchains.python.package_managers.poetry is declared without an explicit package_managers.uv
    requirement, Ota no longer injects uv as a mandatory host tool on check-only/run-path surfaces;
    uv remains available for explicit Python run fulfillment and for repos that actually declare
    package_managers.uv
  • Fix native task fulfillment so inferred wildcard shell-tool requirements like pnpm: "*" no longer conflict
    with exact toolchain-owned package-manager versions; exact owned versions now win during requirement merging.
  • fixed agent bootstrap determinism advisories so exact OTA_GIT_REV=<commit> source-install
    pins are now recognized as deterministic, while moving branch installs still warn correctly
  • widened Python toolchain package-manager ownership so Poetry is first-class under
    toolchains.python.package_managers.poetry, while legacy standalone tools.poetry
    declarations remain temporarily accepted with migration warnings instead of a silent break
  • expanded first-class Python setup so Poetry is now operational as well as declarative:
    prepare.kind: dependency_hydration now ships source.kind: poetry, and the existing
    Python provider: uv fulfillment lane can now install declared Poetry versions on the
    selected run path before tasks execute
  • expanded the managed toolchain ownership surface into named execution contexts:
    execution.contexts.<name>.requirements.toolchains is now first-class, so repos can keep
    runtime and package-manager ownership under toolchains even when that truth is scoped to a
    host, container, or other named execution context instead of falling back to split
    runtimes / tools declarations
  • expanded first-class task preparation for dependency hydration with a Yarn slice:
    prepare.kind: dependency_hydration, medium: package_dependencies, and
    source.kind: node_package_manager with manager: yarn now let ota execute
    yarn install --immutable structurally instead of hiding lockfile-backed Yarn hydration
    inside opaque shell run commands
  • added first-class aggregate task bodies through tasks.<name>.aggregate.tasks: Ota now models
    named dependency-closure entrypoints such as verify structurally instead of teaching fake
    run: "true" wrappers, with schema/validation/runner/output support and updated docs/examples
  • fixed mixed-mode task validation for top-level fallback bodies: when a task already declares its
    default native body at the task level, execution.default_mode: native no longer requires a
    redundant execution.modes.native branch just to add a non-default container override
  • fixed workflow-scoped ota up service selection: when a selected workflow does not declare
    workflows.<name>.services.required, Ota no longer falls back to unrelated repo-global
    required services during the final service-readiness phase
  • fixed Windows native POSIX-shell task execution to launch Bash without login-shell startup:
    repo-rooted commands such as Bundler dependency hydration now preserve Ota's selected working
    directory instead of letting bash -l reset execution into $HOME
  • fixed native ota doctor / ota up --dry-run mismatch handling for toolchains.ruby with
    fulfillment.source: ruby and mode: run: when the selected path declares Bundler under the
    Ruby toolchain, Ota now checks the selected Ruby provider instead of blocking on an ambient
    bundle probe before selected-path fulfillment can occur, and the shipped Ruby fulfillment lane
    now installs declared Bundler versions via ruby -S gem install bundler ...
  • clarified agent-facing task guidance: when a repo declares a matching safe or verification
    task, agents should prefer ota run <task> over raw package-manager or language-tool
    commands and fall back only when no truthful Ota task exists or when isolating an Ota defect
  • expanded first-class task preparation for dependency hydration with a native Go slice:
    prepare.kind: dependency_hydration, medium: package_dependencies, and
    source.kind: go_modules now let ota execute go mod download structurally instead of
    hiding module hydration inside opaque shell run commands
  • expanded first-class task preparation for dependency hydration with a Ruby/Bundler slice:
    prepare.kind: dependency_hydration, medium: package_dependencies, and
    source.kind: bundler now let ota execute repo-local gem hydration structurally instead of
    hiding bundle config set path ... && bundle install inside shell run commands
  • hardened dependency-isolation volume cleanup after container-backed execution and proof:
    Ota now gives container engines a longer retry window before surfacing volume is in use
    cleanup failures, reducing false-negative proof tails when Docker lags briefly after
    container removal
  • added first-class task preparation semantics through tasks.<name>.prepare: the shipped
    prepare.kind: dependency_hydration slices now model both docker image hydration and
    node package-manager dependency hydration structurally instead of forcing finite setup phases
    to live inside opaque shell run strings
  • added executable task support for the first shipped prepare slice in schema, validation,
    summaries, and runner execution, including mode-branch support and validation that keeps
    docker-backed and node package-manager dependency hydration aligned with explicit
    requirements and effects
  • updated the full contract example and the widened immich pressure contract to use
    first-class prepare for registry-backed docker image hydration instead of repo-local shell
    glue
  • added a canonical orchestration model for repo-mediated execution: contracts can now declare
    top-level orchestrators, selected tasks can opt into execution.orchestrator.ref /
    execution.orchestrator.mode, and Ota ships mise as the first orchestrator for trust,
    install, and mediated task execution on the selected path
  • fixed run-path preparation env parity for selected backends: orchestrator preparation,
    toolchain fulfillment, and Corepack activation now inherit the effective backend/task env
    before execution, so container-scoped repo-manager paths such as mise trust / mise install
    can use declared context env (for example writable MISE_* paths) instead of failing under
    backend-default locations
  • fixed native ota doctor / ota up --dry-run mismatch handling for toolchains.<name>.fulfillment.source: mise
    with mode: run: when the selected path declares mise as the run-path authority, Ota now
    checks mise itself instead of blocking on an ambient host runtime version mismatch before
    selected-path fulfillment can occur
  • upgraded toolchains to the canonical capability-first model: public contracts now use
    structured fulfillment (source + mode) instead of teaching legacy provider-coupled
    toolchain shapes, while runtime compatibility still accepts legacy provider and flat
    fulfillment: run input during migration
  • updated Ota's own contract, examples, and spec docs to the new canonical model, including
    removal of managed-surface shell glue that duplicated declared toolchain truth
  • made service-task readiness budgets authoritative during startup in ota run: when a service
    task declares a projected runtime endpoint and the configured readiness start_period /
    interval / timeout / retries budget is exhausted before that endpoint becomes reachable,
    Ota now fails startup instead of waiting indefinitely until the workload exits or the user
    interrupts it
  • added structured readiness failure reporting for service startup in ota run: startup failures
    now carry the real probe budget and last probe error through terminal output and JSON-facing
    execution surfaces, and --stream readiness probes now emit live attempt progress instead of
    only a final generic readiness failure

Breaking Changes

  • Core schema/validator/spec/example surface changes must now update docs/policy/skills-sync-status.yaml with a synced ota-run/skills commit or an explicit waiver reason; the release gate enforces this discipline.
View diff on GitHub

Weekly OSS security release digest.

The CVE patches and breaking changes that affected production tools this week. One email, every Sunday.

No spam, unsubscribe anytime.

Share this release

Share on X Share on Bluesky

Track ota-run/ota](https:

Get notified when new releases ship.

Sign up free

About ota-run/ota](https:

All releases →

Related context

Earlier breaking changes

  • v1.6.16 Enforce `metadata.ota.minimum_version` at contract load time across all commands.

Beta — feedback welcome: [email protected]