Soluna Harness
[!IMPORTANT]
Soluna Harness is an early 0.1.0 release. The implementation is tested and usable from source; the npm package is prepared but not yet published.
Why Soluna?
Coding agents are good at changing files. Shipping reliable software needs more: scoped plans, explicit ownership, deterministic verification, independent review, bounded retries, cancellation, and evidence you can inspect later.
Soluna turns that engineering discipline into a reusable orchestration layer:
| Role | Responsibility | Default route |
|---|
| Sol | Architecture planning and independent final review | gpt-5.6-sol, high / xhigh |
| Luna | Repository exploration, implementation, testing, and repair | gpt-5.6-luna, max |
| Terra | Escalation after Luna exhausts its retry budget | gpt-5.6-terra, high |
What you get
- Automatic L0–L5 routing — trivial edits stay lightweight; risky work earns a real plan and review.
- Validated implementation packets — file ownership, invariants, dependencies, acceptance criteria, and structured verification commands.
- DAG-aware scheduling — independent packets can run concurrently; overlapping ownership is rejected.
- Verification as a gate — allowlisted argv execution, bounded output, timeouts, cancellation, and no shell interpolation.
- Workspace accountability — Git HEAD and content hashes detect unreported or out-of-scope edits.
- Durable runs — atomic state snapshots plus append-only worker, workspace, verification, and review evidence.
- Fail-closed safety — strict schemas, bounded context, secret redaction, symlink/traversal rejection, and ownership-safe uninstall.
- Zero project configuration by default — add
.soluna.toml only when you want policy overrides.
Quick start
Requirements
- Node.js
>=20
- An authenticated Codex CLI installation (
0.150.1 is the validated baseline)
- Access to configured planning, implementation, and escalation routes; model availability is deployment-specific
- Optional: DeepSeek Harness
0.1.x (0.1.0-rc.7 is the validated baseline)
Install from source
git clone https://github.com/Leopold-Fitz-AI/soluna-harness.git
cd soluna-harness
npm ci
npm test
npm link
Install into Codex:
node dist/cli-entry.js install --platform codex
node dist/cli-entry.js doctor --platform codex
Install into the DeepSeek Harness web profile:
node dist/cli-entry.js install \
--platform dsh \
--dsh-profile web \
--package-spec "$PWD"
node dist/cli-entry.js doctor --platform dsh --dsh-profile web
Or install both at once:
node dist/cli-entry.js install \
--platform all \
--dsh-profile web \
--package-spec "$PWD"
node dist/cli-entry.js doctor --platform all --dsh-profile web
npm link exposes the local soluna executable; remove it later with npm unlink -g @soluna-harness/install. The Codex installer creates a timestamped config backup and records every owned setting/file. The DSH installer delegates package reconciliation to dsh plugin and preserves independently managed or user-modified dependencies during uninstall.
Use it in Codex
Start a new Codex session inside a trusted Git repository:
cd your-project
codex
Then ask normally:
Implement role-based access control for the API, add regression tests,
and verify backward compatibility.
The implicit soluna-orchestration skill routes non-trivial work automatically. You can also be explicit:
Use Soluna orchestration. Have Sol produce the plan, let Luna implement and
repair it, run every required verification gate, then have Sol review the result.
Useful operational commands:
soluna doctor # validate installation and model routes
soluna status # list persisted runs
soluna status <RUN_ID> # inspect one run
soluna resume <RUN_ID> # continue a cooperative run
soluna cancel <RUN_ID> # cancel active work
Use it in DeepSeek Harness
After installing the bundle, restart the selected DSH profile. Sessions in that profile receive a scoped orchestration prompt plus ten native tools:
soluna_run soluna_plan soluna_submit_plan
soluna_dispatch soluna_verify soluna_review
soluna_resume soluna_status soluna_cancel
soluna_doctor
DSH 0.1.x provides the native Cordis tool and prompt surface. Sol/Luna/Terra execution currently uses the hardened Codex CLI backend, so Codex authentication and model access are still required.
How it works
flowchart LR
A[Request] --> B{Classify L0-L5}
B --> C[Bounded repository profile]
C --> D[Sol plan for L3+]
D --> E[Validate packet DAG]
E --> F[Luna Max implementation]
F --> G{Verification gates}
G -- fail --> H[Repair loop]
H --> F
H -- retry budget exhausted --> I[Terra escalation]
I --> F
G -- pass --> J[Sol review for L3+]
J -- changes requested --> H
J -- approved --> K[Done + persisted evidence]
Every run follows a validated state machine:
received → classified → recon → planned → ready → implementing
↓
verifying
↓
reviewing → done
↓
ready ← escalating ← repairing
Any active state → cancelled | failed
Run data lives under:
${XDG_STATE_HOME:-~/.local/state}/soluna/runs/<run-id>/
Each run contains an atomic run.json and append-only evidence logs for workers, workspace changes, verification, and reviews.
Two native integration surfaces
Codex Plugin
- implicit Skills for orchestration, debugging, review, and doctor flows;
- MCP server exposing versioned orchestration tools;
- six user-level agent roles;
- optional, non-blocking telemetry hooks;
- cooperative native dispatch plus autonomous
codex exec fallback.
DeepSeek Harness Cordis bundle
- profile-scoped package bundle;
- ten native DSH Tool definitions with runtime output schemas;
- one scoped system-prompt section;
- Cordis-fiber lifecycle and cancellation propagation;
- no sandbox, approval, credential, or shipped-preset modifications.
Both surfaces share the same schemas, scheduler, persistence, token ledger, verification engine, and safety model.
Configuration
Projects need no Soluna files. To override policy, add .soluna.toml:
version = 1
[quality]
requireTests = true
requireReview = true
forbidNewUnsafe = true
[routing]
maxWorkers = 4
plannerFromLevel = "L3"
reviewFromLevel = "L3"
[context]
softTokens = 64000
hardTokens = 128000
[roleModels]
Sol = "gpt-5.6-sol"
Luna = "gpt-5.6-luna"
Terra = "gpt-5.6-terra"
The model IDs above match the validated deployment but are not assumed to exist for every Codex account. Override roleModels with routes available in your model catalog, then run soluna doctor before starting work.
Precedence is:
built-in defaults → machine config → user config → project .soluna.toml → task overrides
CLI reference
soluna install [--platform codex|dsh|all] [--dsh-profile web] [--package-spec SPEC]
soluna uninstall [--platform codex|dsh|all] [--dsh-profile web]
soluna doctor [--platform codex|dsh|all] [--json] [--live]
soluna status [RUN_ID]
soluna run "TASK" [--cwd PATH]
soluna resume RUN_ID
soluna cancel RUN_ID
soluna serve
doctor --live performs paid, opt-in model smoke tests. Ordinary doctor checks are non-generative.
Security model
Soluna is designed to make orchestration evidence explicit, not to turn untrusted repositories into trusted code.
- Model output crosses strict Zod / JSON Schema boundaries.
- Context compilation rejects traversal, symlinks, secret-like paths, binaries, and hard-limit overflow.
- Child processes use argv arrays; verification has an executable allowlist and repository-contained cwd.
- Secrets are redacted before model/backend output is persisted or returned through status tools.
- Dirty worktrees, non-Git roots, nested Git cwd, and workspace symlinks fail closed by default.
- Installer ownership records prevent uninstall from deleting user-modified configuration or DSH packages.
Repository test/build scripts remain trusted code and execute with the host process's OS permissions. Read the complete security policy before using Soluna on sensitive code.
Verified acceptance
The current release has been exercised beyond unit tests:
- 19 test files / 57 tests passing;
- real Sol, Luna Max, and structured backend smoke checks;
- a full autonomous
Sol → Luna → verification → Sol review run;
- isolated Codex install, idempotence, doctor, MCP stdio, and uninstall checks;
- linked and packed DSH bundle installation;
- a real DSH model invocation of native
soluna_status;
- final security and product audits with no open P0/P1 findings.
See docs/ACCEPTANCE.md for the exact evidence and explicit boundaries.
Development
npm ci
npm run check
npm run lint
npm test
npm pack --dry-run
Core implementation:
src/orchestrator.ts classification, state machine, repair, review, escalation
src/scheduler.ts packet DAG validation and scheduling
src/context.ts bounded context compilation and secret redaction
src/workspace.ts Git workspace evidence
src/verification.ts structured verification runner
src/storage.ts atomic persistent state and locking
src/server.ts MCP tool surface
dsh/plugin.js native DeepSeek Harness Cordis tools
Roadmap
- Publish
@soluna-harness/install to npm.
- Add a DSH-native model execution backend alongside Codex exec.
- Expand cooperative native execution to multi-packet DAGs.
- Add richer run visualization and cost reporting.
- Validate additional operating systems and host versions in CI.
Contributing
Issues, design discussions, tests, and pull requests are welcome. Start with CONTRIBUTING.md, and please include verification evidence for behavioral changes.
For security vulnerabilities, use GitHub's private vulnerability reporting instead of a public issue.
License
MIT © 2026 Soluna Harness Contributors
