# Soluna Harness Architecture

## Planes

1. **Codex plugin plane** — plugin manifest, implicit skills, user-level custom agents, and optional guardrail hooks.
2. **DeepSeek Harness plugin plane** — one profile bundle inserts a host-plane Cordis plugin that contributes native tools and a scoped prompt section without publishing services or changing sandbox policy.
3. **MCP control plane** — versioned Codex tools around one application service; stdout is reserved for MCP protocol messages.
4. **Orchestration plane** — classification, profiling, planning, packet validation, scheduling, execution, verification, review, repair, and escalation.
5. **Persistence plane** — per-run atomic snapshots, process-safe lock files, optimistic revisions, and append-only evidence.

## State machine

```text
received → classified → recon → planned → ready → implementing
                                                      ↓
                                                  verifying
                                                      ↓
                                                  reviewing → done
                                                      ↓
                         ready ← escalating ← repairing

Any active state → cancelled | failed
```

Transitions are validated. A run is complete only after verification and any required review pass.

## Routing

The classifier is deterministic and explains its L0–L5 decision. L0 remains local. L1/L2 use a single bounded Luna packet without spending a Sol planning/review call by default. L3+ use Sol planning and review. L5 raises Sol effort to `xhigh`. Model IDs and thresholds are policy values.

## Packets and DAG

An Implementation Packet contains objective, owned files, interfaces, invariants, non-goals, dependencies, structured verification argv, and acceptance criteria. DAG validation rejects duplicate/missing/self dependencies, cycles, and concurrently runnable ownership overlap. Empty ownership is rejected; a deliberate whole-repository packet must explicitly own `**`.

Scheduler ordering is deterministic: critical-path length, priority, risk, then task ID. Independent ownership waves may execute concurrently up to `maxWorkers`.

## Context isolation

Workers receive compiled packets and explicit file references, never the parent conversation. The compiler:

- uses estimated tokens (`ceil(characters/4)`) and labels them as estimates;
- defaults to 64K soft and 128K hard limits;
- sorts inputs deterministically and records SHA-256 evidence;
- rejects absolute/traversal/symlink paths and secret/binary/oversized files;
- never recursively dumps a repository.

## Execution

`CodexExecBackend` uses `spawn` with an argv array and no shell. It supplies model, effort, sandbox, cwd, final-output schema, last-message path, JSONL telemetry, timeout, output cap, sanitized environment, and cancellation. Final JSON is validated again locally. Token usage is recorded only when emitted by Codex.

The native cooperative backend is a protocol: the front skill receives an exact dispatch and returns structured output through MCP. This avoids coupling MCP to private Codex launcher APIs while preserving the native path.

DeepSeek Harness loads `dsh/cordis.patch.yml` as a profile bundle. Its package-resolved plugin registers ten native DSH tools and one order-145 system-prompt section in the host registries. Registration is Cordis-fiber scoped and publishes no process-global service. Tool-call AbortSignals are linked to planner, worker, and verification cancellation. DSH v0.1 deliberately reuses the hardened Codex exec backend rather than pretending it can invoke DSH's private agent loop.

## Verification and workspace evidence

Verification commands are structured argv. The runner enforces repository-contained cwd, an executable allowlist, per-command timeout, bounded output, and no shell. Required gate failures prevent review/completion.

Before execution Soluna snapshots Git HEAD and content hashes for all tracked, dirty, untracked, and nonvolatile ignored paths. It compares the final workspace to the original baseline, so a worker cannot hide a new edit or an additional edit to a pre-dirty file merely by omitting it from `changedFiles`. Out-of-scope deltas force repair/failure.

## Persistence

Default state is `${XDG_STATE_HOME:-~/.local/state}/soluna`. Every run owns:

```text
runs/<run-id>/
  run.json
  workers.jsonl
  workspace.jsonl
  verification.jsonl
  reviews.jsonl
```

Atomic rename protects snapshots. A per-run exclusive lock serializes CLI/MCP/DSH writers, stale-lock takeover fails closed rather than racing a newer owner, and expected revisions reject lost updates.

## Installation

The Codex installer builds/copies a self-contained MCP bundle into a stable user data directory, writes a local marketplace layout, calls the official Codex plugin commands, merges supported settings, and stores prior/installed snapshots. Uninstall changes a setting only when its current value still equals the installed Soluna value.

The DSH installer delegates package ownership and profile reconciliation to the official `dsh plugin --profile … add/remove` interface. The npm manifest declares `dsh.bundle.patch`; activation is verified from the selected profile manifest, and no shipped agent preset is edited.

Plugin-contributed hooks are not required. Codex 0.150.1 reports `plugin_hooks` removed, so machine config owns hook registration; failures cannot bypass orchestration gates.