fix(hosted): harden provider delivery contracts (#1016)

## Summary

- preserve provider credentials, routing, and execution context through
hosted preflight and runtime boundaries
- align Codex, Claude, and OMP hosted execution, including writable temp
paths, process ownership, terminal failure semantics, and bounded
completion results
- make shipped GitHub delivery authoritative and resilient to transient
merge-state races
- harden private candidate/image packaging and add focused regression
coverage for the deployed contracts

## Deployed validation

Validated through `dev.theopenengine.com` with real provider calls, real
work, and real `--ship` delivery to
`the-open-engine/zeroshot-matrix-demo-20260812-3ebd`. Every shipped PR
merged and its repository CI passed.

| Provider / coordinator | RunIntent | Shipped PR |
|---|---|---|
| Azure OpenAI + OMP / custom | `019ffd84-61e7-7d70-b900-f74eab6a6a5c` |
demo PR 65 |
| Azure OpenAI + OMP / built-in | `019ffd8d-6159-70a3-ac33-cc3a1eeb049d`
| demo PR 67 |
| OpenRouter + Claude / custom | `019ffd9c-e8f8-7f30-a6b1-d142a54238b6`
| demo PR 72 |
| OpenRouter + Claude / built-in |
`019ffd9c-ef80-7901-b892-4b1fdaf0d244` | demo PR 73 |
| OpenAI + Codex / custom | `019ffd9c-f8e8-7070-9b16-781bba765fab` |
demo PR 74 |
| OpenAI + Codex / built-in | `019ffd9c-ff78-7791-950c-c003ba111378` |
demo PR 75 |

The targeted Azure failure rows were proven first; only then were the
four previously green rows rerun as regression guards. The accumulated
demo repository suite passes 543/543 tests. No delivery fixtures or
simulated provider results were used.

The full runtime tree was tested at `42c6cfd`; this PR was then
recomposed as one conventional commit. The only tree delta in `f3ed3fe`
is two test-fixture files (no production/runtime files). Zero-cloud main
pins `f3ed3fe`, and focused exact-head deployment run `31757758450`
completed successfully with image scan, IaC apply, and public health
checks.

## Validation

- focused completion-boundary suite: 24 passing
- private hosted preflight suite: 7 passing
- `npm run check`: green (0 errors; existing warnings only)
- Opcore staged gate: 92/92 files covered, clean
- repository pre-commit validation: green
- branch push hooks: green
- exact-head PR CI: green (one unrelated Rust timing flake passed on the
single rerun)
- zero-cloud exact-main CI:
[green](https://github.com/the-open-engine/zero-cloud/actions/runs/31757674291)
- zero-cloud exact-main full deployment:
[green](https://github.com/the-open-engine/zero-cloud/actions/runs/31757674266)

Co-authored-by: Michael Eichelbeck <michael@theopenengine.com>

Author: mkceichelbeck

.dockerignore

@@ -0,0 +1,7 @@
+.git
+.cache
+node_modules
+**/node_modules
+target
+zeroshot-rust/target
+*.log

AGENTS.md

@@ -213,7 +213,9 @@ cannot succeed. After provider success, trusted Git delivery verifies the mutati
 configuration, and that the retained revision remains an ancestor of the current target before
 pushing one deterministic-branch commit. Review delivery succeeds only with a verified open pull
 request. Ship delivery succeeds only after an authoritative merge receipt or GitHub acceptance of
-merge-method auto-merge; an open pull request alone never succeeds. The backend validates the
+merge-method auto-merge; an open pull request alone never succeeds. Transient auto-merge
+enablement failures use one bounded retry policy and re-read the exact pull-request authority
+before retrying or accepting a lost response. The backend validates the
 secret-free, versioned result, and any execution, cleanup, or delivery defect produces a closed
 failure. Keep the runtime, binary, image, and manifest private. Provider and harness interpretation
 belongs only in the Zeroshot runtime bundle and worker, never in hosting, IaC, or the run-intent
@@ -226,6 +228,9 @@ Structured-output recovery eligibility is also registry-derived: every engine wh
 capability is `true` or `experimental` must implement its provider-owned, fail-closed recovery
 adapter. Recovery always runs as a fresh nested turn with provider sessions, MCP, approval bypass,
 write-capable tools, network tools, and user-defined agents/configuration disabled.
+OMP SDK children inherit only the registry-declared non-secret configuration environment plus the
+fixed minimal process environment. Credentials remain on the private credential channel; never add
+arbitrary ambient passthrough or duplicate provider configuration lists beside the registry.
 
 Cluster Protocol Rust types are the source of truth. Files under
 `protocol/openengine-cluster/v1/` are generated projections; update them with
@@ -617,11 +622,13 @@ Cluster preflight validates the selected registry entry's `settingsValidator` wi
 Detached provider tasks default to the `detached` execution boundary. Embedding runtimes that
 already own process, filesystem, and network isolation must set
 `ZEROSHOT_TASK_EXECUTION_CONTEXT=benchmark`; the task runner validates and propagates this
-provider-neutral boundary so adapters do not attempt incompatible nested containment.
+provider-neutral boundary so adapters do not attempt incompatible nested containment. Task
+preflight and provider command preparation must share `src/task-execution-context.js`; availability
+probes must receive the same validated boundary that command preparation will use.
 
 OMP's supported version, package identity, and release asset digests are pinned once in `omp-release.ts`; the RPC codec and any registry/version-probing/Docker-build code import it. Never recopy the version string, asset names, or digests elsewhere.
 
-OMP's `rpc-stdio` invoke lane uses one shared lifecycle driver, `runOmpRpcTask` (`omp-rpc-driver.ts`), for both foreground (`contract-invoke.ts`) and detached (`task-lib/rpc-watcher.js`) execution, so the two paths produce identical result semantics. Spawn evidence is persisted (via the caller's `onSpawn` hook) before the first stdin write, and is reported only once the child process is confirmed spawned (the Node `'spawn'` event) — never synthesized from a pre-spawn/undefined pid, which would let ownership-based termination signal an unrelated process. Output is normalized-events-only: raw RPC frames, prompt text, and control payloads are never logged, only `OutputEvent`s (`omp-rpc-events.ts`). The detached watcher's prompt never enters its argv (`ps` and `/proc/<pid>/cmdline` expose argv to every local user for the watcher's whole lifetime); `task-lib/runner.js` hands it over the private, length-prefixed stdin pipe in `src/watcher-prompt-channel.js`, and the watcher fails closed — no OMP spawn, ownership-aware cleanup still runs — when that channel is absent, truncated, over the pinned 1 MiB frame contract, or closed before a complete payload. The per-task OMP config overlay (`omp-config-overlay.ts`) and its cleanup are ownership-checked by the shared `src/command-cleanup-ownership.js` owner used by both cleanup call sites; a failed or unsafe cleanup leaves the task's cleanup receipt intact (durably retryable) instead of silently discarding it. Provider `dockerIsolation`/`worktreeIsolation` capabilities are gated in `orchestrator.js` and `preflight.js` before any container/worktree is created, not after.
+OMP's `rpc-stdio` invoke lane uses one shared lifecycle driver, `runOmpRpcTask` (`omp-rpc-driver.ts`), for both foreground (`contract-invoke.ts`) and detached (`task-lib/rpc-watcher.js`) execution, so the two paths produce identical result semantics. Spawn evidence is persisted (via the caller's `onSpawn` hook) before the first stdin write, and is reported only once the child process is confirmed spawned (the Node `'spawn'` event) — never synthesized from a pre-spawn/undefined pid, which would let ownership-based termination signal an unrelated process. Output is normalized-events-only: raw RPC frames, prompt text, and control payloads are never logged, only `OutputEvent`s (`omp-rpc-events.ts`). The detached watcher's prompt never enters its argv (`ps` and `/proc/<pid>/cmdline` expose argv to every local user for the watcher's whole lifetime); `task-lib/runner.js` hands it over the private, length-prefixed stdin pipe in `src/watcher-prompt-channel.js`. Watchers are plain detached Node children with no IPC channel, so wrapper completion has exactly one lifetime owner. The watcher fails closed — no OMP spawn, ownership-aware cleanup still runs — when the prompt channel is absent, truncated, over the pinned 1 MiB frame contract, or closed before a complete payload. The per-task OMP config overlay (`omp-config-overlay.ts`) and its cleanup are ownership-checked by the shared `src/command-cleanup-ownership.js` owner used by both cleanup call sites; a failed or unsafe cleanup leaves the task's cleanup receipt intact (durably retryable) instead of silently discarding it. Provider `dockerIsolation`/`worktreeIsolation` capabilities are gated in `orchestrator.js` and `preflight.js` before any container/worktree is created, not after.
 
 OMP session persistence (issue #866): fresh runs pass `--session-dir <partition>`; verified resume
 adds `--resume <partition>/<file>` as the exact absolute path Zeroshot already verified, never a
@@ -777,7 +784,9 @@ before a task row exists. The watcher then compares the **complete** committed t
 id, full session file path (never a basename), partition and session-file inode identity, artifact
 manifest digest, and an `executionFingerprint` (`src/omp-execution-fingerprint.ts`, with generated CommonJS at the matching `.js` path) binding the
 pinned OMP release, the config-overlay content digest, the requested `--model`/`--thinking`/
-`--approval-mode` selectors, and the concrete provider/model/thinking level OMP reported. That
+`--approval-mode` selectors, and the concrete provider/model/thinking level OMP reported. OMP
+catalog aliases such as `openrouter/~anthropic/claude-sonnet-latest` are valid exact selectors;
+the `~` prefix is accepted only at the start of the model portion. That
 fingerprint has exactly one implementation, `src/omp-execution-fingerprint.ts`; do not add a second
 digest helper beside the ownership schema, where only its own unit test would exercise it and it
 could silently drift from the contract production uses. Every failed, cancelled, or uncertain
@@ -912,6 +921,28 @@ isolated followers retain a bounded complete-record tail for parsing and diagnos
 terminal settlement. Isolated settlement re-reads only a fixed-size file tail; the raw task log is
 the sole complete-output authority. Never restore whole-record watcher buffering, cumulative output
 strings, whole-log terminal reads, or unbounded provider records/events in control-plane state.
+Normal host/detached Codex tasks stay in `workspace-write`. When `cwd` is a linked Git worktree,
+task preparation may set `additionalWritableDirectories` to the one resolved external Git common
+directory and the adapter maps it to deduplicated `--add-dir` arguments only when Codex advertises
+that flag. Host/detached runs enable Codex's explicit workspace-write network capability so normal
+API, dependency, and Git journeys work without widening filesystem access. GitHub delivery rewrites
+GitHub SSH remotes to HTTPS for the push command and delegates credentials to `gh auth
+git-credential`; never embed a token in the prompt or remote. Hosted capsules declare the `docker`
+execution context and benchmark containers declare
+`benchmark`; both use `danger-full-access` because the container is the security boundary, and they
+must not receive redundant host Git-directory grants. Do not enable `danger-full-access` for host or
+detached execution, do not add unrelated cache or socket paths, and never carry either permission
+into read-only structured-output recovery.
+Successful `--pr`/`--ship` auto-cleanup may close and remove the live cluster before a foreground
+caller emits its result. The orchestrator must retain a bounded in-process final-run handoff
+(settled status, ledger snapshot, and terminal messages) until `close()`; foreground reporting must
+consume that handoff rather than reopening or querying the closed ledger.
+Claude gateway authentication may use `ANTHROPIC_AUTH_TOKEN` with `ANTHROPIC_BASE_URL` and an
+explicitly empty `ANTHROPIC_API_KEY`; keep the token, endpoint, and Claude role-model selectors in
+the provider's declared isolation passthrough rather than persisting gateway secrets in settings.
+When both gateway token and endpoint are explicit, the Zeroshot-owned per-run `--settings` safety
+overlay must set the Bedrock, Vertex, and Foundry backend selectors to `0`; this overrides stale
+ambient user backend choices while preserving the user's other settings and repository context.
 Provider terminal failures are parsed from the newest typed terminal event before generic status
 text. Raw provider diagnostics remain task-log-only; `AGENT_OUTPUT`, `failureInfo`, `AGENT_ERROR`,
 and `CLUSTER_FAILED` retain only a synthesized error plus provider/event/category/retryability and

cli/index.js

@@ -78,7 +78,10 @@ const {
   resolveEffectiveRunPlan,
 } = require('../lib/start-cluster');
 const { requirePreflight } = require('../src/preflight');
+const { resolveTaskExecutionContext } = require('../src/task-execution-context');
 const {
+  buildForegroundResult,
+  exitCodeForForegroundResult,
   exitCodeForResult,
   isForegroundStatusSettled,
   writeForegroundResult,
@@ -752,16 +755,25 @@ async function finishForegroundRun({ cluster, orchestrator, clusterId, plan, res
       plan,
       Boolean(resultPath)
     );
-    if (!resultPath) return;
-    const receipt = writeForegroundResult({
+    if (resultPath) {
+      const receipt = writeForegroundResult({
+        orchestrator,
+        cluster,
+        clusterId,
+        resultPath,
+        cancelled: foreground.cancelled,
+      });
+      process.exitCode = exitCodeForResult(receipt);
+      console.log(chalk.dim(`Result ${receipt.outcome} committed to ${resultPath}`));
+      return;
+    }
+    const result = buildForegroundResult({
       orchestrator,
       cluster,
       clusterId,
-      resultPath,
       cancelled: foreground.cancelled,
     });
-    process.exitCode = exitCodeForResult(receipt);
-    console.log(chalk.dim(`Result ${receipt.outcome} committed to ${resultPath}`));
+    process.exitCode = exitCodeForForegroundResult(result);
   } finally {
     orchestrator.close();
   }
@@ -3053,6 +3065,7 @@ taskCmd
         requireDocker: false, // Docker not needed for plain tasks
         quiet: false,
         provider: providerOverride,
+        executionContext: resolveTaskExecutionContext(),
       });
 
       // Dynamically import task command (ESM module)
@@ -3727,6 +3740,7 @@ program
           requireDocker: false,
           quiet: false,
           provider: providerName,
+          executionContext: resolveTaskExecutionContext(),
         });
 
         // Try resuming as task
@@ -5092,9 +5106,18 @@ function formatToolCall(toolName, input) {
 function formatToolResult(content, isError, toolName, toolInput) {
   if (!content) return isError ? 'error' : 'done';
 
+  let normalizedContent = content;
+  if (typeof content !== 'string') {
+    try {
+      normalizedContent = JSON.stringify(content) ?? String(content);
+    } catch {
+      normalizedContent = String(content);
+    }
+  }
+
   // For errors, show full message
   if (isError) {
-    const firstLine = content.split('\n')[0].substring(0, 80);
+    const firstLine = normalizedContent.split('\n')[0].substring(0, 80);
     return chalk.red(firstLine);
   }
 
@@ -5123,7 +5146,7 @@ function formatToolResult(content, isError, toolName, toolInput) {
   }
 
   // For success, show summary
-  const lines = content.split('\n').filter((l) => l.trim());
+  const lines = normalizedContent.split('\n').filter((l) => l.trim());
   if (lines.length === 0) return 'done';
   if (lines.length === 1) {
     const line = lines[0].substring(0, 60);

docker/zeroshot-oecp/.dockerignore

@@ -42,10 +42,7 @@
 !lib/cluster-worker/worker-internals.js
 !scripts/
 !scripts/omp/
-!scripts/omp/runtime.js
-!scripts/omp/runtime-identities.js
-!scripts/omp/runtime-lock.js
-!scripts/omp/runtime-release.js
+!scripts/omp/**
 !src/
 !src/**
 src/target/

docker/zeroshot-oecp/Dockerfile

@@ -25,6 +25,23 @@ RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund \
     && node -e "const pkg = require( \
       './node_modules/@earendil-works/pi-coding-agent/node_modules/undici/package.json'); \
       if (pkg.version !== '8.9.0') throw new Error('expected undici@8.9.0, got ' + pkg.version)"
+COPY scripts/omp/runtime-identities.js ./omp-runtime-identities.js
+RUN node -e "const fs = require('fs'); const path = require('path'); \
+      const { execFileSync } = require('child_process'); \
+      const ids = require('./omp-runtime-identities'); \
+      const platformPackage = ids.BUN_PLATFORM_PACKAGES[process.platform + ':' + process.arch]; \
+      if (!platformPackage) throw new Error('unsupported hosted Bun platform'); \
+      const platformManifestPath = require.resolve(platformPackage + '/package.json'); \
+      ids.assertPackageIdentity(platformPackage, ids.BUN_RUNTIME_VERSION, { \
+        packageJsonPath: platformManifestPath, manifest: require(platformManifestPath) }); \
+      const bunManifestPath = require.resolve(ids.BUN_PACKAGE_NAME + '/package.json'); \
+      ids.assertPackageIdentity(ids.BUN_PACKAGE_NAME, ids.BUN_RUNTIME_VERSION, { \
+        packageJsonPath: bunManifestPath, manifest: require(bunManifestPath) }); \
+      const source = path.join(path.dirname(platformManifestPath), 'bin', 'bun'); \
+      const target = path.join(path.dirname(bunManifestPath), 'bin', 'bun.exe'); \
+      fs.copyFileSync(source, target); fs.chmodSync(target, 0o755); \
+      if (execFileSync(target, ['--version'], { encoding: 'utf8' }).trim() \
+        !== ids.BUN_RUNTIME_VERSION) throw new Error('hosted Bun version drift');"
 
 FROM docker.io/instructure/tini:v0.19.0@sha256:0f9ccf2e54d010735ad691ebe670e256a3820fe8b92c28101194c68ee1216092 AS tini
 
@@ -54,7 +71,7 @@ COPY cluster-templates /opt/zeroshot/cluster-templates
 COPY lib /opt/zeroshot/lib
 COPY src /opt/zeroshot/src
 COPY task-lib /opt/zeroshot/task-lib
-COPY scripts/omp/runtime.js scripts/omp/runtime-identities.js scripts/omp/runtime-lock.js scripts/omp/runtime-release.js /opt/zeroshot/scripts/omp/
+COPY scripts/omp /opt/zeroshot/scripts/omp
 COPY src/command-cleanup-ownership.js src/omp-config-overlay.js src/worktree-claude-config.js src/worktree-tooling-env.js /opt/zeroshot/src/
 COPY protocol/openengine-cluster/v1/worker.schema.json /opt/zeroshot/protocol/openengine-cluster/v1/worker.schema.json
 COPY zeroshot-rust/hosted-node /opt/zeroshot/zeroshot-rust/hosted-node

docker/zeroshot-oecp/Dockerfile.dockerignore

@@ -42,10 +42,7 @@
 !lib/cluster-worker/worker-internals.js
 !scripts/
 !scripts/omp/
-!scripts/omp/runtime.js
-!scripts/omp/runtime-identities.js
-!scripts/omp/runtime-lock.js
-!scripts/omp/runtime-release.js
+!scripts/omp/**
 !src/
 !src/**
 src/target/