Dev MCP: add explicit OWNER_DIRECT host-operation execution contract

[James3014]

Status / priority

P1 — DEV MCP CONTROL-PLANE CAPABILITY GAP. AUTO_CHAIN=false.

This Issue is the canonical owner for a gap reproduced on macOS while using ChatGPT -> Dev MCP -> Agy/OpenCode for a bounded host-only task. It is intentionally separate from Nexus runtime/governance and from platform-level ChatGPT/OpenAI safety policy.

Relationship: focused child/follow-up of #15. #15 owns broad Dev MCP reliability; this Issue owns only the execution-contract gap for non-repository host effects and their reconciliation.

Problem

Current agent_start execution contracts are repository/workspace-centric. They model effects through fields such as:

• expectedHead
• writePaths
• dispatchIntent.readScope
• dispatchIntent.writeScope
• exclusiveOwnership
• maxFiles

That is correct for source mutation, but it cannot truthfully represent an Owner-authorized task whose intended effects are host-only, for example:

Owner request
-> ChatGPT coordinator
-> Dev MCP
-> one worker/profile/session
-> bounded local host operation
   - invoke one authorized executable/package command
   - write only approved package/cache/runtime state outside the repo
   - optionally create one bounded long-lived process
-> reconcile exact process/files/effects

Observed example command class:

npx <package> <subcommand>

The concrete reproduction used npx @wonderwhy-er/desktop-commander@latest remote, but this Issue must not depend on that product. Acceptance fixtures should use inert local commands/processes.

Reproduced contract friction

Before worker execution, Dev MCP rejected multiple truthful attempts because:

1. a mutating dispatchIntent required exclusiveOwnership=true even though the intended mutation was host state, not repository files;
2. dispatchIntent.writeScope and executionContract.writePaths could not represent external host-only writes without inventing repository ownership;
3. removing repository write scope made the contract effectively read-only even though package/cache/process effects were intended;
4. a host-only task therefore has no clean authority shape between READ_ONLY and REPOSITORY_MUTATION.

Reconciliation confirmed the repository remained at the same HEAD and clean after the failed attempts.

A later dispatch attempt was independently blocked by the upstream ChatGPT/OpenAI safety layer before the requested remote-control-agent setup executed. That platform denial is not a Dev MCP bug and must not be bypassed by this Issue.

Goal

Add an explicit, auditable OWNER_DIRECT host-operation contract so Dev MCP can represent bounded macOS host effects without pretending they are repository writes.

Target authority shape:

Owner direct request
-> ChatGPT coordinator
-> DevSpace host-operation contract
-> one exact worker/profile/session
-> bounded host effect
-> physical host/process reconciliation
-> machine-readable receipt

This must remain separate from Nexus CapabilityPlanner, Workforce Admission, Task Cards, Candidate approval, merge/release authority, and repository mutation contracts.

Required semantics

1. Explicit effect target

Introduce a discriminated equivalent of:

effectTarget: REPOSITORY | HOST_OPERATION

or a dedicated host-operation API with equivalent semantics.

For HOST_OPERATION, repository mutation is default-denied rather than represented by fake/empty writePaths.

2. Host-operation scope

The contract must be able to bind at least:

authorityMode: OWNER_DIRECT
operationId / attemptKey
executable identity
argv / argument constraints
allowed host paths
allowed network destinations when applicable
longLivedProcess: true | false
expected process/listener identity when applicable
startup / execution / idle / total bounds

Prefer structured executable + argv matching over unrestricted shell strings.

3. Default-deny host effects

Unless explicitly authorized, deny at least:

sudo / privilege escalation
launchctl / service mutation
keychain / secret / .env reads
arbitrary home-directory writes
repository/source writes
Git mutation
shell-generated helper scripts
unbounded child processes
unbounded network access
background persistence

Host package/cache paths must be authorized separately from repository paths.

4. Long-lived process ownership

Record enough physical identity to distinguish:

worker agent process
command child process
long-lived owned process
PID
resolved executable
argv fingerprint
listener/port when applicable
start time
terminal/running/unknown state

A provider/client timeout must never imply the host process stopped.

5. Durable replay / reconciliation

Preserve DevSpace's existing attempt-identity invariant:

same operationId/attemptKey
-> exact replay reuses/reconciles prior effect
-> conflicting reuse fails closed
-> timeout/disconnect => status/reconcile before retry

Preferred surface, or exact equivalent:

host_operation_preflight
host_operation_start
host_operation_status
host_operation_reconcile
host_operation_cancel   # owned process only

If implemented inside agent_start, use a discriminated union so repository and host authority cannot be mixed ambiguously.

6. Repository independence

A host-only operation must support:

• zero repository writable paths;
• no fabricated writeScope;
• no repository-file exclusive ownership merely because host state mutates;
• optional expectedHead only when the operation semantically depends on repository source identity.

When a repository workspace is present, pre/post HEAD and dirty state should still be captured to detect unintended repo mutation.

7. Physical-effect receipt

Return a machine-readable receipt containing at least:

operation / attempt identity
workspace identity if present
worker provider/model/profile/session identity
host effect class
executable + argv fingerprint
allowed host paths
observed created/modified paths when observable
owned process identities
network scope requested/used when observable
pre/post repository HEAD + dirty state when applicable
terminal / running / unknown outcome
reconciliation state

Worker prose is not receipt authority.

Platform-policy boundary

Required ordering remains:

platform safety policy
        ↓
Dev MCP host-operation capability
        ↓
Owner-scoped execution contract
        ↓
worker/provider

This Issue must not:

• bypass ChatGPT/OpenAI platform enforcement;
• hide a blocked host operation inside a repository task;
• grant arbitrary remote-control, credential, surveillance, persistence, or privilege-escalation authority;
• infer that representable Dev MCP authority means the surrounding platform permits the effect.

A platform-level denial remains terminal.

Verification matrix

Use inert macOS-local fixtures. At minimum prove:

1. harmless read-only host command succeeds with no repository mutation;
2. bounded host write to one explicitly allowed temporary/cache path succeeds;
3. write outside the allowed host path fails closed;
4. repository write during HOST_OPERATION is rejected/reported;
5. sudo / privilege escalation is rejected absent a separate explicit authority contract;
6. one bounded long-lived test process starts, exposes exact identity, remains observable after worker turn, and can be reconciled/cancelled without killing unrelated processes;
7. timeout/transport loss does not cause blind replay or duplicate process creation;
8. conflicting attemptKey reuse fails closed;
9. exact replay/reconciliation does not duplicate a completed effect;
10. host-only operation requires no fake repository writeScope / writePaths;
11. repository HEAD/dirty state remains unchanged for host-only fixtures;
12. current repository-focused agent_start behavior and tests remain unchanged.

Do not use remote-control software as the acceptance fixture.

Acceptance criteria

• explicit host-operation authority model distinct from repository mutation;
• host-only mutation can be represented without fabricated repository scope;
• executable/argv, host paths, network, process lifetime, and forbidden effects are machine-readable;
• host process ownership and long-lived state are physically reconcilable;
• timeout/unknown outcome requires same-attempt reconciliation before retry;
• repository mutation remains default-denied and independently observable;
• existing repository agent_start contract does not weaken;
• platform safety denials remain external/authoritative and cannot be bypassed;
• focused positive/negative/replay/process tests pass on macOS.

Non-goals

• no Nexus Task Card or governed execution requirement for Owner-direct host tasks;
• no CapabilityPlanner or Workforce changes;
• no arbitrary shell/root access;
• no implicit sudo, launchd, keychain, secret, or persistence access;
• no Remote Desktop Commander-specific dependency;
• no bypass of ChatGPT/OpenAI safety policy;
• no Nexus Gateway deployment as part of this Issue.

Current reproduction evidence

• DevSpace workspace: /Users/jameschen/Workspace/Nexus-new-g5-runtime-20260911
• observed repository HEAD during reproduction: 89554746c039b03e0a9d342498fe6f05fa08e5b5
• post-reconciliation repository state: clean / unchanged
• Agy profile observed: agy-medium-implement, provider agy, model gemini-3.8-flash-medium
• the contract gap was observed before any successful host mutation
• upstream platform denial occurred separately and is out of scope

Exact next gate

DEVSPACE_HOST_OPERATION_CONTRACT_DESIGN_FREEZE

Rebind current DevSpace agent_start / execution-contract implementation, identify the smallest discriminated host-operation authority surface, freeze replay/reconciliation/process-ownership semantics, then implement with inert macOS fixtures and regression coverage.

Durable terminal marker:

DEVSPACE_OWNER_DIRECT_HOST_OPERATION_VERIFIED

Maximum claim now:

Dev MCP has a reproduced contract gap for bounded OWNER_DIRECT host-only effects: repository execution contracts cannot truthfully represent package/cache/process mutations outside the repository, while platform-level safety enforcement remains a separate higher authority.

[James3014]

Source implementation is published as PR #111 at 8e13568, stacked on safety PR #110. Primary independent acceptance includes strict macOS sandbox enforcement, 9 real inert-process lifecycle tests, 3 real MCP HTTP tests, typecheck/build and affected server/durable/control-plane checks. Package was built and inspected but is not deployed. Direct host execution honestly reports null provider identity and observedPaths=not_collected. Keep open for independent install and real intended host-operation delivery acceptance; source integration does not close runtime gates.

[James3014]

Source integration completed: PR #111 MERGED at 8c1c72a; GitHub main read back at that SHA. Safety prerequisite PR #110 merged first. Accepted host head: 8e13568. Primary repeated macOS real-process 9/9 and MCP HTTP 3/3. macOS CI retained exact baseline missing-agy dependency failure, recorded explicitly. Keep open for independent package install and real intended operation acceptance; no runtime deployment or restart performed.

[James3014]

2026-09-13 acceptance reconciliation

Canonical matrix: #15 comment 5652810667.

Current disposition: NATIVE_WITNESS_ONLY.

PR #111 already integrated the OWNER_DIRECT host-operation source. Only remaining closure gate: install/rebind the exact current macOS runtime and run an inert bounded host-operation witness covering start/status/reconcile/cancel, allowed host write/process ownership, no repository mutation, no blind replay after ambiguity, and preserved platform-safety precedence. No source redesign unless this native witness reproduces a fresh defect.