@soluna-harness/install

Install

面向 Codex 和 DeepSeek Harness 的可审计 Sol/Luna/Terra 软件工程编排

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:Leopold-Fitz-AI/soluna-harness#bdebff3def0de2d417fd2a9753c445366c075154

兼容性与来源证明

Install 以 @soluna-harness/install 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: any
发布来源: github
Registry 更新时间: 2026/8/30

版本

0.1.0stable

2026/8/30

README

Soluna Harness

Turn one coding request into an auditable engineering run

Sol plans. Luna builds. Terra escalates. Your tests decide.

A persistent, policy-driven software-engineering orchestrator for OpenAI Codex CLI and DeepSeek Harness.

Quick start · How it works · Configuration · Architecture · Acceptance evidence

[!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

README

Soluna Harness

Turn one coding request into an auditable engineering run

Sol plans. Luna builds. Terra escalates. Your tests decide.

A persistent, policy-driven software-engineering orchestrator for OpenAI Codex CLI and DeepSeek Harness.

Quick start · How it works · Configuration · Architecture · Acceptance evidence

[!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?

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

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"

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.

Install

兼容性与来源证明

版本

相关插件

Install

README

Soluna Harness

Why Soluna?

What you get

Quick start

Requirements

Install from source

Use it in Codex

Use it in DeepSeek Harness

How it works

Two native integration surfaces

Codex Plugin

DeepSeek Harness Cordis bundle

Configuration

CLI reference

Security model

Verified acceptance

Development

Roadmap

Contributing

License

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

Soluna Harness

Why Soluna?

What you get

Quick start

Requirements

Install from source

Use it in Codex

Use it in DeepSeek Harness

How it works

Two native integration surfaces

Codex Plugin

DeepSeek Harness Cordis bundle

Configuration

CLI reference

Security model

Verified acceptance

Development

Roadmap

Contributing

License