simjecture 0.4.0__tar.gz → 0.5.0__tar.gz

{simjecture-0.4.0 → simjecture-0.5.0}/CHANGELOG.md

@@ -4,6 +4,22 @@ This project follows semantic versioning. Dates use ISO 8601.
 
 ## Unreleased
 
+## 0.5.0 — 2026-09-21
+
+- Default new native-agent studies to minimal, with structured and frontier
+  selectable in the CLI, browser and TUI. Mode and backend are separate choices;
+  DSH/API remain explicitly labelled legacy routes. Existing records retain their mode.
+- Preserve active counterexample search, minimal-change repair rationale,
+  branching hypothesis ancestry and fresh prospective validation in the smaller service.
+- Add live terminal activity, job/review counts and remaining budget; project
+  minimal evidence and hypothesis trees into the browser and terminal interface.
+- Preserve deadlines across pause/resume, surface provider failures as resumable
+  states, and verify numerical-worker identity before cancellation.
+- Make the launch package usable with native agent logins without installing DSH;
+  retain an optional `setup.sh --with-dsh` path.
+- Retain measured limitations: simple-task follow-ups completed faster but used
+  more tokens; the previous hard FLASH trial did not establish superiority to a plain agent.
+
 ## 0.4.0 — 2026-09-20
 
 - Updated the bundled DSH integration to the tested `0.1.5-rc.2` runtime,

{simjecture-0.4.0 → simjecture-0.5.0}/CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use this software, please cite the exact software version and Git commit."
 title: "Simjecture"
 type: software
-version: 0.4.0
-date-released: 2026-09-20
+version: 0.5.0
+date-released: 2026-09-21
 abstract: >-
   An evidence-governed runtime for autonomous computational experimentation and
   falsification over hypothesis trees.

{simjecture-0.4.0 → simjecture-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simjecture
-Version: 0.4.0
+Version: 0.5.0
 Summary: Evidence-governed autonomous experimentation and falsification for computational science
 Project-URL: Homepage, https://github.com/tomzhu0225/simjecture
 Project-URL: Documentation, https://github.com/tomzhu0225/simjecture/tree/main/docs
@@ -50,9 +50,9 @@ writes its own experiments and diagnostics, and searches deliberately for the
 simplest result that survives independent verification. The harness controls
 what may count as evidence.
 
-> **Research preview:** version 0.4 extends the infrastructure with a
-> license-safe FLASH resistive-MHD capability and an explicitly bounded
-> island-coalescence audit. It does not claim to solve arbitrary
+> **Research preview:** version 0.5 defaults native-agent studies to minimal mode,
+> adds live terminal progress and shared browser/TUI mode selection, and retains
+> the license-safe FLASH capability and bounded scientific audits. It does not claim to solve arbitrary
 > scientific prose, establish truth about nature from one simulator, or replace
 > independent scientific review.
 
@@ -63,6 +63,23 @@ that have a sharp question and a checkable instrument. The 0.3 preview records
 both the origin domain and that generalization, and adds a fluid-MHD campaign
 whose unresolved repair state is preserved rather than hidden.
 
+## Start an agent-owned study
+
+New native-agent studies default to **minimal**: the agent chooses its approach,
+while Simjecture preserves evidence, counterexamples and hypothesis ancestry.
+
+```bash
+simjecture study --campaign ./runs/my-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+Use `--mode structured` or `--mode frontier` to select another workflow. Resuming
+keeps the recorded mode and deadline. See [minimal-mode usage](docs/how-to/research-service.md)
+for the scientific rules, backend choices and explicit legacy DSH/API routes.
+The measured hard-task benchmark does not establish a completion advantage over
+a plain agent; this default reflects the preferred agent-owned design.
+
 ## The core idea: AI low-hanging fruit
 
 Scientific problems are not uniformly difficult. A candidate may be buried in

{simjecture-0.4.0 → simjecture-0.5.0}/README.md

@@ -13,9 +13,9 @@ writes its own experiments and diagnostics, and searches deliberately for the
 simplest result that survives independent verification. The harness controls
 what may count as evidence.
 
-> **Research preview:** version 0.4 extends the infrastructure with a
-> license-safe FLASH resistive-MHD capability and an explicitly bounded
-> island-coalescence audit. It does not claim to solve arbitrary
+> **Research preview:** version 0.5 defaults native-agent studies to minimal mode,
+> adds live terminal progress and shared browser/TUI mode selection, and retains
+> the license-safe FLASH capability and bounded scientific audits. It does not claim to solve arbitrary
 > scientific prose, establish truth about nature from one simulator, or replace
 > independent scientific review.
 
@@ -26,6 +26,23 @@ that have a sharp question and a checkable instrument. The 0.3 preview records
 both the origin domain and that generalization, and adds a fluid-MHD campaign
 whose unresolved repair state is preserved rather than hidden.
 
+## Start an agent-owned study
+
+New native-agent studies default to **minimal**: the agent chooses its approach,
+while Simjecture preserves evidence, counterexamples and hypothesis ancestry.
+
+```bash
+simjecture study --campaign ./runs/my-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+Use `--mode structured` or `--mode frontier` to select another workflow. Resuming
+keeps the recorded mode and deadline. See [minimal-mode usage](docs/how-to/research-service.md)
+for the scientific rules, backend choices and explicit legacy DSH/API routes.
+The measured hard-task benchmark does not establish a completion advantage over
+a plain agent; this default reflects the preferred agent-owned design.
+
 ## The core idea: AI low-hanging fruit
 
 Scientific problems are not uniformly difficult. A candidate may be buried in

{simjecture-0.4.0 → simjecture-0.5.0}/docs/conf.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 project = "Simjecture"
 author = "Bowen Zhu"
 copyright = "2026, Bowen Zhu and contributors"
-release = "0.4.0"
+release = "0.5.0"
 
 extensions = [
     "myst_parser",

simjecture-0.5.0/docs/getting-started/first-run.md

@@ -0,0 +1,68 @@
+# First autonomous run
+
+To explore the interface before supplying an API key, replay the committed
+Gray–Scott record. This is read-only and starts neither a model call nor a
+simulation:
+
+```bash
+uv sync --frozen
+uv run python demos/gray_scott_counterexample/verify_record.py
+uv run simjecture web demos/gray_scott_counterexample/record --read-only
+```
+
+See [Recorded Gray–Scott demo](../demos/gray-scott.md) for the scientific result
+and the boundaries of that record.
+
+To start a new study, install and log in to a supported native agent CLI
+(Codex GLM, Codex, Grok or AGY), then open the browser:
+
+```bash
+uv run simjecture web
+```
+
+In **New hypothesis**, choose mode, backend and model separately. **Minimal** is
+the default. It keeps the agent's native tools and planning freedom while recording
+experiments, counterexample searches, hypothesis repairs and independent reviews.
+Structured and frontier modes remain selectable. DSH and direct API routes are
+explicit legacy choices and require their separate provider configuration.
+
+For a terminal run, write a bounded statement in `hypothesis.txt` and its test
+scope, resource constraints and acceptance criteria in `instructions.md`:
+
+```bash
+uv run simjecture study --campaign artifacts/first-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+The terminal shows current activity, elapsed/remaining time and experiment/review
+counts. Use `--quiet` to suppress progress. Select `--mode structured` or
+`--mode frontier` when starting a new directory. Existing mode, backend and wall
+deadline are retained on resume.
+
+Minimal records include `research.json`, immutable experiment snapshots,
+prospective repair commitments, independent review receipts and a final
+`research_report.json`. A clean agent exit is only a checkpoint. A supported root
+or an accepted falsification followed by a supported repair completes the study;
+uncertainty stays unresolved. Numerical convergence and physical validity remain
+scientific obligations. See [minimal research](../how-to/research-service.md).
+
+Inspect or control the same directory:
+
+```bash
+uv run simjecture status artifacts/first-study
+uv run simjecture watch artifacts/first-study
+uv run simjecture web artifacts/first-study
+uv run simjecture pause artifacts/first-study
+uv run simjecture resume artifacts/first-study
+```
+
+Pause stops the native agent at the supervisor boundary. Already recorded jobs
+may finish within their existing limits; the wall deadline continues. Cancel or
+deadline exhaustion terminates active recorded jobs. A provider outage pauses
+with the evidence intact rather than inventing a scientific conclusion.
+
+The optional [Terminal interface](terminal-ui.md) offers the same mode/backend
+selection and a dashboard for SSH and headless machines. The legacy `simjecture
+mvp` and [DSH](../how-to/deepseek-harness.md) entry points remain available; their
+workbench/commissioning contracts are unchanged.

{simjecture-0.4.0 → simjecture-0.5.0}/docs/getting-started/installation.md

@@ -17,7 +17,15 @@ uv run simjecture install core
 uv run simjecture doctor --profile core
 ```
 
-## Model credentials
+## Native agent login
+
+New studies default to minimal mode. Install and log in with Codex GLM, Codex,
+Grok or AGY independently, then choose that backend and model in the launcher.
+Simjecture does not redistribute those CLIs or subscriptions. Native tools remain
+available; numerical execution still uses the Bubblewrap sandbox. No DeepSeek
+API key or DSH install is required for native-agent studies.
+
+## Legacy API credentials
 
 Credentials are process-local harness inputs. They are never mounted into the
 agent workspace.

{simjecture-0.4.0 → simjecture-0.5.0}/docs/getting-started/web-interface.md

@@ -2,10 +2,18 @@
 
 The local web interface is the primary human-facing view of a Simjecture
 campaign. It makes the scientific structure visible without replacing the
-durable record. `mvp_manifest.json`, `transcript.jsonl`,
+durable record. New native studies default to minimal; mode, backend and model
+are separate launch choices. Minimal reads `research.json`, experiment snapshots,
+commitments and reviews. Legacy `mvp_manifest.json`, `transcript.jsonl`,
 `hypothesis_ledger.json`, `mvp_report.json`, and artifact provenance remain the
 sources of truth.
 
+Minimal studies show actual agent activity instead of the fixed-stage role strip.
+The header shows mode/backend/model and remaining budget. Long guidance and review
+rationales fold away, with failed reviews expanded. Usage is pending/unavailable
+when the backend has not supplied counters, never assumed to be zero. DSH/API
+remain explicitly labelled legacy routes; incompatible combinations are disabled.
+
 ## Open a recorded campaign
 
 The browser interface is included in the core installation and has no Node.js

simjecture-0.5.0/docs/how-to/research-service.md

@@ -0,0 +1,138 @@
+# Agent-owned research: minimal mode
+
+`simjecture study` defaults to minimal mode for new native-agent studies. The
+native agent chooses its plan, writes code and uses its existing tools; the
+service records evidence and independently reviews claims. Select `--mode
+structured` or `--mode frontier` to use the other workflows. `--workflow` is an
+alias for `--mode`. The `simjecture-supervise` and `simjecture-research` entry
+points use the same launcher.
+
+Resume without a mode flag to retain the recorded mode. Changing a study's mode
+requires a new campaign directory; no existing evidence is silently converted.
+Old studies retain their existing scientific-policy schema. The browser and TUI
+launch and monitor minimal, structured and frontier native-agent studies. Select
+mode and backend separately. DSH/API remain explicit legacy choices; selecting an
+unsupported combination returns an error rather than silently changing modes.
+The `mvp` command remains the legacy API entry point.
+
+```bash
+simjecture study --campaign /absolute/path/to/new-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+From a checkout use `python -m conjecture_solver.research_supervisor` with the
+checkout's `src` on `PYTHONPATH`. The backend uses its existing login. Codex/GLM
+resume the same native thread; other configured CLI backends preserve the working
+folder and evidence state. The wall deadline survives process restarts. Operator instructions are frozen before experiments and included in every reviewer packet; changing them requires a new study.
+
+The generated `research/lab.py` offers five operations:
+
+```python
+from lab import lab
+
+experiment = lab.run("calculation.py", args=["--n", "128"],
+                     inputs=["helper.py"], outputs=["result.json"], key="case-128")
+state = lab.status()  # Compact receipts; compact=False includes full metadata.
+# After the experiment reports succeeded:
+request = lab.review([experiment["id"]], "The finite result supports ...",
+                     disposition="supported",
+                     challenge={"strategy": "Exhaustive finite-domain test",
+                                "experiments": [experiment["id"]],
+                                "outcome": "Every declared case passed"})
+review = lab.review_status(request["id"])
+```
+
+`run` returns immediately. You may keep working while jobs execute, or end the model turn; the host then waits for a recorded job to finish before resuming the agent. The service snapshots source and declared local inputs,
+records their hashes and arguments, and runs the experiment inside Simjecture's
+existing Bubblewrap numerical sandbox. An installed capability can be selected
+with `capability=NAME`. Supply its manifest directory using `--capabilities` or
+the numerical instrument registry field in the browser/TUI. With no registry,
+minimal exposes only the Python numerical sandbox. Its identity is bound to the receipt. Native tools are
+available for exploration; execution success alone does not accept a claim.
+
+Identical requests reuse the same receipt. Change `key` for an intentional
+replicate. Changed source, inputs or arguments produce a new experiment identity.
+Result files and raw outputs remain under `experiments/ID/workspace/`; agents can
+inspect them but must not modify recorded artifacts. Review rechecks their hashes.
+The initial implementation bounds each experiment to 4 GiB and the study to
+8 GiB of recorded experiment storage with conservative reservations for active experiments. These bounds do not police arbitrary native working-folder writes.
+
+A review request returns a persistent receipt, independent of the caller's
+working directory. End the model turn after submitting it: the supervisor opens
+a fresh, tool-free reviewer context and records the result. Missing evidence
+returns explicit gaps. A malformed reviewer response never becomes approval.
+Each review targets one explicit claim ID and statement; the host rejects a mismatched target. Approval of an original falsification is distinct from completion of the study, which still requires a supported repair. Pending reviews survive pauses and deadlines. Scientific approval authority is
+not exposed through `lab`.
+
+For a repair, commit the prediction and exact commands first:
+
+```python
+plan = lab.commit("A bounded refined claim ...", source="validation.py",
+                  cases=[["--case", "a"], ["--case", "b"]],
+                  acceptance="Predeclared quantitative criteria ...", inputs=[],
+                  parent="root", rationale="Smallest justified change and why ...")
+fresh = lab.run("validation.py", args=["--case", "a"],
+                outputs=["result.json"], commitment=plan["id"])
+# Execute all committed cases, then review their receipts with claim=plan["id"].
+```
+
+New studies require evidence of active counterexample search for any supported
+claim. The `challenge` identifies the strategy, submitted experiments and outcome;
+the reviewer judges whether the tests actually challenge the claim. Boundary cases,
+failure-prone regimes or exhaustive finite-domain testing may qualify. There is
+no mandatory extra search phase or fixed number of tests.
+
+A repair names its parent (`root` or an earlier commitment ID) and explains why
+each changed assumption, scope or bound is necessary. This creates a durable
+branching hypothesis tree. A repair's review includes ancestor statements and the
+accepted counterexamples' actual source/results. Every ancestor must have an
+accepted falsification before a supported descendant can close the study.
+Minimality is judged scientifically, not by text length; scope restrictions must
+explain failures rather than erase them. Experiment workspaces are immutable
+snapshots, not separate Git worktrees for every hypothesis.
+
+The service rejects changed committed source/arguments, retrospective relabelling
+of earlier runs and omission of committed cases. The reviewer still must judge
+whether the repair is meaningful: a fitted range tested on its own fitting data
+is not validated research.
+
+Ordinary calculations do not need a separate instrument-claim hierarchy or an
+approval before every calculation. Physical adequacy, controls and convergence
+remain scientific obligations and are checked at review. A supported original
+claim completes the study; a falsified original requires an independently
+supported repair. Unresolved evidence and normal model exit do not complete it.
+
+This is a cooperative same-account trust model. The native CLI agent is not
+adversarially isolated from host files; host-only Python methods are an interface
+boundary, not an OS security boundary. A hostile-worker deployment needs separate
+accounts or a separately authenticated service. Numerical execution retains its
+existing sandbox. No existing campaign is migrated automatically.
+
+Native-thread continuation prompts are short; full instructions remain in
+`research/RESEARCH_GUIDE.md`. `lab.status()` includes remaining wall time and
+receipt/workspace paths, with full metadata available through `compact=False`.
+For long solvers prefer separately recorded cases, check a pilot's output schema,
+and reserve time for validation and synthesis.
+
+Minimal is the new-study default by operator preference, not because the benchmark
+established superiority. The workflow is evaluated against plain, structured and frontier runs;
+see [the measured results](https://github.com/tomzhu0225/simjecture/blob/main/research/evaluations/research-service-v2/RESULTS.md) and [benchmark plan](https://github.com/tomzhu0225/simjecture/blob/main/research/evaluations/research-service-v2/PLAN.md).
+
+Latest iteration: [scientific-rule and default-mode tests](https://github.com/tomzhu0225/simjecture/blob/main/research/evaluations/minimal-default/RESULTS.md).
+
+
+## Watching and controlling a study
+
+A terminal launch prints live activity, backend/model, elapsed/remaining time and
+experiment/review counts. Redirected output gets plain periodic status lines;
+use `--quiet` to suppress them. Open `simjecture web /path/to/study` or
+`simjecture tui /path/to/study` to inspect the same evidence and hypothesis tree.
+
+Pause stops the agent at the supervisor boundary; already recorded numerical jobs
+may finish within their existing bounds. Resume retains the original wall deadline
+and mode. Cancel and deadline exhaustion terminate verified active numerical
+workers. Three consecutive provider failures pause the study with its evidence
+intact; ordinary agent exit and inconclusive review do not establish completion.
+Provider usage is shown when the backend supplies completed-turn counters, with
+resumed cumulative counts deduplicated by native thread. Missing usage is not zero.

simjecture-0.5.0/docs/how-to/simote-agent-roles.md

@@ -0,0 +1,279 @@
+# Scientific roles with Simote agent sessions
+
+Simote can run Codex, Grok, and AGY (Antigravity) CLI agents as claim-scoped Simjecture workers.
+Simjecture remains the authority for evidence, claim disposition, jobs, budgets,
+and campaign finalization. The native API runner and DSH profile remain available.
+
+Install the matching Simjecture checkout on the compute worker, including the
+`simjecture-call` entry point. Restart Simote after updating its server. Agents
+and their logins remain on the Simote host; compute happens through the existing
+SSH bridge. This integration uses the selected bot's engine and model.
+
+In Simote, enable **Simjecture campaigns** under **Settings → General →
+Experimental features**. It is off by default: standalone Simote does not need
+Simjecture, load its campaign page, poll campaigns, or expose campaign tools to
+ordinary agent sessions. Disabling it hides the page and prevents new campaign
+and role launches; existing assigned work can finish and records are preserved.
+
+## Run a shared campaign
+
+1. Configure a campaign-owner bot and one or more worker bots in the same Simote
+   team section, using the same named SSH compute machine. Select Codex, Grok, or AGY
+   agent engines for the workers, with their existing local logins.
+2. Ask the owner to use `simjecture_open_campaign`. The owner keeps the campaign
+   under its workspace. Scientific worker tasks share that campaign; they do not
+   create copies under their own bot workspaces.
+3. The owner calls `simjecture_assign_role`, for example:
+
+   ```json
+   {
+     "campaign_id": "invariant-test",
+     "assignment_id": "falsify-root-1",
+     "agent_id": "YOUR_GROK_BOT_ID",
+     "role": "falsifier",
+     "claim_id": "claim_root",
+     "max_operations": 100
+   }
+   ```
+
+   This starts a fresh task on the selected bot. Other supported roles are
+   `lead_scientist`, `repair_scientist`, and `blocker_resolver`. The target bot
+   must be idle. A Repair Scientist requires a falsified parent.
+4. The worker reads `simjecture_snapshot` and uses the typed `simjecture_*`
+   tools exposed from its role-filtered kernel catalog. The supervisor binds
+   the campaign identity. Every mutating
+   operation ID begins with its assignment ID and `:`. The worker finishes with
+   `simjecture_handoff`; the kernel record must substantiate claimed
+   falsifications and linked evidence. A handoff ends that assignment, not the
+   campaign. Only one unfinished scientific worker assignment may own a claim.
+5. For independent review, the owner or assigned lead calls
+   `simjecture_adjudicate` with `campaign_id`, `judge_bot_id`, `operation_id`,
+   `claim_id`, `contract_version`, and `case_for_sufficiency`. The selected
+   Codex/Grok/AGY instance receives a fresh session, empty working directory, no
+   conversation history or Simote integrations, and only the frozen case.
+   Tool activity invalidates the review. Only a successful text-only response
+   reaches Simjecture's existing verdict validation and scientific gates.
+6. The owner or lead uses the official `finalize_campaign` tool only when the
+   scientific frontier is ready. A chat reply never finalizes a campaign.
+
+Assignments appear as named tasks in Simote, with the normal streamed agent
+activity. `simjecture_snapshot` includes assignment identities, operation counts,
+session history, and handoffs. The optional **Simjecture** sidebar page shows a
+hypothesis graph, claim contracts, linked evidence previews, jobs, role tasks,
+and the final report. You can create or attach a campaign, assign workers,
+request independent review, cancel jobs, and finalize through the same kernel
+gates. The existing Simjecture web dashboard is also available.
+
+AGY workers require the instance's full-auto setting, because its headless CLI
+cannot approve MCP calls interactively. Simote mounts named scientific MCP tools
+for each turn and removes them before a tool-free judge starts. AGY uses a global
+MCP configuration, so Simote serializes AGY child lifetimes to prevent one task
+from receiving another task's credentials. User-configured MCP entries remain
+preserved; any observed judge tool use rejects the review, as for other engines.
+
+## Recovery and boundaries
+
+Campaign creation first probes Bubblewrap namespace support. A GPU container
+that denies user namespaces is not a compatible scientific worker, even if
+SSH and ordinary commands work. Use a compatible Linux host; no fallback skips
+isolation or turns a failed run into evidence. `simjecture-call --workspace
+./campaigns --probe` checks readiness without creating a campaign.
+
+Parallel agent tool calls are queued per campaign. A narrowly identified
+pre-dispatch writer conflict may be retried while a detached job commits its
+receipt; ambiguous errors are returned for explicit operation-ID recovery.
+
+Reopen the same Simote task to continue after a server restart. The task retains
+its campaign routing and native session cursor. A new session must read a
+snapshot before scientific work. Reuse the original operation ID and arguments
+after a lost response; neither the assignment budget nor the kernel's operation
+journal resets. Existing jobs are reconciled by the kernel on reopen.
+
+Repeating `simjecture_assign_role` with the same identity returns the existing
+task. It does not automatically rerun a previously dispatched task. A changed
+assignment needs a new ID. An inconclusive or blocked handoff is preserved;
+start a new assignment for subsequent work. A saved judge verdict is reused
+after a remote commit failure; an operation cannot silently bind a new case.
+
+The Simote role registry contains routing metadata only. Authoritative
+assignments live in `role_assignments.json` beside the campaign ledger, outside
+the experiment sandbox. The campaign supervisor lease serializes one-shot
+calls. A campaign already owned by a running DSH/native supervisor cannot also
+be driven through this transport.
+
+Role enforcement covers the Simjecture tool boundary and Simote's remote tool
+endpoint. Provider CLIs may also have native local tools or user-configured
+integrations; this feature does not turn those CLIs into OS-isolated processes.
+It never copies SSH credentials into those processes. Scientific outputs still
+have to pass the existing sandbox, provenance, and evidence gates.
+
+## Headless supervisor interface
+
+Any trusted supervisor can use the same role boundary without running Simote.
+First open a campaign normally, then issue a JSON assignment with exactly
+`assignment_id`, `agent_id`, `role`, `claim_id`, and `max_operations`:
+
+```bash
+simjecture-call --workspace ./campaigns --campaign invariant-test \
+  --issue-assignment-file assignment.json
+
+simjecture-call --workspace ./campaigns --campaign invariant-test \
+  --assignment-id falsify-root-1 --agent-id grok-worker --session-id session-1 \
+  snapshot
+```
+
+Pass `--arguments-file` for tool arguments, `--list` for the role's tool catalog,
+or `--handoff-file` for a structured final handoff. The supervisor supplies the
+authenticated identity flags; they must never come from model tool arguments.
+
+The DSH profile retains its existing role orchestration and guards. This
+transport adds a persistent boundary for external agent sessions without
+changing recorded campaigns or their scientific acceptance rules.
+
+## Persistent CLI supervision
+
+An external worker's exit or handoff is a checkpoint, not permission to end a
+campaign. To run AGY or Grok without an interactive Simote owner, prepare an
+initialized campaign with `MVPAgentConfig(require_independent_contract_review=True)`
+and an operator instruction file, then start the persistent supervisor:
+
+```bash
+simjecture-supervise --campaign /absolute/path/to/campaign \
+  --state-dir /absolute/path/to/supervisor-state \
+  --instructions-file /absolute/path/to/instructions.txt \
+  --backend grok --model grok-4.6 --judge-model grok-4.6 \
+  --wall-seconds 21600 --turn-seconds 600
+```
+
+From a checkout, `python -m conjecture_solver.agent_supervisor` is equivalent.
+The supervisor resumes unfinished assignments and issues successors after
+inconclusive or blocked handoffs. Local turn/operation limits do not reset the
+campaign deadline or end the study. Its durable `state.json` and `events.jsonl`
+record progress. Restarting with the same state directory preserves the deadline.
+One persistent supervisor can own a campaign at a time.
+
+Workers request independent review by writing `review-request.json` in their
+native research directory, with `claim_id`, `contract_version`, and
+`case_for_sufficiency`. The supervisor freezes the kernel case and launches a
+fresh judge through the selected CLI backend in an empty directory. Any observed judge tool activity rejects
+the verdict. Only the kernel can accept the verdict or finalize the campaign.
+Judge rejection and insufficient evidence return to experimental work.
+
+With the default strict repair loop, an accepted `unresolved` or
+`instrument_limited` record leaves the scientific claim open. Normal completion
+requires independently accepted support for the original claim or its repair
+frontier. A falsified frontier requires a repair and further testing. Existing
+legacy claims already closed as unresolved require explicit recovery; the
+supervisor refuses to reinterpret them as success.
+
+The wall-time boundary saves `budget_exhausted`, preserves the open ledger and
+cancels active jobs. Operator controls are separate: write
+`{"command":"pause"}` or `{"command":"cancel"}` to the supervisor's
+`control.json`. Repeated infrastructure/provider failures pause with a recorded
+error; they never count as scientific completion. Remove a pause command before
+resuming. This does not OS-sandbox the agent's native tools or alter its global
+MCP configuration; numerical jobs retain Simjecture's sandbox and evidence rules.
+
+### Contract and qualification review
+
+New persistent runs require `require_independent_contract_review=True`. The
+legacy default remains false so historical manifests remain readable; the
+persistent supervisor refuses that legacy policy instead of silently accepting
+old qualification. Start a new reviewed campaign to requalify an instrument;
+old artifacts may be supplied as unaccepted research context.
+
+A worker first registers its prospective contract, then writes
+`contract-review-request.json` containing only `claim_id` in its research
+folder. The host freezes the original hypothesis, parent statement, exact
+contract, bound program sources, and optional operator-owned
+`operator_input/scientific_protocol.txt`. A separate review must approve this
+packet before evidence execution or sufficient evidence linking. A changed
+contract, source, or frozen protocol invalidates the approval.
+
+After collecting and linking prospective instrument/diagnostic/control evidence,
+the worker writes `qualification-review-request.json` with `claim_id`. This
+second review includes actual linked output and provenance; only approval permits
+supported closure. Execution status, stage labels and output counts cannot stand
+alone as physical qualification checks, even if labelled with the expected
+aspect. The kernel enforces both reviews; workers have no approval tool.
+
+Reviews and transcript hashes persist outside the numerical workspace in
+`scientific_reviews.json`. These are scientific reviews, not user confirmation
+prompts. Judge transport accepts a single outer JSON fence, validates semantics,
+and retries malformed output once in a fresh context. It never changes an invalid
+scientific disposition to make a verdict acceptable. Observed judge tool activity
+rejects the response. Worker native tools remain available. Both CLI backends
+retain their existing logins; the supervisor does not rewrite global MCP settings.
+
+### Optional researcher workflow
+
+Use `--workflow frontier` to let one researcher organize experiments, pursue
+supporting claims and test repairs without switching scientific roles. The
+structured workflow remains the default. Both use the same evidence contracts,
+provenance checks, independent reviews and completion rules.
+
+For a campaign configured with independent contract review:
+
+```bash
+simjecture-supervise --campaign /absolute/path/to/campaign \
+  --state-dir /absolute/path/to/new-supervisor-state \
+  --instructions-file /absolute/path/to/research-instructions.md \
+  --workflow frontier --backend codex-glm --model glm-5.3 \
+  --wall-seconds 21600 --turn-seconds 600
+```
+
+The `codex` backend uses the same native CLI protocol and requires an explicit
+`--model`. Each backend retains its existing login. Native thread resumption is
+currently implemented for `codex` and `codex-glm`; AGY and Grok retain the stable
+research directory and kernel state across invocations. Do not switch workflow
+or backend inside an existing supervisor state directory.
+
+The researcher keeps a stable `research/` directory. Native tools remain
+available, and detached numerical jobs need not block other research. In this
+mode `--turn-seconds` is an inactivity watchdog: provider output or kernel action
+activity resets it. It cannot extend the campaign's fixed wall deadline. A model
+ending its turn does not declare the science finished. Review requests move to a
+durable host queue, which survives a pause or deadline; resuming an exhausted
+budget does not create a new deadline.
+
+Inside the generated research directory, the agent can use the scoped client:
+
+```python
+from lab import lab
+
+lab.write("measure.py", "print('measurement')\n")
+result = lab.run_python(["measure.py"], inputs=[], request_key="probe-1")
+# After registering an actual prospective evidence contract:
+lab.request_review("contract")
+```
+
+The client fills in operation IDs, the assigned claim and administrative notes.
+Scientific inputs and declared artifact dependencies remain explicit. Repeating
+an identical request reuses its receipt; use a different `request_key` for an
+intentional replicate. `run_python` also binds this identity to the entry script
+and contract revision. The client cannot approve evidence or finalize a campaign.
+For other operations use `lab.call(tool, arguments)` and inspect the generated
+adapter's `schema TOOL` output.
+
+Evidence validation paths support object keys and array indices, for example
+`rows.0.N`, `rows[0].N` and `$.rows[0].N`. Wildcards, slices, expressions and
+negative indices are unsupported. Checks retain strict scalar comparison rules.
+A design reviewer may approve a proposal and suggest executing it next; required
+evidence or design gaps still prevent approval. Design approval is not a
+scientific conclusion.
+
+Native agents run under a cooperative trust model with access to their host
+account. These role checks do not provide adversarial isolation from host files.
+Numerical execution retains its existing sandbox and evidence rules.
+
+The first real GLM pilot supports reduced context loss, but neither workflow
+completed an accepted scientific conclusion within its short budgets. Keep this
+mode opt-in pending further evaluation. See the
+[measured results](https://github.com/tomzhu0225/simjecture/blob/main/research/evaluations/frontier-workflow/RESULTS.md) and
+[design notes](https://github.com/tomzhu0225/simjecture/blob/main/research/evaluations/frontier-workflow/DESIGN.md).
+
+For the smaller service with explicit experiment/review receipts and agent-owned
+planning, see [agent-owned research](research-service.md). Minimal is now the
+default for new native-agent studies; select `--mode structured` or `--mode
+frontier` for the alternatives. Existing campaigns retain their recorded mode
+and record format. The browser/TUI now select these native modes too; DSH/API remain explicit legacy choices.