[P0] Eliminate manual-terminal escape hatches with typed operator actions

[James3014]

Problem

DevSpace can already carry a large portion of the engineering lifecycle: isolated workspaces/worktrees, bounded workers, Candidate creation, verification, reconciliation, cutover/session control, and exact-effect identity. However, many flows still terminate with an instruction equivalent to:

Owner: open Terminal and run this command manually.

That is now a recurring automation boundary, not a one-off inconvenience.

A representative current fixture is OpenSWE → OpenCLI → ChatGPT Web G0 closure. The implementation Candidate, focused tests, independent review, real Web canary, semantic_run, fresh semantic_reconcile, and zero-resend evidence all passed, but final production host activation could not be performed through Dev MCP because the target paths live outside configured repository/workspace roots. Issue #124 tracks that concrete host-scoped production activation primitive.

This umbrella issue tracks the broader product/control-plane requirement: bounded, mechanically specifiable host/operator actions should not fall back to manual Terminal work solely because Dev MCP lacks a typed primitive.

Goal

Reduce MANUAL_TERMINAL_REQUIRED to genuine human/security boundaries rather than routine engineering mechanics.

Target end state:

diagnose
→ implement
→ verify
→ accept
→ host/operator action
→ production canary
→ reconcile
→ closure

For an already-authorized bounded operation, Owner should not need to return to a Mac Terminal simply to execute a deterministic command that could have been represented as a typed, fenced, auditable action.

Non-goal

This MUST NOT become arbitrary remote shell or arbitrary home-directory write authority.

Do not add a generic run_any_terminal_command / unrestricted sudo / unrestricted filesystem mutation API.

The existing principle remains: source, accepted Candidate, installed artifact, loaded runtime and acceptance are separate evidence clocks; OUTCOME_UNKNOWN != retry permission.

Required design

1. Typed Operator Action contract

Introduce a registry/catalog of bounded operator actions. Each action should define server-side:

• action/capability id;
• exact permitted effect class;
• fixed or bounded target set;
• required authority/approval class;
• precondition/preimage schema;
• accepted Candidate/source identity schema where applicable;
• rollback contract;
• physical readback contract;
• reconciliation contract;
• claim ceiling.

The model/controller chooses an action id and supplies bounded parameters; it does not supply an arbitrary executable or arbitrary path.

2. Explicit manual-terminal blocker taxonomy

When DevSpace cannot perform an action, return a typed blocker rather than prose-only guidance.

At minimum distinguish:

HOST_ACTION_CAPABILITY_MISSING
PRIVILEGED_HUMAN_ACTION_REQUIRED
OS_INTERACTIVE_APPROVAL_REQUIRED
UNSUPPORTED_EXTERNAL_EFFECT
AUTHORITY_OR_APPROVAL_REQUIRED
BLOCKED_PREIMAGE_DRIFT

This enables measurement of which manual steps should be productized vs which must remain human.

3. Durable operation identity before consequential effect

Every effectful operator action must have a stable operation/attempt id persisted before the first possible host effect.

Transport timeout / 502 / disconnect MUST NOT authorize another execution attempt.

Required status/reconciliation outcomes should support at least:

PREPARED
NO_EFFECT
APPLIED
PARTIAL_EFFECT
ROLLED_BACK
EFFECT_UNKNOWN
BLOCKED_DRIFT

4. Exact preimage fencing

Consequential host actions must bind expected pre-state, e.g. exact SHA/version/service identity/config identity.

If physical truth differs, fail closed before mutation.

5. Transaction + rollback

Where multiple physical targets form one semantic activation:

verify preimages
→ create rollback bundle
→ prepare postimages
→ verify postimage identities
→ apply bounded transaction
→ physical readback
→ terminal receipt

On partial failure, inspect physical truth and perform only the contract-defined rollback/reconcile path.

6. Approval is separate from execution

An Owner approval or standing grant can authorize an exact operator action, but approval must not grant generic shell access.

Pairing/approval should bind the exact action family, target scope, preimage/candidate identity and expiry.

7. Capability Discovery integration

Write-capable agents should discover an existing operator-action capability before proposing another one-off deploy/activation script.

The concrete #124 host activation primitive should become the first reusable donor/fixture for this layer.

Initial operator-action families to evaluate

Do not implement all at once. Start from current repeated manual-Terminal escape hatches and add only bounded action families with clear physical contracts.

Suggested families:

1. Host-scoped production activation — child: [P0] Host-scoped production activation & reconciliation primitive #124.
2. Pinned package/runtime installation or upgrade — exact package/version/manifest only; not arbitrary npm install / pip install.
3. Bounded service lifecycle — specific registered launchd/service identity; start/stop/restart/status/reconcile, similar to current cutover donor patterns.
4. Bounded host configuration — catalogued config targets and typed fields only.
5. Credential/pairing lifecycle actions — prepare → explicit Owner approval → resume/readback, with no credential leakage.
6. Registered maintenance/repair action — only when executable/target/effect class are fixed server-side.

Human actions that may legitimately remain manual

The objective is not zero human authority. The following can remain explicit human gates when the OS/security model requires them:

• first-time macOS security/privacy UI approval;
• root/sudo or irreversible machine-wide permission elevation without a bounded approved primitive;
• new credential consent where the provider requires user interaction;
• high-risk release/production approval decisions;
• operations whose target/blast radius cannot be mechanically bounded.

The system should report these as typed PRIVILEGED_HUMAN_ACTION_REQUIRED / OS_INTERACTIVE_APPROVAL_REQUIRED, not misclassify them as missing engineering automation.

Acceptance / DoD

Contract

• No arbitrary shell/executable/path inputs for consequential operator actions.
• Each action has server-side fixed/bounded target semantics.
• Exact authority/approval and expiry are explicit.
• Stable operation identity exists before external/host effect.
• Preimage drift fails closed.
• Timeout/disconnect never becomes blind retry permission.
• Status + reconcile can distinguish confirmed no-effect, applied, partial and unknown outcomes.
• Rollback is bounded and identity-checked.
• Physical post-effect readback is required before success receipt.

Manual-terminal telemetry

• DevSpace can emit a typed manual-terminal blocker classification.
• Missing capability vs true human/security requirement are separate.
• These blockers are visible enough to identify repeated escape hatches worth productizing.

First physical fixture — #124

• Use [P0] Host-scoped production activation & reconciliation primitive #124 as the first end-to-end fixture.
• A previously accepted OpenCLI adapter Candidate can be host-activated to the three fixed production surfaces without Owner opening Terminal.
• Exact old SHA/preimage must match before mutation.
• Backup/rollback bundle created.
• User/global adapter and launcher pin postimages physically read back.
• Production long-protocol canary passes.
• Fresh semantic_run reaches terminal success.
• Fresh semantic_reconcile returns the same terminal result with zero resend.

Relationship to #124

• This issue: umbrella architecture/product gap — eliminate repeated manual-Terminal escape hatches using typed operator actions.
• [P0] Host-scoped production activation & reconciliation primitive #124: concrete first implementation/acceptance child — host-scoped production activation & reconciliation.

#124 should not be broadened into a generic shell executor. Its accepted design should instead become the first donor pattern for the typed operator-action layer.

Priority rationale

This is high priority because the current system can spend substantial effort achieving a verified Candidate and still stop one step before physical production closure solely because the final deterministic host action has no governed tool surface.

That repeatedly converts an otherwise unattended engineering lifecycle back into Owner-operated Terminal work.

The desired product property is therefore not 'Dev MCP can run more commands'. It is:

Every recurring bounded consequential operation has an explicit, typed, authority-aware, crash-consistent execution and reconciliation contract.

[James3014]

2026-09-13 concrete evidence update

The OpenSWE → OpenCLI → ChatGPT Web G0 closure work has now produced a concrete repeatable manual-terminal escape-hatch witness for this umbrella.

What is already proven before host activation

• OpenCLI submit-ack Candidate: f131c9f4533f874e311376f2e6aeb5bc50de1135
• focused regression: 4/4 PASS
• node --check: PASS
• git diff --check: PASS
• independent rereview: REVIEW_PASS
• real Browser Bridge / production profile m5c6uje4 Candidate canary: PASS
• real OpenSWE semantic flow: glob -> read_file -> record_finding
• terminal: INTELLIGENCE_COMPLETED
• outcome_unknown=false
• fresh-process semantic_reconcile: same terminal result
• zero resend: PASS

Current automation break

The only remaining G0 production-closure step is host activation of three fixed production surfaces:

• ~/.opencli/clis/chatgpt/
• global npm OpenCLI adapter under ~/.npm-global/...
• ~/.local/share/nexus-open-swe-runtime/bin/opencli-chatgpt-foreground

DevSpace can create, verify, review, commit, integrate and reconcile the Candidate, but current typed mutation surfaces cannot apply this already-bounded host activation. The fallback is one Owner Terminal command.

This is exactly the failure mode tracked by this umbrella: a deterministic consequential operation with known preimages/postimages, rollback plan, and verification contract still falls back to manual Terminal because the control plane lacks a typed operator action.

Important control observation

An attempt to delegate the final activation to a background DevSpace worker was rejected before worker start by the surrounding safety/control layer. No production mutation occurred and there is no unknown host effect. This is desirable fail-closed behavior, but confirms the missing capability.

Required product consequence

Treat MANUAL_TERMINAL_REQUIRED as a typed control-plane outcome, not prose. Repeated HOST_ACTION_CAPABILITY_MISSING outcomes should be measurable and should drive bounded primitive creation.

#124 remains the first implementation/acceptance child and should prove the pattern end-to-end without introducing arbitrary shell or arbitrary $HOME write authority.

[James3014]

2026-09-13 current confirmation

This umbrella scope is confirmed as the broader Dev MCP gap exposed by the OpenSWE/OpenCLI G0 closure work.

The target is not to give Dev MCP more arbitrary shell power. The target is to eliminate recurring Owner: open Terminal and run this command escape hatches whenever the operation is mechanically bounded enough to have:

• a fixed action family;
• exact target scope;
• exact authority / approval class;
• exact preimage identity;
• deterministic postimage / effect identity;
• rollback semantics;
• physical readback;
• same-operation status / reconciliation after timeout or transport uncertainty.

Current relationship

• [P0] Eliminate manual-terminal escape hatches with typed operator actions #125 = umbrella architecture/product requirement: typed operator actions + manual-terminal blocker taxonomy.
• [P0] Host-scoped production activation & reconciliation primitive #124 = first implementation fixture: host-scoped production activation & reconciliation for the OpenCLI adapter/runtime launcher case.

Current concrete evidence from the G0 fixture

The OpenCLI submit-ack repair has already reached:

• immutable Candidate f131c9f4533f874e311376f2e6aeb5bc50de1135;
• focused Vitest 4/4 PASS;
• syntax + diff checks PASS;
• independent rereview REVIEW_PASS;
• real OpenSWE → OpenCLI → ChatGPT Web canary PASS;
• INTELLIGENCE_COMPLETED with outcome_unknown=false;
• fresh-process semantic reconcile PASS;
• physical zero-resend evidence PASS.

Production is still intentionally unchanged because the final bounded host activation targets sit outside ordinary DevSpace workspace roots, and both direct shell mutation and delegated background-agent activation are correctly blocked.

This is therefore the exact failure family #125 should eliminate:

verified Candidate
→ verified canary
→ production host action missing typed primitive
→ MANUAL_TERMINAL_REQUIRED

Product requirement

Repeated manual-terminal fallbacks should become typed blockers, not prose-only instructions. In particular, distinguish at least:

HOST_ACTION_CAPABILITY_MISSING
PRIVILEGED_HUMAN_ACTION_REQUIRED
OS_INTERACTIVE_APPROVAL_REQUIRED
UNSUPPORTED_EXTERNAL_EFFECT
AUTHORITY_OR_APPROVAL_REQUIRED
BLOCKED_PREIMAGE_DRIFT

The engineering objective is to drive HOST_ACTION_CAPABILITY_MISSING toward zero for recurring bounded operations while preserving legitimate human/security gates.

Do not regress authority boundaries

DevSpace remains the local execution/control transport, not Nexus product truth or Completion authority. Source, accepted Candidate, installed artifact, loaded runtime, production canary and final acceptance remain separate clocks. OUTCOME_UNKNOWN != retry permission continues to apply to host/operator effects exactly as it does to external semantic effects.

#124 should remain the first child implementation and donor pattern, not be broadened into a generic shell executor.

[James3014]

2026-09-13 current evidence update — manual Terminal / operator escape hatch is a recurring Dev MCP product gap

This umbrella is confirmed by two separate current production-shaped fixtures, not only the OpenCLI activation case.

Fixture A — #124 host-scoped production activation

Nexus / OpenSWE / OpenCLI G0 reached all of the following before the final host mutation boundary:

root cause isolated
→ bounded source repair
→ focused tests PASS
→ independent rereview PASS
→ immutable Candidate f131c9f4533f874e311376f2e6aeb5bc50de1135
→ real OpenSWE → OpenCLI → ChatGPT Web Candidate canary PASS
→ INTELLIGENCE_COMPLETED
→ outcome_unknown=false
→ fresh-process semantic_reconcile PASS
→ physical zero-resend evidence PASS

The only remaining step is activation of the accepted bounded overlay to fixed host production surfaces under ~/.opencli, the global OpenCLI package, and the installed runtime launcher.

DevSpace repository/worktree mutation correctly cannot write those host paths, and bash correctly cannot be used as an unrestricted host-mutation escape hatch. A bounded background worker was also blocked before start; fresh physical readback confirmed production remained unchanged and there was no ambiguous production effect.

Therefore #124 is a valid first implementation child for this umbrella: the missing capability is a typed host/operator action, not another browser carrier or another OpenCLI transport.

Fixture B — #115 controller → GitHub PR delivery

#115 independently exposes the same higher-level failure shape:

implemented
→ independently accepted Candidate
→ branch pushed
→ controller lacks bounded PR-delivery capability
→ manual operator intervention required

This is not a host-filesystem activation problem, but the same control-plane class: a deterministic, identity-bound, externally consequential operation has no typed DevSpace action and falls back to manual tooling.

Updated interpretation

The durable abstraction should therefore be broader than host_activation_* alone:

Recurring bounded consequential operations should be first-class typed operator actions with exact authority, preimage/effect identity, readback, reconciliation, and rollback semantics.

Do not solve this by widening arbitrary shell/home/GitHub permissions.

Recommended hierarchy:

#125 typed operator actions / manual-terminal escape-hatch umbrella
  ├─ #124 host-scoped production activation & reconciliation
  ├─ #115 bounded GitHub PR delivery & reconciliation
  └─ future repeated operator-action families only when physically evidenced

Product-level acceptance metric

Add an explicit operational metric:

MANUAL_TERMINAL_REQUIRED / MANUAL_OPERATOR_REQUIRED

with typed causes such as:

HOST_ACTION_CAPABILITY_MISSING
EXTERNAL_WRITE_CAPABILITY_MISSING
PRIVILEGED_HUMAN_ACTION_REQUIRED
OS_INTERACTIVE_APPROVAL_REQUIRED
AUTHORITY_OR_APPROVAL_REQUIRED
UNSUPPORTED_EXTERNAL_EFFECT

The target is not zero human authority. The target is to drive *_CAPABILITY_MISSING toward zero for recurring mechanically bounded operations, while preserving true human/security approval boundaries.

Current claim ceiling

#124 source/candidate/canary/reconcile evidence = PASS
#124 production host activation = NOT_DONE
#115 bounded controller-owned PR delivery = NOT_CLOSED
#125 typed operator-action layer = OPEN

Do not close #125 merely because one activation or one PR is manually completed. Closure requires a reusable control-plane capability that removes the recurring need for James to return to Terminal for bounded, already-authorized engineering mechanics.