Implement persistent native agent state

AGENTS.md

@@ -55,23 +55,24 @@ The `bias` initializes the mutable `AGENTS.md` in each output workspace.
 
 ## Node state
 
-Every executed output agent receives two sibling directory trees:
+Every executed output agent receives three sibling directory trees:
 
 ```text
 node/
   statespace/    # activation X becomes Y; writable during forward
-  workspace/     # persistent Parameter W; writable only during optimization
+  parameter/     # read-only canonical native agent state W
+  workspace/     # writable temporary episode fork
 ```
 
 Forward gives every output agent an independent, writable `statespace/.git`
 with one fetched local ref per input. The agent chooses the merge order,
 resolves conflicts, edits the statespace, and commits before it finishes. It
-uses a sparse,
-read-only `workspace/` checkout that contains the global model history.
-`loss.backward()` resumes the session with the permissions reversed. The agent
-commits workspace changes directly on the global candidate lineage and returns
-one directional feedback string per input. `DFM.step()` promotes the completed
-candidate model branch.
+uses a read-only `parameter/` and a writable `workspace/` episode fork with no
+model Git metadata. `loss.backward()` resumes the episode and returns one
+owner mutation proposal plus one directional feedback string per input.
+Backward accumulates proposals in `.feed` and discards the episode.
+`DFM.step()` resumes each persistent owner once with all accumulated feed. It
+updates a model candidate that HyTorch promotes atomically.
 
 `mn.Linear.reset_parameters()` delegates to `hytorch.mn.init`, just as
 `torch.nn.Linear` delegates to `torch.nn.init`. Each workspace starts with an
@@ -82,39 +83,44 @@ and data.
 Model checkpoint syntax follows PyTorch with a directory-native representation:
 `hytorch.save(model.state_dir(), path)` and
 `model.load_state_dir(hytorch.load(path))`. A StateDir fixes one canonical model
-commit and preserves the complete model Git history. It excludes feedback,
-sessions, temporary node trees, and unpromoted optimizer candidates.
+commit and preserves the complete model Git history. It includes durable
+native sessions and harness state. It excludes feedback, credentials, live
+runtime state, temporary node trees, and unpromoted optimizer candidates.
 
 Forward returns the complete committed statespace, never a special answer file.
 Do not inject Space contents into the agent prompt. Mount complete directory
-trees. `zero_feed()` clears accumulated feedback and discards an unpromoted
-candidate branch. It never deletes canonical Git history.
+trees. `zero_feed()` clears accumulated feedback and discards an incomplete
+step candidate. It never deletes canonical Git history.
 
 ## Git semantics
 
 Each Space owns its statespace repository and forward history. The private,
 global model workspace store records initialization and optimizer generations.
 Feedback is transient text.
-Workspace diffs are concrete mutations. DFM is evolutionary: it advances to
-every valid child mutation and does not roll back because one immediate result
-is worse.
+Agent-state diffs are concrete mutations. Agents never receive the private
+model repository and never create model commits. DFM is evolutionary: it
+advances to every valid child mutation and does not roll back because one
+immediate result is worse.
 
-Backward runs dependency-ready nodes with distinct workspace paths in
-parallel. Each node commits against one global candidate revision. HyTorch
-merges these commits into the global model history. Nodes that share a
-workspace path run in sequence.
+Backward runs dependency-ready episodes in parallel. Repeated execution of one
+Parameter creates separate episode forks. HyTorch does not merge these forks.
+`step()` gives all sorted feed records to the persistent owner. Each owner
+updates once. HyTorch commits all owner updates in one global candidate.
 
 ## Harnesses
 
-`hytorch.harness.Harness` is the execution base class. Built-ins are
-`hytorch.harness.pi`, `codex`, and `claude_code`; only Pi executes in v0. Pi
-uses OpenAI through the operator's Codex login or `OPENAI_API_KEY`, with
+`hytorch.harness.Harness` is the execution base class. Built-ins are `pi`,
+`codex`, `claude-code`, `opencode`, `hermes`, and `prime-agent`. Each harness
+stores its complete native profile and session inside the Parameter. A resumed
+turn returns a new opaque session tip because native compaction can rotate its
+identifier. `close()` releases runtime resources but does not delete state.
+Pi uses OpenAI through the operator's Codex login or `OPENAI_API_KEY`, with
 `gpt-5.6-terra` as the default model.
 
 One executed graph uses one harness. `model.to(harness)` moves the complete
 model before a new forward pass. Docker remains external deployment
-configuration. HyTorch uses the standard active Docker context and accepts
-`HYTORCH_PI_IMAGE` as an image override. Agent variables come from
+configuration. Container-capable harnesses use the standard active Docker
+context. Agent variables come from
 `.hytorch.env`, the global HyTorch secrets file, or `HYTORCH_ENV_FILE`. Never
 load the ordinary project `.env` automatically.
 
@@ -127,7 +133,7 @@ load the ordinary project `.env` automatically.
 - `hytorch/backward.py` — Loss and feed-Space propagation.
 - `hytorch/optim/` — Optimizer base and DFM.
 - `hytorch/space.py` — Space and lowercase `space` factory.
-- `hytorch/runtime/` — Dockerized Pi runtime.
+- `hytorch/runtime/` — packaged harness runtime assets.
 - `example/` — Terminal-Bench training and evaluation example.
 - `tests/` — offline unit tests plus an opt-in real Pi integration test.
 

CHANGELOG.md

@@ -11,6 +11,11 @@ HyTorch uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - PyTorch-shaped, directory-native model checkpoints with `state_dir()`,
   `hytorch.save()`, `hytorch.load()`, and `load_state_dir()`.
+- Persistent opaque native agent state across forward, backward, compaction,
+  optimizer promotion, and checkpoints.
+- Executable Codex, Claude Code, OpenCode, Hermes, and Prime Agent harnesses.
+- Disposable forward episode forks, accumulated owner feed, and one persistent
+  owner reducer per Parameter in `step()`.
 
 ## [0.1.0] - 2026-08-05
 

CONTRIBUTING.md

@@ -43,8 +43,9 @@ Pi uses the operator's Codex login by default. To use an OpenAI API key, export
 
 Keep each pull request focused. Add tests for behavior changes. Update
 `README.md`, `SPEC.md`, and `GLOSSARY.md` when a public concept changes. Do not
-commit credentials, `.hytorch.env`, generated model workspaces, or agent
-session data.
+commit credentials, `.hytorch.env`, or generated model workspaces. Durable
+agent sessions belong inside generated model state. Do not add them to the
+source tree unless they are explicit test fixtures.
 
 Use short commit subjects in the imperative form. Explain design decisions and
 test results in the pull request description.

GLOSSARY.md

@@ -12,26 +12,26 @@
 | `torch.nn` | `hytorch.mn` | Neural-network versus meta-network namespace |
 | neuron | agent | One output computation unit |
 | `nn.Module` | `mn.Module` | Registered owner with dynamic `forward()` topology |
-| `nn.Parameter` | `mn.Parameter` | Registered trainable workspace |
+| `nn.Parameter` | `mn.Parameter` | Registered persistent native agent state |
 | `model.parameters()` | `model.parameters()` | Iterator passed to an optimizer |
 | `nn.Linear(m, n)` | `mn.Linear(m, n)` | Dense mapping from `m` inputs to `n` agents |
-| `Linear.weight` | `Linear.weight` | Shape `(out_features,)`; one workspace per agent |
+| `Linear.weight` | `Linear.weight` | Shape `(out_features,)`; one native state per agent |
 | `Linear.bias` | workspace `AGENTS.md` initializer | Initial mutable direction for each output agent |
-| parameter value | workspace directory | Persistent instructions, code, tools, examples, and data |
+| parameter value | workspace directory | Opaque transcript, memory, instructions, skills, settings, databases, tools, and data |
 | `torch.nn.init` | `hytorch.mn.init` | In-place workspace initialization |
 | `torch.manual_seed` | `hytorch.manual_seed` | Seed workspace prior initialization |
 | autograd tape | retained execution graph | Dynamic forward provenance and saved sessions |
 | gradient direction | feedback string | Imperative direction for behavior change |
 | `.grad` | `.feed` | Accumulated downstream directions for one workspace |
 | loss tensor | `Loss` | Output Space plus terminal directional feedback |
-| `loss.backward()` | `loss.backward()` | Update candidates and propagate per-input feedback |
-| `optimizer.zero_grad()` | `optimizer.zero_feed()` | Clear feedback and discard an unpromoted candidate |
+| `loss.backward()` | `loss.backward()` | Accumulate owner feed and propagate per-input feedback |
+| `optimizer.zero_grad()` | `optimizer.zero_feed()` | Clear accumulated feed and an incomplete step candidate |
 | `torch.optim.Optimizer` | `hytorch.optim.Optimizer` | Own Parameters and update transaction state |
 | `torch.optim.SGD` | `hytorch.optim.DFM` | Gradient descent versus directional feedback mutation |
-| `optimizer.step()` | `optimizer.step()` | Promote the completed candidate model branch |
+| `optimizer.step()` | `optimizer.step()` | Reduce each Parameter once and atomically promote it |
 | learning rate `lr` | mutation temperature `temp` | Semantic update scale and sampling temperature |
 | optimizer budget | `max_tokens` | Backward agent output-token limit |
-| parameter delta | candidate workspace mutation | Proposed change made during backward |
+| parameter delta | owner mutation feed | Direction accumulated before one persistent owner update |
 | updated parameter storage | promoted global Git commit | Canonical model generation after `step()` |
 | saved forward activations | statespace commit and harness session | Context resumed during backward |
 | `state_dict()` | `state_dir()` | Immutable handle to the canonical model-state revision |

README.md

@@ -17,7 +17,7 @@ plain-language feedback.
 
 - Python 3.11 or later
 - Git
-- Docker
+- One supported agent CLI or the packaged Pi Docker runtime
 
 ### Installation
 
@@ -105,7 +105,7 @@ print(output.commit)  # immutable Git identity
 The result is another complete Git-backed directory. The agents decide which
 files to create or change, then commit their work. `output.dir` is the output
 directory. `output.commit` identifies its exact contents. Inference mode
-closes the agent sessions after the result is complete.
+closes runtime resources and discards all private agent-state changes.
 
 ### Improve the network with feedback
 
@@ -138,10 +138,11 @@ Test malformed inputs before you select an implementation.
 Keep contradictory evidence and explain how you resolved it.
 ```
 
-This lifecycle mirrors PyTorch training. `zero_feed()` clears feedback from the
-previous iteration. `backward()` resumes the agents and creates candidate
-workspace changes. `step()` promotes all completed changes as one new model
-generation.
+This lifecycle mirrors PyTorch training. `zero_feed()` clears feed from the
+previous iteration. Forward runs a disposable episode fork. `backward()`
+resumes the episode and accumulates owner mutation feed. `step()` resumes each
+persistent owner once with all accumulated feed. It promotes all updates as
+one model generation.
 
 ### Save and load model state
 
@@ -171,10 +172,12 @@ model.load_state_dir(hytorch.load("model-state"))
 ```
 
 A `StateDir` identifies one immutable model commit. The saved directory
-contains `MODEL.json`, every registered workspace, and the canonical model Git
-history. Loading is strict by default. Pass `strict=False` to permit missing or
-unexpected workspace keys with compatible shapes. The save destination must
-not already exist.
+contains `MODEL.json`, every complete native agent state, and the canonical
+model Git history. Native state can include transcripts, memories, compaction
+records, skills, settings, and databases. It never includes credentials or
+live process state. Loading is strict by default. Pass `strict=False` to permit
+missing or unexpected workspace keys with compatible shapes. The save
+destination must not already exist.
 
 ## PyTorch-shaped composition
 
@@ -199,25 +202,30 @@ directory-backed workspace for each output agent. Its physical weight shape is
 `(out_features,)`. Every output receives every input Space, so the logical
 layer is dense.
 
-The `bias` argument initializes each workspace's mutable `AGENTS.md`.
-Optimization can later add instructions, code, tools, examples, and data.
+The `bias` argument initializes each workspace's mutable `AGENTS.md`. The
+native harness and agent can later replace or extend the complete state in any
+format.
 
 ## How one agent runs
 
-Each output agent receives two sibling directory trees:
+Each output agent receives three sibling directory trees:
 
 ```text
 node/
 ├── statespace/    # activation: writable during forward
-└── workspace/     # parameter: writable during backward
+├── parameter/     # read-only canonical native state
+└── workspace/     # writable temporary episode fork
 ```
 
 During forward, the agent merges every input statespace, transforms the merged
-tree, and commits the result. Its workspace is read-only.
+tree, and commits the result. Its native transcript, memory, and other local
+state can change inside the episode, but forward never changes the Parameter.
 
-During backward, HyTorch resumes the same agent session. The statespace is now
-read-only. The agent can mutate and commit its candidate workspace. Git records
-each activation, workspace diff, and promoted model generation.
+During backward, HyTorch resumes the episode. The statespace and Parameter are
+read-only. The episode returns one owner proposal and one direction per input.
+HyTorch accumulates these proposals in `.feed` and discards the episode.
+`step()` resumes the persistent owner once and lets it update its complete
+native state from all accumulated feed.
 
 ## Harnesses and environment
 
@@ -228,8 +236,26 @@ model.to("pi")
 model.to(harness="pi", mtype="gpt-5.6-terra")
 ```
 
-The built-in harness identities are `pi`, `codex`, and `claude-code`. Only Pi
-executes in 0.1.0. Pi uses `gpt-5.6-terra` by default.
+The built-in harness identities are `pi`, `codex`, `claude-code`, `opencode`,
+`hermes`, and `prime-agent`. Pi uses `gpt-5.6-terra` by default. Each harness
+uses its native local profile and session format inside the Parameter.
+
+| Identity | Runtime | Persisted native state |
+|---|---|---|
+| `pi` | Packaged Pi SDK runtime | Pi profile and JSONL session |
+| `codex` | `codex` CLI | `CODEX_HOME`, transcript, and project memory |
+| `claude-code` | `claude` CLI | Claude config, projects, and JSONL session |
+| `opencode` | `opencode` CLI | Isolated home and all XDG state directories |
+| `hermes` | `hermes` CLI | `HERMES_HOME`, `state.db`, memories, skills, and profile |
+| `prime-agent` | `prime-agent` CLI | Profile, JSONL session, RLM children, and session artifacts |
+
+You can construct a harness when you need a custom binary, model, provider,
+or external credential sidecar:
+
+```python
+harness = hytorch.harness.CodexHarness(binary="codex")
+model.to(harness)
+```
 
 Agent variables come from `~/.config/hytorch/secrets.env`, project
 `.hytorch.env`, `HYTORCH_ENV_FILE`, and exported shell variables, in increasing
@@ -246,10 +272,9 @@ values in prompts or Git state.
 HyTorch 0.1.0 is the first public alpha release. Run agents in isolated
 environments and review agent-created changes before production use.
 
-Version 0.1.0 includes Spaces, Parameters, dynamic Module graphs, dense Linear
-layers, directional backward feedback, atomic DFM optimizer generations, and
-the Dockerized Pi harness. The `codex` and `claude-code` harnesses are reserved
-but unavailable.
+Version 0.1.0 includes Spaces, native-state Parameters, dynamic Module graphs,
+dense Linear layers, directional backward feedback, atomic DFM optimizer
+generations, and six native agent harnesses.
 
 ## Resources
 

SECURITY.md

@@ -20,7 +20,10 @@ data from the report.
 HyTorch executes coding agents against directory trees and Git repositories.
 Treat agent output and model-generated code as untrusted. Use isolated Docker
 environments. Use credentials with the least required privilege. Review
-workspace mutations before you use a trained model in a sensitive system.
+promoted native agent state before you use a trained model in a sensitive
+system. Native state can contain transcripts, tool results, memories, and
+executable files. HyTorch rejects Git metadata, escaping symlinks, special
+files, states with more than 100,000 files, and states larger than 2 GiB.
 
 HyTorch does not load a project `.env` file. Store agent variables in
 `.hytorch.env`, the global HyTorch secrets file, or the file selected by