Ota v1.6.28: Secret Requirements and Linked Worktrees

Idea

Ota v1.6.28 begins V12.1: governed secret delivery.

Repositories already need to declare that selected work depends on credentials. The unsafe version of that declaration mixes intent with implementation: provider names, account identifiers, secret paths, environment values, and delivery scripts become repository-owned configuration. That makes the contract less portable and creates more places for sensitive operational truth to drift.

v1.6.28 establishes a narrower boundary. A contract can declare which selected tasks or workflows require an authentication credential, where a future delivery mechanism would make it available, and which propagation paths must remain denied. Ota derives that requirement from the exact selected closure and refuses before work begins while protected delivery truth is unavailable.

This release does not deliver secrets. It makes secret intent explicit without allowing a repository declaration, an ambient environment value, or an incomplete provider integration to be mistaken for delivery authority.

The release also removes practical sources of execution drift: container tasks can run from ordinary linked Git worktrees, Yarn 1 hydration has an explicit typed path, generated AGENTS.md ownership is safer, and Corepack-backed commands use the declared package manager instead of an ambient global shim.

Feature

Provider-neutral secret requirements

Contracts requiring Ota v1.6.28 or later can declare a secret_requirements catalog. The initial surface describes authentication credentials intended for a canonical process-environment destination and exact task and workflow recipients. It does not deliver those credentials.

This excerpt from the release fixture declares a requirement for its separately defined governed task without placing a credential value or secret locator in the repository:

metadata:
  ota:
    minimum_version: "1.6.28"

secret_requirements:
  provider_api_token:
    secret_class: authentication_credential
    purpose: external_api_authentication
    delivery:
      kind: process_environment
      variable: GOOGLE_API_KEY
    recipients:
      tasks: [governed]
      dependencies: deny
      hooks: deny
      services: deny
      helpers: deny
      containers: deny
      remote_execution: deny
      proof_observers: deny
      negative_controls: deny
      lifecycle_children: deny
    constraints:
      actor_mode: ci
      environment: test
      execution_mode: native
      target_platform: linux
      runtime_boundary: process
      capability: segmented_process_environment

GOOGLE_API_KEY names the process-environment destination, not a provider binding or proof that the credential exists. Every propagation edge is explicitly denied.

Validation rejects provider selectors, cloud projects, tenants, secret paths or versions, GitHub secret names, values, defaults, noncanonical recipients, and destinations already owned by compatibility environment or execution-context truth. The minimum-version floor prevents older Ota versions from silently ignoring the declaration.

Fail-closed command admission

Secret requirements participate in command-scoped admission for ota run, ota up, runtime and lifecycle proof, Doctor context, CI projection and re-evaluation, sandbox capability, and harness output.

When the selected closure has no secret requirement, admission remains not_applicable and existing behavior is unchanged. When it does, the current release refuses with secret_delivery_protected_truth_unavailable before setup, dependency hydration, workflow environment rendering, durable logs, services, proof artifacts, child creation, repository mutation, or provider contact.

For that fixture, ota run governed --native --dry-run --json refuses rather than previewing a runnable task. Selected fields from its JSON result keep the limit explicit:

{
  "ok": false,
  "code": "secret_delivery_protected_truth_unavailable",
  "preview_status": "BLOCKED",
  "execution_started": false,
  "secret_delivery_admission": {
    "status": "refused",
    "availability": "not_checked",
    "provider_contact": "not_attempted",
    "delivery": "not_attempted"
  }
}

An existing environment variable with the same name does not satisfy the governed requirement. Within Ota-selected execution, agents and CI cannot satisfy it with ambient values or repository-local secret-loading glue. Ota does not govern commands run outside its execution path.

Provider-free foundations, not delivery

Behind this refusal, Core can reconstruct the selected requirement, recipient closure, protected binding and source identities, adapter profile, and provider-free plan. The first sealed adapter
profile is bounded to GitHub Actions OIDC and Google Secret Manager on a Linux/x64 protected runner. These are internal foundations for a later transaction, not a usable provider integration: v1.6.28 makes no OIDC request, contacts no provider, and produces no secret-delivery receipt.

Linked Git worktrees now run in containers

Unix container execution now supports ordinary linked Git worktrees. Ota verifies Git pointer metadata and translates it through runner-owned, read-only mounts. The common Git directory follows the selected workspace access posture.

Malformed, aliased, or unsupported metadata is refused rather than allowing a container to start with host-only Git paths. The boundary is intentionally local: it relies on a protected per-user runner-state root and does not claim protection from a hostile concurrent process running as the same operating-system user.

This closes an important day-to-day gap for agents and maintainers who use isolated worktrees but still expect the contract's container lane to behave like the canonical repository execution path.

Typed Yarn Classic hydration

Typed Node dependency hydration now supports:

source:
  kind: node_package_manager
  manager: yarn
  yarn_release: classic
  frozen_lockfile: true

Ota renders yarn install --frozen-lockfile for Yarn 1 instead of modern Yarn's --immutable. Existing Yarn contracts retain their modern behavior, and incompatible Classic plus inline_builds declarations are rejected.

Native Corepack run fulfillment is tighter too. Structured task commands and typed Node hydration are dispatched through corepack <manager>, so an ambient global Yarn or pnpm shim cannot replace the declared package-manager version. Opaque shell bodies remain repository-owned and unchanged.

Safer generated agent guidance

ota agents --review and ota agents --write now recognize generated guidance only when it occupies one uniquely delimited managed block.

Duplicate, reversed, ambiguous, or stale markers no longer appear synchronized merely because matching text exists elsewhere in AGENTS.md. Write mode refuses ambiguous layouts without modifying the file, preserves ordinary prose containing marker text, migrates exact legacy generated-only files, and does not treat an unreadable existing file as missing.

ota tasks --use, including the canonical ota tasks --safe --use discovery lane, also renders task notes. Proof limits, external boundaries, and operational guidance are therefore visible before an agent chooses a runnable task.

Readiness and detection improvements

Rich output now shows a compact Ota Readiness success summary before publishing runtime endpoints. It names only the resolved listener, aggregate probe count, and observed attempt; detailed targets remain failure and retry diagnostics. JSON and plain output are unchanged.

The release also tightens several discovery and diagnosis paths:

• Optional nested .NET marker discovery skips permission-denied descendants; requested roots and selected sources still fail closed.
• source-bound candidates retain nested .sln and .csproj observations
• Taskfile helpers beginning with _ or marked internal: true stay out of runnable task truth
• repeated reusable GitHub Actions verification steps collapse into one readable inferred task
• named Actions steps with unresolved matrix or shell expressions cannot become runnable tasks
• Rust diagnosis requires comparable semantic versions; rustup-owned fulfillment still accepts stable, beta, and nightly.
• CI drift detection recognizes ota run <aggregate> --agent, but not dry-run, dependency-skipping, malformed, or shell-indirected forms.

What this does not claim

v1.6.28 does not store, resolve, request, materialize, inject, or deliver secret bytes. It does not authorize execution of a secret-requiring selected closure, contact GitHub's OIDC endpoint or Google Secret Manager, or produce positive secret-delivery evidence. A declaration proves only that the repository has made its intent reviewable; a refusal proves only that Ota stopped the selected closure at the governed boundary.

Linked-worktree translation does not provide hostile same-user process isolation. A green readiness summary does not expand the underlying probe evidence. Typed hydration does not make a networked setup lane automatically agent-safe.

These limits are part of the execution contract, not caveats around it.

Docs

Use the live references for the current contract, command, and agent-guidance behavior:

• Install Ota
• Contract Reference
• Command Reference
• Agent Quickstart
• JSON Output Reference

Release

Ota v1.6.28 is live at
ota.run/releases/v1.6.28.

Upgrade and inspect the repository's governed execution surface:

ota upgrade --version v1.6.28
ota --version --json
ota validate
ota doctor --json
ota tasks --safe --use
ota run <task> --dry-run --json
ota up --workflow <workflow> --dry-run --json

The GitHub release contains the shipped binaries, checksums, and complete patch-level changelog.

v1.6.28 makes a strategically important distinction durable: a repository may declare that selected work needs a credential without owning the provider binding, secret locator, secret value, or delivery authority. Until protected truth can satisfy that declaration, Ota refuses before work begins and says exactly what it did not attempt.

At the same time, linked-worktree container support, explicit Yarn Classic hydration, managed agent-guidance boundaries, and tighter detection make the ordinary execution path more deterministic. The result is stronger governance at both ends: clearer intent for future protected delivery and fewer ambient assumptions in the work repositories execute today.

---

Originally posted here: https://ota.run/blog/ota-v1-6-28-release-essay