Complete bounded local-agent execution contract rollout and verification

[James3014]

Goal

Finish the bounded local-agent execution-control work so an MCP host can truthfully preflight a worker, start it with a structured execution contract, observe/reconcile physical workspace state, run configured verifiers, and distinguish provider/lifecycle failure from Candidate state without granting DevSpace routing, acceptance, approval, merge, or production authority.

Current evidence boundary

• Upstream repository: Waishnav/devspace
• Observed upstream main: b5b4ab62a8718e1186aef815538741d9402f92ba (Release v1.0.7)
• No open Issue was found for agent_preflight, agent_reconcile, workspace_verify, or the structured executionContract work.
• A locally verified implementation exists, but it is not present on GitHub/upstream. Local final reference only:
  • final commit: 8fcf11fbafcbcfc7740e761c91b7e185e0d3bf10
  • tree: 80f52358b06a8077dc60071791d9bc37869e14a5
  • prior local chain: 93287681... -> 2e2139a8... -> 38bdf6b5... -> ec025e1f... -> 8fcf11fb...
• GitHub does not resolve 8fcf11fb...; do not treat that SHA as an upstream commit.
• Current upstream main is not an ancestor of the local final Candidate. Their observed merge-base is 3bd0378b128c048add810dff00efeff4e7326eb9, so this work must be ported/rebased onto fresh main and re-verified, not blindly merged by local SHA.
• The local checkout also has unrelated pre-existing changes in src/local-agent-adapters.ts and src/local-agent-adapters.test.ts; those must not be laundered into this work.

Required behavior

1. Preflight

Expose agent_preflight for an exact workspace/profile with truthful readiness evidence.

Readiness must distinguish:

• READY
• BLOCKED
• UNKNOWN

providerAvailable/configured must not be equated with dispatch-ready. Unknown auth/provider reachability must remain unknown rather than being silently promoted or treated as a known failure.

2. Structured execution contract

agent_start should accept an optional structured execution contract while preserving existing callers. The contract should cover the current bounded controls, including:

• expectedHead
• writePaths
• maxFiles
• toolchainId
• maxWallMs
• idleTimeoutMs (observational only unless a truthful mid-run activity signal exists)

expectedHead must fail closed before worker mutation.

writePaths must not be described as hard sandbox enforcement unless writes are physically blocked. With the current local-process architecture, the truthful mode is OBSERVE_AND_ABORT.

3. Dirty-state-safe scope attribution

Scope supervision must preserve pre-existing dirty state while still detecting worker changes to the same path.

A path baseline must distinguish at least:

• untouched pre-existing dirty path
• pre-existing dirty path modified again
• newly dirty/untracked/deleted path
• index-only/stage mutation (e.g. git add with unchanged file bytes)

Do not infer worker attribution from path names alone.

If baseline/current physical identity is incomplete or cannot be read safely, degrade to UNKNOWN; do not falsely report WITHIN_SCOPE or kill a worker on unproven attribution.

Git path handling must be literal. Filenames that look like pathspec magic such as :(glob)*.txt must not cause unrelated files to contaminate per-path fingerprints.

Symlink/path inspection must not escape the workspace boundary or follow an external symlink target to read its bytes.

4. Reconciliation and lifecycle

Expose agent_reconcile so provider/session failure is separable from physical Candidate state.

A provider timeout/error must be able to reconcile to candidate.present = true when a physical diff exists.

agent_status should expose enough structured lifecycle evidence to distinguish running/stalled/terminal conditions without interpreting them as Candidate acceptance.

maxFiles must work even when writePaths is omitted; it must not become a no-op contract field.

5. Verification tool

Expose workspace_verify with a stable MCP action schema.

If a requested configured toolchain/verifier is unavailable, return a structured TOOLCHAIN_UNAVAILABLE result rather than removing the tool from the advertised surface.

workspace_verify is not read-only: it executes a configured executable with caller-supplied args and may run mutation-capable commands. MCP annotations must reflect that (readOnlyHint: false; mutation/destructive semantics as appropriate).

Do not automatically install packages, create .venv, or repair the repository environment.

Independently reproduced local regressions

The local final implementation was independently checked with paired witnesses:

• pre-existing dirty out-of-scope file modified again:
  • old behavior: worker remained running
  • repaired behavior: SCOPE_VIOLATION and worker termination
• index-only/stage mutation (git add with unchanged bytes):
  • old behavior: missed
  • repaired behavior: SCOPE_VIOLATION
• pathspec-magic-looking filename:
  • old behavior: unrelated file Git state changed the fingerprint
  • repaired behavior: fingerprint remained stable
• controller witnesses also covered tri-state preflight, STALE_WORKSPACE, request-scoped TOOLCHAIN_UNAVAILABLE, same-session continuation, timeout + physical Candidate reconciliation, and maxFiles-only enforcement.

These are local evidence only; they must be repeated against the final upstream-port Candidate.

Completion sequence

1. Port/recreate this bounded change on a fresh branch/worktree from current upstream main. Do not include unrelated local adapter changes.
2. Run the full dependency-complete verification suite on the exact ported Candidate:
   • npm test
   • tsc -p tsconfig.json --noEmit
   • tsc -p tsconfig.build.json --noEmit
   • git diff --check
3. Independently replay the key dirty-path, stage-only, pathspec-literal, preflight, stale-HEAD, toolchain, reconcile, continuation, and maxFiles behaviors on the exact Candidate.
4. Open a focused PR and bind CI/check evidence to the exact PR head SHA.
5. After merge/release, restart/reload the actual DevSpace MCP runtime and verify the host advertises the new surface (agent_preflight, agent_reconcile, workspace_verify, and agent_start.executionContract).
6. Run one real host E2E flow through the reloaded MCP: preflight -> bounded agent start -> physical progress/status -> verifier -> reconcile/cancel as needed. Confirm a worker cannot self-declare acceptance/integration authority.

Acceptance criteria

• Change is ported onto fresh upstream main without unrelated dirty/local-only files.
• Existing agent_start(workspaceId, profile, prompt) callers remain compatible.
• agent_preflight reports READY | BLOCKED | UNKNOWN truthfully.
• expectedHead fails closed before worker launch/mutation.
• writePaths behavior is truthfully labeled OBSERVE_AND_ABORT unless a real sandbox is introduced.
• Pre-existing dirty paths are not attributed to the worker when untouched.
• Re-modification of a pre-existing dirty out-of-scope path is detected.
• Index-only/stage mutation of an out-of-scope path is detected.
• Incomplete physical fingerprint evidence degrades to UNKNOWN rather than false green/false termination.
• Git pathspec-magic-looking filenames are handled literally.
• Symlink/path fingerprinting does not read outside the workspace.
• maxFiles works independently of writePaths.
• Provider timeout/error can reconcile an existing physical Candidate.
• workspace_verify is always advertised when the agent surface is enabled and reports TOOLCHAIN_UNAVAILABLE structurally when necessary.
• workspace_verify is not advertised as read-only.
• No automatic environment/package repair is introduced.
• npm test passes on the exact final Candidate.
• Both TypeScript typechecks pass on the exact final Candidate.
• git diff --check passes.
• PR CI/checks pass for the exact PR head.
• Reloaded DevSpace runtime exposes the new MCP schema to a real host.
• One real host E2E bounded-worker flow passes after reload.

Non-goals / parked work

Do not expand this Issue into:

• hard filesystem sandboxing unless separately designed and proven;
• idle-time auto-termination without a reliable mid-run activity signal;
• speculative auth/provider reachability probes that require starting a provider;
• OpenCode concurrency/server-topology redesign;
• model routing / planner authority;
• Candidate acceptance, approval, merge, or production-readiness authority inside DevSpace.

Execution / ownership

• Priority: P1 — this blocks rollout of the bounded host->local-agent workflow but does not appear to break the currently released DevSpace path.
• Frontier: READY_FOR_PORT / BLOCKED_FOR_UPSTREAM_PR until a writable fork/branch is available.
• Claim mode: manual. This touches lifecycle/security/schema semantics and requires independent verification before integration.
• Implementation realm: isolated local worktree based on fresh upstream main.
• Verification realm: dependency-complete isolated worktree plus real host/runtime verification after reload.