qriton 0.3.0

package/docs/energy.md

@@ -0,0 +1,102 @@
+# Energy Language workbench
+
+Qriton can inspect polynomial Hopfield checkpoints, stage one Energy Language edit, measure it, select the resulting checkpoint, and restore the prior revision. Use it from the terminal, `/energy` in chat, or optional agent tools.
+
+This adapter targets degree-3 checkpoints containing square `blocks.<layer>.hopfield.W` or `layers.<layer>.hopfield.W` tensors in float16, bfloat16, or float32. It uses the separately installed `qriton-hlm` Python package. For HLM5's slot-memory format and published HF releases, use the separate [`hlm` integration](hlm.md).
+
+## Setup
+
+Create a Python environment with compatible PyTorch wheels and Energy Language. The real checkpoint check used Python 3.10, PyTorch 2.6, and `qriton-hlm` 0.11.2.
+
+```sh
+python3 -m venv .qriton/energy-venv
+.qriton/energy-venv/bin/python -m pip install 'qriton-hlm==0.11.2'
+```
+
+Set the interpreter in the workspace's `.qriton/config.json`. Merge this into existing configuration:
+
+```json
+{
+  "energy": {
+    "python": "/absolute/path/to/.qriton/energy-venv/bin/python",
+    "timeoutMs": 120000,
+    "enabled": true
+  }
+}
+```
+
+`enabled` advertises the three agent tools. Direct CLI and slash commands remain available when it is false. Python packages are optional; normal coding sessions do not import Python, download checkpoints, or add Energy tool schemas by default.
+
+Review the project configuration with `qriton trust show`, then grant the reviewed fingerprint with `qriton trust grant <fingerprint>`. Project settings are applied only with a current grant; changes require review again. See [workspace configuration trust](workspace-trust.md).
+
+```sh
+qriton energy doctor
+qriton energy inspect models/model.pt
+```
+
+Place the checkpoint inside the workspace. Source checkpoints are never overwritten. The loader uses PyTorch's `weights_only=True` without falling back to unrestricted pickle loading.
+
+## Preview, apply, evaluate, restore
+
+The example script is [edit.hlm](../examples/energy/edit.hlm). This adapter accepts one command per preview:
+
+```text
+inject 0 42 0.00001
+```
+
+`inject` and `remove` take layer, seed, and strength in `(0, 0.1]`. `strengthen` takes a factor in `(1, 1.1]`; `weaken` takes a factor in `[0.9, 1)`. Factor operations scale the adapter's fixed base strength of 0.01; they do not specify a percentage change in memory quality. File I/O, arbitrary Python, multi-command scripts, and forced overrides are not part of this adapter. The full upstream Energy Language remains a separate tool.
+
+```sh
+qriton energy preview models/model.pt examples/energy/edit.hlm
+qriton energy show <proposal-id>
+qriton energy apply <proposal-id>
+qriton energy evaluate <proposal-id>
+qriton energy restore <proposal-id>
+qriton energy status
+```
+
+Preview returns a proposal ID and report, with baseline/candidate snapshots under `.qriton/energy/<id>/`. It does not activate the candidate. Reports include checkpoint and evaluation-suite fingerprints, the runtime version and source fingerprint, the exact edit, and checks on the serialized candidate's actual dtype.
+
+Apply atomically selects that candidate **within this workbench**. Subsequent `energy inspect` and `energy preview` operations on the source path use its active revision. Apply does not hot-patch the chat model, Ollama, or another serving process. The returned `activePath` identifies the edited checkpoint for a separate model loader.
+
+Restore selects the exact parent revision and checks its SHA-256 fingerprint. With multiple edits, restore the newest first. Original and candidate artifacts remain available for review. The state file retains the last 500 apply/restore events. Keep copies elsewhere if you need a long-term audit archive.
+
+Stale previews, changed snapshots, changed source checkpoints, failed checks, and simultaneous write operations are rejected. If a process is forcibly killed, its `operation.lock` may remain; remove it only after verifying that the owning process has exited.
+
+## What the checks mean
+
+Structural checks require finite weights, a nonzero relative weight change no greater than 10%, and cosine agreement of at least 0.85 on all 32 sampled dynamics endpoints. Baseline and candidate use the same starting states, seed 1729, learned beta, degree 3, and 100-iteration limit. Fixed-point convergence is reported separately. These are bounded empirical checks; a finite-step endpoint is not necessarily an attractor, and passing does not establish general memory retention or semantic correctness.
+
+Without a language evaluation suite, the report explicitly says `behavior.status: "not_run"`. An edit can pass structural checks without a demonstrated language benefit.
+
+To measure a full HLM3 language model, configure its original source directory and matching tokenizer:
+
+```json
+{
+  "energy": {
+    "modelCodePath": "/path/to/HLM3/source-directory",
+    "tokenizerPath": "/path/to/matching/tokenizer.json"
+  }
+}
+```
+
+The directory must supply `hlm3_model.py`, `model.py`, and `data_utils.py`. These are executable model implementations chosen by the user. The bridge uses strict state loading, adapting only legacy single-element scalar shapes. Vocabulary size must match, but that alone cannot establish tokenizer identity: use the tokenizer shipped with the checkpoint. Its hash is recorded.
+
+```sh
+qriton energy preview models/model.pt examples/energy/edit.hlm examples/energy/evaluation.json
+qriton energy evaluate <proposal-id>
+```
+
+The suite contains 2–20 named text cases, at least one `target` and one `control`. Each must fit within 256 encoded tokens and the model's context. It reports teacher-forced loss in nats/token, next-token IDs, and maximum next-token logit change before and after. Controls must stay within `maxControlLossIncrease` (default 0.1). Target measurements are reported, not automatically interpreted as success. Replace the example texts with a task-specific evaluation before claiming an intended behavior improved.
+
+`evaluate` reruns the stored preview suite unless another suite is provided. It does not change an existing proposal's approval report or activate anything. To approve an edit against different tests, create a new preview with that suite.
+
+## Chat and permissions
+
+The same commands work after `/energy`, including quoted paths. A direct `/energy apply <id>` or CLI invocation is an explicit user command. Plan mode blocks apply and restore.
+
+When `energy.enabled` is true, the model receives `energy_inspect`, `energy_preview`, and `energy_apply`. Inspect and preview can run in plan mode; preview only writes isolated proposal artifacts. Agent-requested apply/restore needs approval in both suggest and auto-edit modes. Full-auto authorizes it in advance. The approval shows the script and measured report and is invalidated if the preview or active revision changes.
+
+Operations have a timeout and honor cancellation. Each Python process exits after its operation. Preview failure removes incomplete artifacts and releases the lock.
+
+Manual checkpoint checks belong to a source checkout. The installed package does not include them. `evaluate` reports the saved suite. It does not by itself show that a larger edit improved the model.

package/docs/hlm.md

@@ -0,0 +1,148 @@
+# Qriton HLM integration
+
+Qriton exposes the parts of the HLM ecosystem that fit a coding workspace: local language-model inference, reviewed factual-memory edits, Energy Language checkpoint edits, and diagnostics for the memory graph's Hopfield recall policy.
+
+## What is connected
+
+| Component | Integration | Scope |
+|---|---|---|
+| [HLM5 1B](https://huggingface.co/qriton/hlm5-1b-trunk) baseline | `hlm` model import/download, inspection, completion, editable memory | Single-token exact-prompt edits with measured target/locality checks. |
+| HLM5 1B hybrid | Same loader and memory-overlay adapter | Available for comparisons; full hybrid checkpoint validation is separate. |
+| [HLM5 3B Base](https://huggingface.co/qriton/hlm5-3b-base) | Pinned sharded-safetensors import/download and FP32 completion | Inference only. Loader coverage does not establish full-model quality or editing support. |
+| [HLM5 certificate package](https://github.com/qriton/hlm5) | Upstream certificate/dose and editable-memory APIs | Separately installed; model weights remain frozen. |
+| `.hlm` programs | Text-addressed `memorize`, `correct`, `forget` through `/hlm`; numerical basin edits through `/energy` | Two explicitly separate adapters. |
+| [Energy Language](https://github.com/qriton/energy-lang) / `qriton-hlm` | Existing [HLM3 checkpoint workbench](energy.md) | Degree-3 polynomial Hopfield checkpoints; sampled structural checks and optional text evaluation. |
+| `@qriton/hopfield-anomaly` | Existing memory recall plus `memory probe` diagnostics | Embedding novelty/composition and plain-vs-Hopfield retrieval comparison. |
+| Qriton's gesture, activity, audio, CIFAR-10 and ModelNet10 models | Discoverable in `hlm catalog` with their task and compatibility status | Their sensor/image inputs do not fit the coding/text workflow. No automatic download or unsupported inference claims. |
+| [HF certificate explorer](https://huggingface.co/spaces/qriton/hlm5-energy-language) | Reference demonstration | The local integration runs in its own Python process; private prompts are not sent to the Space. |
+
+These base models are evaluation/completion tools. The coding conversation continues to use its configured instruction-following provider. Normal project facts still belong in the persistent memory graph; a one-token HLM edit is a different, narrower capability.
+
+## See the memory edit
+
+Start with `/capabilities` in chat or `qriton capabilities` in a shell. This overview reads configuration and workspace metadata only: no provider requests, Python startup, downloads, model loading or memory-store writes. An installation manifest is labeled as metadata, not proof that the runtime or weights are ready. The banner links to this overview and reflects whether project memory and HLM agent tools are enabled.
+
+Three capabilities serve different purposes:
+
+| Layer | Useful for | How to inspect it |
+|---|---|---|
+| Persistent memory graph | Project decisions and facts across coding sessions; links, corrections and restorable forgetting | `/memory`, `/recall <query>` |
+| Hopfield recall over embeddings | Inspecting novelty and mixtures of stored patterns when compatible vectors are available | `/memory probe <query>` |
+| HLM5 editable memory | Controlled single-token edits to a local frozen model, with measured acceptance and rollback | `/hlm preview`, `/hlm compare`, `/hlm evaluate`, `/hlm restore` |
+
+After the optional runtime and 1B model are installed, compare a prompt before and after an approved edit:
+
+```sh
+qriton hlm compare hlm5-1b "The capital of Veldoria is"
+qriton hlm preview hlm5-1b examples/hlm/memorize.hlm examples/hlm/controls.json
+qriton hlm show <proposal-id>
+# If the preview passed and you want to activate this edit:
+qriton hlm apply <proposal-id>
+qriton hlm compare hlm5-1b "The capital of Veldoria is"
+qriton hlm evaluate <proposal-id>
+qriton hlm restore <proposal-id>
+qriton hlm compare hlm5-1b "The capital of Veldoria is"
+```
+
+`compare` returns `base` and `active` next-token text, IDs, margins and full-logit hashes, the active revision, and `changed` flags plus the maximum absolute logit difference. It evaluates both variants in **one model load**, preserves the overlay, and uses the same workspace lock, asset verification and runtime binding as prediction. With no overlay, both predictions are identical. The 3B inference-only model also supports comparison without an editable overlay. Results describe one prompt; `evaluate` checks the proposal's saved controls and retained facts. Neither command establishes broad language understanding or improved coding performance.
+
+In chat, `/hlm compare` displays a short frozen/active comparison and the next evaluation command. The shell command preserves the full JSON report, including runtime fingerprints and logit hashes, for inspection or scripting.
+
+When HLM agent tools are enabled, the assistant can call `hlm_inspect` with `action: "compare"` and explain the result alongside the saved evaluation. HLM is loaded only for the operation and released afterward. Discovery does not enable these tools or change your coding provider. OpenAI can continue handling coding while the optional HLM workbench is used on demand.
+
+Exact-prompt checks cover one target, retained facts and unchanged controls. They are not a measure of general coding quality. The upstream [HLM5 research and limits](https://github.com/qriton/hlm5) describe the certificate mechanism and its operating scope.
+
+## Install the optional runtime
+
+Install the upstream `hlm5` package and its dependencies in a Python environment. The tested local environment uses Python 3.10 and PyTorch 2.6. A separately checked-out upstream source directory can be selected explicitly:
+
+```sh
+git clone https://github.com/qriton/hlm5.git .qriton/hlm-runtime
+git -C .qriton/hlm-runtime checkout 46d00c55a47f8542f65ca7dcd1b4c464aeb33003
+python3.10 -m venv .qriton/hlm-venv
+.qriton/hlm-venv/bin/python -m pip install ./.qriton/hlm-runtime safetensors
+```
+
+```json
+{
+  "hlm": {
+    "enabled": true,
+    "python": "/absolute/path/to/venv/bin/python",
+    "sourcePath": "/absolute/path/to/hlm5-repository",
+    "timeoutMs": 180000
+  }
+}
+```
+
+The interpreter needs `torch`, `tokenizers`, and, for 3B, `safetensors`. `sourcePath` contains the upstream `hlm5/` package. It can be empty if that package is already installed in the interpreter. Model code is executable code selected through this configuration; the downloader fetches model data, tokenizer, documentation and license files, not Python source.
+
+When using `.qriton/config.json`, review it with `qriton trust show` and grant its fingerprint with `qriton trust grant <fingerprint>` before running the commands below. Editing that file requires a new grant. See [workspace configuration trust](workspace-trust.md).
+
+```sh
+qriton hlm doctor
+qriton hlm catalog
+qriton hlm fetch hlm5-1b
+# Or use a local HF release snapshot with matching files:
+qriton hlm import hlm5-1b /path/to/local/release
+qriton hlm inspect hlm5-1b
+qriton hlm predict hlm5-1b "The history of computing began" 16
+```
+
+Available IDs are `hlm5-1b`, `hlm5-1b-hybrid`, and `hlm5-3b`. Each download uses a pinned HF commit and verifies every file's size and SHA-256. The manifest is checked against Qriton's bundled catalog, and files are reverified before use. Failed or cancelled installations leave no installed partial model. An existing installation is checked and reused without overwriting it.
+
+Files live under `.qriton/hlm/models/`. A 1B release needs about 4.2 GB of disk; 3B needs about 10.8 GB. FP32 inference also needs substantial RAM. Loading uses memory mapping and meta-device initialization to avoid a second full model allocation. Heavy model operations are serialized within a workspace, and each process exits when its operation finishes. The release's included `LICENSE` describes its use terms.
+
+After a forced process termination, `.qriton/hlm/operation.lock` can remain. Remove it only after verifying that the recorded process has exited.
+
+## Edit factual memory with `.hlm`
+
+The HLM5 workbench defines a text-addressed `.hlm` dialect:
+
+```text
+memorize "The capital of Veldoria is" " Paris"
+```
+
+The leading space is part of the target. The tokenizer must encode it to exactly one token. `correct` updates an existing prompt address, and `forget` deactivates it. These operations each require a separate preview. They do not assert that the model learned a general concept or can answer paraphrased questions.
+
+The supplied [control suite](../examples/hlm/controls.json) includes a paraphrase and unrelated prompts. Replace or extend it for the intended task. A suite requires 2–16 distinct controls; the edit prompt cannot be one of them.
+
+```sh
+qriton hlm preview hlm5-1b examples/hlm/memorize.hlm examples/hlm/controls.json
+qriton hlm show <proposal-id>
+qriton hlm apply <proposal-id>
+qriton hlm predict hlm5-1b "The capital of Veldoria is"
+qriton hlm evaluate <proposal-id>
+```
+
+Use [correct.hlm](../examples/hlm/correct.hlm) and [forget.hlm](../examples/hlm/forget.hlm) in later previews to exercise corrections and forgetting. `memorize` rejects duplicate active addresses; `correct` and `forget` require an existing address. Already-predicted targets and unreachable targets are refused. Expensive residual-synthesis rescue is not run automatically.
+
+Preview uses the upstream float64 reachability certificate and dose selection, then tests the serialized FP32 memory overlay through the full model. Activation requires:
+
+- The requested token wins with a positive measured margin, or forgetting restores the original logits at that prompt.
+- Every remaining active fact still predicts its stored target with a positive margin.
+- All supplied controls have bit-identical logits to both the parent revision and the frozen trunk.
+
+The adapter uses upstream degree-5 memory, temperature 0.10, and gate threshold 0.95. First-edit prompt/control hidden states provide pooled ZCA calibration, which remains frozen across revisions. This calibration choice is recorded; it is not an exact reproduction of the paper's multi-fact calibration dataset. A certificate alone is insufficient for activation: measured FP32 behavior must also pass.
+
+Apply selects the overlay used by subsequent `hlm predict` calls. Snapshots contain the editable memory and calibration, not another copy of the large base model. Previews and receipts bind the script, model manifest, runtime/adapter code, controls, parent and candidate fingerprints. `evaluate` repeats the saved checks without changing the original activation decision.
+
+```sh
+qriton hlm restore <active-proposal-id>
+qriton hlm status
+```
+
+Restore newer revisions first. Restoring the first revision returns to the frozen trunk. `forget` and restore retain historical snapshots for audit and recovery; they are not secure deletion. This workbench supports up to 32 fact addresses in an overlay. Stale proposals, changed artifacts, model assets or runtime implementations are refused.
+
+Commands also work after `/hlm` in chat. `hlm.enabled` exposes three agent tools: inspect/predict, preview, and apply/restore. Agent activation requires approval in suggest and auto-edit modes. Plan mode permits inspection and isolated previews, but blocks model installation and activation. Explicit CLI/slash apply commands are direct user instructions.
+
+## Inspect associative recall
+
+```sh
+qriton memory probe "Which conventions apply to our API tests?"
+```
+
+Or use `/memory probe <query>` in chat. The diagnostic compares plain and Hopfield recall over the same stored graph, query embedding and limits. It reports selected memories, added/removed results, energy, novelty, composition and the resulting recall policy. It does not reinforce memories or change the configured policy. Embedding requests use the existing configured embedding backend.
+
+These readings describe embedding geometry. They do not measure factual truth or establish an HLM-specific retrieval advantage. Missing/incompatible embeddings leave keyword/graph recall available.
+
+Manual model checks belong to a source checkout. The installed package does not include them. A successful exact-prompt edit does not change the coding model.

package/docs/network-policy.md

@@ -0,0 +1,76 @@
+# Network policy
+
+Network settings belong in user configuration (`~/.qriton/config.json`, or `$QRITON_HOME/config.json`) or the launcher-managed file selected by `QRITON_POLICY`. A project configuration cannot set `network`, even after a workspace trust grant. `qriton doctor policy` and `/policy` show both policies without contacting a provider. Restart after changing policy.
+
+Every applicable policy must allow a request. Managed limits can restrict user preferences but cannot expand a user's local-only setting. Project configuration may still select endpoints after review; those endpoints must pass the network policy.
+
+## Local services only
+
+Merge this into your user configuration:
+
+```json
+{
+  "network": {
+    "mode": "local-only",
+    "allowHostedFallback": false
+  }
+}
+```
+
+This permits configured HTTP services on loopback IP addresses or exact `localhost`. `localhost` is pinned to loopback without DNS. Public endpoints and LAN addresses are refused before transport. Local Ollama and compatible local API servers remain usable. Selecting a hosted model explicitly does not override this setting.
+
+Local-only describes Qriton's direct connections. An allowed local server can itself contact external services. Run a trusted local service with its own offline settings and OS/firewall controls when complete machine-level isolation is required. Qriton blocks recognized Ollama `:cloud` models and delegated model pulls in restricted modes, but cannot determine the internals of an arbitrary allowed server.
+
+## Approved origins
+
+For a managed deployment, set `QRITON_POLICY` to an absolute path outside the workspace containing, for example:
+
+```json
+{
+  "version": 1,
+  "allowedModes": ["suggest", "auto-edit", "plan"],
+  "network": {
+    "mode": "allowlist",
+    "allowedOrigins": [
+      "http://127.0.0.1:11434",
+      "https://api.anthropic.com"
+    ],
+    "privateOrigins": [],
+    "allowHostedFallback": false
+  }
+}
+```
+
+Origins include scheme, host, and port. Paths, query strings, URL credentials, and wildcards are rejected. An empty allowlist denies every HTTP request, including loopback. Each redirect destination needs its own grant. For HLM downloads, grant the pinned release's host and the actual CDN origin if required; a denied redirect reports its origin without printing the signed query.
+
+`privateOrigins` permits a named origin to resolve to private/reserved addresses. It does not bypass `allowedOrigins` or local-only mode. Every applicable policy must grant the private destination. Configured loopback services are the exception: they do not need a separate private-origin entry, but still require an allowlist entry when using allowlist mode. General web fetching requires a private-origin entry even for loopback, preventing model-supplied URLs from reaching local services by default.
+
+## Explicit Ollama discovery and selection
+
+`/servers local` checks loopback only. `/servers scan` probes at most 255 attached private IPv4 addresses on port 11434. Only credential-free GET requests to `/api/version` and `/api/tags` are permitted through this discovery path; redirects, query strings, arbitrary ports, public addresses and generation requests are refused. The unrestricted profile grants these two metadata reads for that operation only. Discovery does not add a permanent private-origin grant or select a server. Local-only and allowlist restrictions continue to apply, including every managed-policy layer.
+
+Selecting a server with `/server <url>` verifies it and stores its origin as the personal Ollama preference. A selected private IPv4 origin is added to the user's `privateOrigins`; managed policy must already permit it. Only the Ollama client may use credential-free HTTP on that trusted origin. Normal authenticated services retain their HTTPS requirement. Hostnames for remote services should use HTTPS and need the usual private-origin grant if DNS returns private addresses. The network scanner itself uses IP literals, so it performs no reverse DNS or service-name guessing.
+
+LAN HTTP traffic is unencrypted. Selecting a server makes it the destination for subsequent Ollama prompts, tools and embeddings. Discovery sends none of those. Use a trusted machine/network or an HTTPS server for sensitive content.
+
+## Fallback and upgrade changes
+
+The default mode is `unrestricted`, which permits public HTTP(S) destinations and the configured loopback services. It retains the address and redirect checks below. It does not confine subprocess networking.
+
+Automatic hosted fallback is now **disabled by default**. A missing local chat model no longer selects a hosted model because a key happens to exist. Failed local embeddings fall back to keyword retrieval. Explicit `--model`, `/model`, and `fastModel` choices still work when their endpoints are allowed.
+
+To opt into automatic hosted chat, fast-model and embedding fallback, set `network.allowHostedFallback` to `true` in user configuration. A managed network policy must also permit it. Local-only mode always forbids it. When using a hosted chat model with fallback disabled, configure a usable `fastModel` explicitly for compaction and memory capture.
+
+Remote service endpoints now require HTTPS. HTTP remains supported for loopback development servers. Move an existing LAN HTTP service behind an HTTPS endpoint and grant its private origin in every applicable policy. OpenAI-compatible chat and embedding requests use the configured `providers.openai.baseUrl`; `OPENAI_BASE_URL` remains the environment default. Anthropic requests are fixed to `https://api.anthropic.com`; SDK-only endpoint environment overrides are not honored.
+
+## What is enforced
+
+- Chat, fast-model calls, provider discovery, embeddings, search, fetched pages, key validation, and HLM downloads use the shared transport. It rechecks configuration trust and managed-policy fingerprints at request boundaries in the CLI.
+- URLs are canonicalized before checking. Private, loopback, link-local, shared-address, multicast and reserved ranges are denied by default for general web access. IPv6 global addresses are conservatively restricted. DNS checks every returned address; the connection receives those exact approved answers, preventing a second lookup between checking and connecting.
+- Authenticated/service requests are bound to one configured origin and do not follow redirects. General web/download redirects are checked individually, limited to five, and cannot downgrade HTTPS or forward POST bodies to another origin.
+- Policy errors propagate to the UI and headless stderr. Cancellation remains active during response streaming. Connections are closed after requests and destroyed when the CLI session ends. Explicit per-request dispatchers do not use ambient proxy dispatchers; proxy-based deployment is not a supported policy profile yet.
+- `local-only` and `allowlist` block unconfined shell commands, Git commands, HLM/Energy Python execution, Ollama auto-start, model pulls, and recognized cloud-model delegation. Approval and `--yolo` do not bypass these checks. Local file tools and stored-session operations remain available.
+
+The [container profile](production-operations.md) permits shell, Git and Python in restricted modes with no container network and one workspace mount. Host processes, delegated downloads and service auto-start remain blocked. This does not sandbox other software, allowed services or trusted launcher/credential-store helpers. Untrusted Node preload code, replacement executables or a modified CLI can bypass application controls; protecting the launcher and installation is an operator responsibility. In-flight requests are not retroactively revoked when a policy file changes; subsequent requests fail and require restart. Memory scope enforcement and durable agent-tool records are described in the same operator guide.
+
+The HTTP client uses pinned `undici`. Its [Agent connection options](https://github.com/nodejs/undici/blob/v7.29.1/docs/docs/api/Client.md) provide the DNS lookup hook needed to validate and connect to the same addresses while retaining Node's streaming fetch and TLS handling. This avoids implementing a second HTTP/TLS stack. Programmatic integrations must use `withNetworkPolicy`; the CLI also binds the policy for terminal callbacks created outside the async session.

package/docs/production-operations.md

@@ -0,0 +1,107 @@
+# Managed CLI deployment and recovery
+
+This profile targets Linux developer machines and macOS with a local Linux Docker engine. It is a release candidate implementation, not an enterprise certification. Windows process isolation is not supported. Each developer owns a separate private `QRITON_HOME`; a shared multi-tenant service is outside this profile.
+
+## Installation and policy
+
+Use Node 22.16+ on the 22.x line or Node 24+. Install a versioned package prefix and keep the previous package for rollback.
+
+Set `QRITON_POLICY` in the managed launcher to an absolute file outside all project workspaces. Protect the launcher, policy, Qriton installation and Docker configuration using device administration. Repository configuration cannot set network, execution, Shield or memory access policy. A user with administrative control of the host can bypass these application controls; this is not multi-tenant isolation.
+
+Example managed policy (replace the image placeholder with the approved digest):
+
+```json
+{
+  "version": 1,
+  "allowedModes": ["suggest", "auto-edit", "plan"],
+  "allowProjectConfig": true,
+  "network": { "mode": "local-only", "allowHostedFallback": false },
+  "execution": {
+    "mode": "container",
+    "image": "sha256:REPLACE_WITH_64_HEX_DIGITS",
+    "dockerContext": "default",
+    "memoryMb": 2048,
+    "cpus": 2,
+    "pids": 128
+  },
+  "memoryAccess": {
+    "readGlobal": true,
+    "writeGlobal": false,
+    "readOtherProjects": false,
+    "writeOtherProjects": false
+  },
+  "shield": { "mode": "warn", "blockCredentials": true }
+}
+```
+
+Review project settings with `qriton trust show`, then grant the exact reviewed fingerprint. Use `qriton doctor policy` to inspect the resulting boundaries. Keep keys in the supported credential store, outside the workspace. Credentials typed into prompts or committed to project files are not made safe by this profile.
+
+## Container execution
+
+Build the supplied toolchain image and inspect its immutable ID:
+
+```sh
+docker build -f containers/runner.Dockerfile -t qriton-runner:review containers
+docker image inspect qriton-runner:review --format '{{.Id}}'
+```
+
+Review and scan the image before approving its digest. The Dockerfile pins the base image; distribution package repositories can change between builds. The resulting image digest is the deployment identity. Maintain your own approved toolchain image when additional packages or pinned package snapshots are required. Runtime pulls are disabled.
+
+The current toolchain uses a pinned Debian 13/Node 24 base and npm 12.0.2 with explicit compatible dependency updates for `brace-expansion`, `ip-address`, `tar` and `undici`. npm's development-only package declarations are removed before applying those runtime patches. Review these maintained changes as part of the image, and remove them only after a scanned upstream npm release includes the fixes.
+
+Scan the built image before approving its digest. Export it with `docker image save` and scan that archive, so the report matches the image you will run. Record the scanner version, database metadata, image digest and findings. A result with no fixable findings does not approve findings the scanner lists without a fix.
+
+The runner accepts only local Unix-socket Docker contexts. Each command runs as a non-root UID with no network, no additional capabilities, no privilege escalation, a read-only root filesystem, private temporary directories, process/memory/CPU limits and one writable bind mount: the canonical workspace at its original absolute path. Host home, credential stores, SSH agents and Docker sockets are not mounted. The image must provide GNU `/usr/bin/timeout` for an independent deadline if the CLI crashes. Docker's default seccomp and namespace isolation remain enabled. The local Docker daemon and approved image are trusted parts of this boundary.
+
+The agent's approved provider HTTP calls remain in the host CLI and obey the HTTP policy. Container commands cannot reach those providers or any other network. Prepare dependencies before using this profile; network-dependent installation commands fail. Python/HLM dependencies must be installed in the image, and required model/code files must be available inside the selected workspace. A missing engine, image, interpreter, or dependency fails without falling back to host execution. The minimal supplied image does not include PyTorch or an HLM runtime.
+
+Host mode remains available for compatibility and is the default. Its children receive a small allowlisted environment and temporary home; user/global Git identity and package-manager credentials are consequently not inherited. Host mode is not an OS sandbox and remains blocked by restricted network policy. Use container mode for a managed deployment. A selected subdirectory cannot grant Git access to its parent repository; select the intended repository root explicitly.
+
+Cancellation removes the named container. GNU timeout bounds work even if the client is killed. An unavailable daemon can prevent immediate cleanup; inspect it before resuming. List unfinished containers with:
+
+```sh
+docker ps -a --filter label=com.qriton.execution=1
+```
+
+Git status/diff and startup branch detection use a read-only workspace mount. Git read tools disable repository fsmonitor, external diff and text-conversion helpers. Commit operations retain hooks and receive a writable mount.
+
+Inspect the command, creation time and workspace mount before removing a specific abandoned container. Never remove all containers on a developer's machine as a recovery shortcut.
+
+## Memory authorization
+
+The CLI binds each MemoryStore to the canonical workspace scope. Defaults allow reading global notes, writing the current workspace, and no access to other projects. Explicit user preferences can allow broader access only when the managed policy also allows it. Writes require read permission.
+
+SQLite views filter readable nodes, edges and history before query limits; triggers constrain writes and both ends of graph links. These restrictions cover direct IDs, `all_projects`, forgotten notes, FTS/vector recall, Hopfield construction, UI commands and background work. Recall does not reinforce read-only global facts; reembedding and sweeping skip scopes without write permission. Cross-scope modifications fail and multi-statement forget/supersede operations roll back on failure. Existing memories are retained. Workspaces previously opened through an alias may need an operator-reviewed migration to their canonical path scope.
+
+This does not prevent an unrestricted host shell or the developer account from opening the database directly. Use the container profile and private state location for the managed boundary. Cross-scope links created by older unrestricted clients can require authorized maintenance before deletion.
+
+## Operations and interrupted work
+
+`qriton operations [limit]` prints durable agent tool intents, approval denials and outcomes. Records contain timestamps, action/effect/mode, session ID, process ID, workspace hash and argument hash. They omit argument bodies, tool output and prompts. Hashes are identifiers, not encryption; predictable values can be guessed. Limit sharing accordingly.
+
+The journal uses SQLite WAL with FULL synchronous commits. Intent must commit before a tool starts; inability to record completion stops the turn with an uncertain-outcome message. `running` means the outcome is unknown and needs inspection, including when a process crashed. A failed tool can have partially changed files. Never automatically replay an unfinished action. Check the owning process, containers, `git status`/diff, session recovery branch, and HLM/Energy state before deciding what to do.
+
+This journal covers agent tool execution and approval denials. It is not a comprehensive OS audit: direct human CLI/slash commands, background memory maintenance, provider requests and external services retain their own logs/state. Local records are editable by the machine owner and do not provide independent tamper evidence. Preserve them with the backup procedure; establish external retention/export requirements before any regulated rollout. There is no automatic record deletion in this release.
+
+HLM/Energy operations now use persistent SQLite lock databases whose OS locks release when a process dies. Do not delete `operation.sqlite` while any writer may exist. Legacy `operation.lock` files deliberately block work until the prior owner's exit and model state have been inspected. Atomic metadata and sessions flush files and containing directories before acknowledging writes. Memory writes use FULL synchronous commits. These are durability mechanisms, not evidence of power-loss testing on every filesystem.
+
+## Backup and restore
+
+Stop all Qriton writers for a coordinated backup. The built-in command creates consistent individual SQLite snapshots with `VACUUM INTO` (including committed WAL data), atomic session-file copies, and usage records. Cross-resource transactions are not promised while writers remain active.
+
+```sh
+qriton backup create /private/backups/qriton-2026-09-21
+qriton backup restore /private/backups/qriton-2026-09-21 /private/state/qriton-restored
+```
+
+Both destinations must be new directories outside the source and workspace. Restoring validates allowed paths, sizes, SHA-256 hashes, database integrity/version/required tables and session records. It never overwrites an existing home. An interrupted restore carries `.restore-incomplete`; Qriton refuses to activate that directory. Keep the original home and restore again into a fresh destination.
+
+Backups exclude credentials, trust grants, user/managed configuration, debug logs, workspace files, model weights and HLM/Energy proposal artifacts. Back up the workspace and its `.qriton/hlm`/`.qriton/energy` directories separately while stopped, preserving their relative layout and hashes. Protect backup media: transcripts and memories may contain confidential text, and this format is not encrypted or authenticated against an attacker who can rewrite both files and manifest. Built-in limits are 128 MB/file, 512 MB total and 10,000 files; larger deployments need operator-managed consistent snapshots.
+
+After restoration, restore reviewed policies/configuration and credentials separately, grant workspace trust again, then select the new `QRITON_HOME` in the launcher. Verify sessions and memory before allowing changes. Newer schema versions are rejected instead of being downgraded in place.
+
+For incidents, capture `qriton doctor support` and relevant operation IDs. That command stays offline and omits prompts, code, keys and environment dumps. Review even minimized reports before sharing. Preserve the failed state and backup; do not paste transcripts or raw databases into public issues.
+
+## Rollback
+
+Stop writers, snapshot the current state, install the previous package into a separate prefix and point the managed launcher back to it. If it cannot read the current schemas, restore a compatible backup into a new home. Keep the only copy of existing state intact. Re-run offline diagnostics before resuming.

package/docs/session-recovery.md

@@ -0,0 +1,35 @@
+# Session saves and recovery
+
+Qriton saves the conversation after each turn and before clearing, switching sessions, or quitting. Files live in `$QRITON_HOME/sessions` (normally `~/.qriton/sessions`). Existing version-1 JSON sessions remain readable without a migration.
+
+## Two terminals continuing the same session
+
+Each loaded session carries a fingerprint of its exact file contents. Before replacing the file, Qriton checks that fingerprint under a cross-process write lock. A stale save cannot replace a newer save or recreate a deleted session under its original ID.
+
+If another writer changed or deleted the file, Qriton saves the current conversation under a new ID. The original file stays as it is. A warning prints both IDs, and the new session has a `Recovered:` title and a `recoveredFrom` field. Subsequent turns continue the new branch. This preserves the two histories separately; it does not merge them.
+
+Use `/sessions` and `/resume <id>` interactively, or `qriton sessions` and `qriton --resume <id>` from the shell. Use the ID from the recovery warning when selecting a particular branch; `--continue` selects the most recently updated session in the workspace.
+
+## A save fails
+
+Disk errors, unavailable storage, and lock contention are reported visibly. The last successfully saved file remains available if failure occurs before atomic replacement.
+
+In the interactive UI:
+
+1. Keep Qriton open. The current conversation remains in memory.
+2. Fix the reported storage problem, or let the other writer finish.
+3. Run `/save`. A successful retry prints the saved session ID.
+
+An unsuccessful save prevents `/clear`, session switching, and normal quit from discarding the current conversation. A new turn first retries the failed save. Quitting after a save failure leaves the UI open so you can retry. Force-killing the process still loses unsaved in-memory work.
+
+In headless mode (`-p`), a save failure produces a nonzero exit status and an error on stderr; model cleanup still runs. The process cannot retain an unsaved transcript after exit. Preserve stdout/stderr in automation and inspect any code or external changes before rerunning: a storage failure can happen after tools have already completed their work.
+
+## Storage behavior and limits
+
+- Session files are private (`0600`). Qriton writes a sibling temporary file, syncs its contents, then atomically renames it into place. Handled failures clean up the temporary file. A forced crash may leave a `.tmp` file; it is not loaded as a session.
+- `.write-lock.sqlite` serializes saves and deletions across updated Qriton processes. It contains no conversation data. SQLite releases its OS lock when a process dies. Do not delete or replace this file while Qriton instances are active: they must coordinate through the same lock file.
+- This protection assumes a local filesystem with working SQLite locks and atomic rename. Older Qriton versions and external file editors do not participate in the lock. Changes made before the fingerprint check are detected; an uncoordinated writer can still race the replacement. Network and synchronized folders are not validated storage profiles.
+- The existing 4 MB retention limit still applies: large images and older complete exchanges can be dropped. A recovery branch contains the transcript retained by that policy.
+- This is protection against stale saves and visible handling of storage failures. It does not add a durable tool-operation journal, automatic replay, backups, or a power-loss durability guarantee. File contents are synced, but the parent directory is not; a successful rename alone does not establish durability through sudden power loss.
+
+Model-free tests cover two independent writers, killed lock holders, deletion and manual changes, legacy files, injected replacement failure, branch recovery, retry after failed shutdown, and headless cleanup after a save error.

package/docs/shield.md

@@ -0,0 +1,62 @@
+# Local Shield scanning
+
+Qriton uses the standalone `L5SemanticLayer` and `SupplyChainScanner` from the pinned [`@qriton/shield` 3.3.0](https://www.npmjs.com/package/@qriton/shield/v/3.3.0) package. The package declares no runtime dependencies. Pattern matches are review signals. They are not an independent security audit.
+
+The integration starts no Shield server, firewall, email notifier, feed polling, collective reporting, or remote HLM classifier. In particular it never calls `Shield.start()`, `createOpenClawShield()`, `evaluate()` or the package's substring-based registry allow check. Qriton's existing HTTP policy and approval checks remain authoritative.
+
+## Configuration
+
+The default user configuration is:
+
+```json
+{
+  "shield": {
+    "mode": "warn",
+    "blockCredentials": true
+  }
+}
+```
+
+Set this in `$QRITON_HOME/config.json` (normally `~/.qriton/config.json`). Project configuration cannot set Shield policy, even after a workspace grant. `mode` controls injection-pattern handling: `off`, `warn`, or `block`. Credential blocking is independent: `off` still checks credentials when `blockCredentials` is true. Restart after a change.
+
+A launcher-managed policy can set minimum protection:
+
+```json
+{
+  "version": 1,
+  "shield": { "mode": "block", "blockCredentials": true }
+}
+```
+
+Neither user preferences nor runtime mutation can lower the managed minimum. `qriton doctor policy` shows the effective setting and its sources.
+
+## Checked boundaries
+
+- Agent tool results are checked before model-visible tool messages and tool completion events. Withheld results discard display and metadata too. The result states whether the tool reported success; filtering an output does not undo an operation.
+- Project instructions and recalled memory blocks are checked before injection into the model context. Project instructions still keep their existing stable per-session lifetime.
+- Research pages are checked before passage embedding or persistence. Detected credentials are excluded from both single and batch embeddings, including cached results.
+- New memory content and revisions are checked at the store boundary, covering tools and background capture. Blocked writes leave the existing fact and revision history intact.
+
+No matched secret, credential hash, or source-text sample appears in scanner reports. Recognized credential patterns withhold the whole affected result; the integration does not attempt fragile substring redaction. Entropy-only findings are ignored because they frequently match hashes and source identifiers.
+
+Default injection warnings preserve the retrieved text. Blocking is intentionally opt-in because source code, documentation and security tests can legitimately contain suspicious patterns. A positive finding means review is needed, not that malicious intent is established.
+
+## Offline review
+
+```sh
+qriton shield status
+qriton shield scan SKILL.md
+qriton shield scan src/example.ts
+```
+
+These commands load neither credentials nor providers and can inspect an untrusted workspace without granting configuration trust. File scanning reads one regular UTF-8 file inside the workspace, with a 256,000-byte limit; it never executes the content. Reports omit code excerpts and secrets. Exit status is `0` when the scan completes without findings requiring review, `3` when review is required, and nonzero on invalid inputs or read failures. A clean scan does not authorize installation or execution.
+
+## Limits
+
+The scanners use patterns, not a proof of safety. They can miss obfuscation, split payloads and novel instructions. Work is bounded to 8,192-character windows with 2,048-character overlap; patterns spanning farther can be missed. Inputs above the byte limit are explicitly incomplete and are withheld when a blocking control is enabled.
+
+This layer does not sandbox processes, enforce organization memory scopes, replace package provenance verification, or establish resistance to prompt injection. It does not scrub old transcripts, user-entered prompts, images, tool arguments already generated by a model, partial tool progress, local diagnostic files, or every provider request. Those surfaces must retain their separate privacy and authorization controls. Do not enter credentials into a model conversation.
+
+The upstream HLM hook is not used: its published implementation initiates background classification and may return before a fresh result exists. Connecting HLM security classification would need a bounded, awaited decision through Qriton's HTTP boundary and separate accuracy/false-positive evidence.
+
+The Apache license and upstream notice are included in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).

package/docs/terminal-interaction.md

@@ -0,0 +1,38 @@
+# Terminal interaction
+
+Qriton's interface should help users discover what they can do, show where their input will go, and preserve work when they change their mind. This applies equally to commands, saved conversations, model selection and approvals.
+
+## Principles
+
+- **One keyboard owner.** An approval or picker owns the keyboard while open. The composer retains its draft, and the transcript does not also consume navigation keys. Command suggestions are part of the composer.
+- **Show the available choices.** Slash commands and common arguments have descriptions. Long lists scroll around the highlighted item and show position and count. Search filters the full list, including previously hidden entries.
+- **Separate browsing from action.** Moving a selection never runs a command, changes permissions, switches a model or resumes a conversation. A visible selected item and an explicit submission determine the action.
+- **Make cancellation predictable.** Escape dismisses suggestions or a picker without losing input. At an approval, it rejects. With no open control, it interrupts active work. Ctrl+C still interrupts a running turn immediately from the composer.
+- **Keep shortcuts local and visible.** The footer changes with focus. Shift+Tab goes backward in a list; its existing mode-cycle shortcut applies only to an empty, idle composer.
+- **Use text as well as color.** A pointer identifies a selected list row, brackets identify the approval choice, and labels identify the focused control. Light and dark themes use the same structure.
+- **Keep discovery inexpensive.** Completion uses local command metadata. Model discovery runs only on `/models`; filtering does not query a provider or load a model. Session browsing reads local metadata without calling a chat model.
+
+These choices draw on [Command Line Interface Guidelines: consistency and discovery](https://clig.dev/#philosophy). The [W3C combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) informs preserving editable input, visible selection and Escape dismissal. Terminal keybindings are adapted to this application; this is not a claim of browser ARIA conformance.
+
+## Keyboard contract
+
+| Focus | Navigation | Action | Escape |
+|---|---|---|---|
+| Command suggestions | Up/Down; Shift+Tab previous | Tab fills. Enter fills a partial command; Enter on the completed command runs it. | Hide suggestions, keep text |
+| Session or model picker | Up/Down, Tab/Shift+Tab, Page Up/Down, Home/End; type to filter | Enter chooses; Ctrl+U clears the filter | Close, keep draft |
+| Approval | Tab/Shift+Tab or Left/Right selects; Up/Down and Page Up/Down scroll preview | Enter confirms the bracketed choice; y/n/a remain direct shortcuts | Reject |
+| Composer | Left/Right edits; Up/Down moves within multiline drafts or recalls single-line history | Enter sends; Ctrl+J adds a newline | Interrupt when working |
+| Empty, idle composer | Shift+Tab cycles approval modes | `/` opens command discovery | No action |
+| Feedback composer | Normal multiline editing; chat history is not offered | Enter saves locally; Ctrl+J adds a newline | Cancel without saving |
+
+Bracketed paste only inserts text or a filter. Pasted newlines and approval letters do not submit or approve. Approval starts with “approve once” selected, preserving the existing Enter behavior; selection alone never grants permission.
+
+The input remains docked. Short windows show fewer suggestions or picker rows, and long drafts retain their own scrolling behavior. Page Up/Down in the composer continues to scroll the conversation.
+
+## Implemented scope
+
+This interaction model covers slash commands, common fixed arguments, session selection, model selection and approval choices. Ordinary numbered lists in assistant prose remain text. File-path completion, interactive model-generated questions and mouse interaction need separate designs; they must not infer executable actions from arbitrary assistant text.
+
+`/servers` uses the same picker for explicit local/LAN discovery and verified server selection. Navigation never probes or connects until Enter. `/models` preserves provider ordering (newest OpenAI families first) and marks the current model in place. `/feedback` changes the composer into a local form with its own footer; its text is never passed to the agent, even when it begins with a slash command.
+
+Rendered terminal tests cover navigation beyond the visible rows, filtering, cancellation, explicit submission, mode isolation, pasted input, draft preservation and narrow-window resizing. They complement the existing streaming, approval-policy and session-restoration tests.