@ckanner/flywheel 0.31.1 → 0.32.0

package/docs/en/investigation.md

@@ -9,7 +9,7 @@ it is not a third implementation completion mode.
 
 | Daily request | Entry | Engine behavior and endpoint |
 | --- | --- | --- |
-| Diagnose and explain | `/flywheel-task` | Managed reads/searches and an evidence report; no implementation |
+| Diagnose and explain | `/flywheel-task` | Managed evidence collection, approved diagnostic experiments and a report; no implementation |
 | Diagnose and repair within scope | `/flywheel-task` | Supported report, then Spec and Auto; retain provenance, usage and scope |
 | Repair an identified issue | Task Auto or explicit Quick | Qualification, mandatory checks, independent final Review and Git delivery |
 | Propose a complex change for review | `/flywheel-new` | Stop after preparation; Run Full after implementation authorization |
@@ -34,27 +34,93 @@ evidence, falsifiable hypotheses, exact read paths, concrete actions and budgets
 `implementation-scope`; report-only intent grants no implementation scope. A Spec
 is not required while only preparation exists.
 
-The initial action family is implemented directly by Go:
+Go executes the evidence actions. Models choose only among candidates already
+approved in the contract:
 
 | kind | Capability | Boundaries |
 | --- | --- | --- |
 | `read_file` | Read one approved UTF-8 file | Reject symlinks, special files and excessive input |
 | `search_text` | Literal search in one approved file, with line numbers | No regular expressions or command interpolation |
 | `list_files` | List names in one approved directory | No recursive content grant; at most 4096 names |
+| `run_command` | Run exact argv against a temporary copy of approved inputs for reproduction or diagnosis | Explicit `host-process` authority, action timeout, controlled environment, process-group cancellation and cleanup |
+| `http_read` | GET or HEAD against an exact approved URL | HTTPS (loopback HTTP for tests), no redirects/environment proxy, bounded response and output |
 
-Paths must be clean repository-relative paths. Each action references an approved
-path and existing hypotheses. The opened inode must match the inspected inode;
-`os.Root` confines traversal. A directory grant permits names only. This version
-has no arbitrary shell, external query, production restart, cache flush, data
-repair or writable investigator Agent action. Existing full-access configuration
-does not add capabilities to these Go handlers. Broader experiments require
-additional handlers, contracts and validation.
+File paths must be clean repository-relative paths, and file actions reference an
+approved path. Every action references existing hypotheses. The opened inode must
+match the inspected inode; `os.Root` confines traversal. A directory grant permits
+names only, not its descendants' contents. Command and HTTP arguments belong to the
+frozen contract. JEV cannot generate another command, URL or credential variable.
 
 `limits` freezes action count, overall deadline, per-file bytes and total output
 bytes. Resume does not reset them. The deadline starts at preparation, including
 paused time. Bounded UTF-8 excerpts retain a content digest; `truncated` means the
 display is incomplete, not that an entire log or test inventory was observed.
 
+### Reproduction tests and diagnostic commands
+
+`run_command` uses `command.argv` without an implicit shell. `command.inputs`
+lists exact approved regular files from the contract's `read-paths`. Each invocation
+copies these inputs with their relative directory structure and runs in that copy;
+ordinary writes to the copy are not transferred back to the source workspace. This
+is a bounded reproduction input set: at most 32 UTF-8 files, subject to the contract's
+file and output limits, with executable bits preserved. A directory entry does not
+copy its descendants automatically. The following
+action fragment illustrates the fields. Replace paths and the hypothesis ID with
+those actually approved in the current contract:
+
+```json
+{
+  "id": "reproduce-timeout",
+  "kind": "run_command",
+  "purpose": "Reproduce the observed timeout with isolated inputs",
+  "hypotheses": ["timeout"],
+  "command": {
+    "argv": ["/usr/bin/python3", "tests/reproduce.py"],
+    "inputs": ["tests/reproduce.py", "src/settings.py"],
+    "env": [],
+    "timeout-ms": 30000,
+    "expect-exit": 1,
+    "execution-boundary": "host-process"
+  }
+}
+```
+
+`host-process` explicitly means execution with the current user's real host
+permissions. The copy keeps ordinary relative writes outside the original workspace;
+**it is not an operating-system sandbox or a network boundary**. Approve the concrete
+program and arguments within the task's existing authority. Full-access settings
+and the JEV switch do not grant that action authority on their own. `env` contains
+environment-variable names, never secret values. An expected nonzero exit can
+establish a reproduced failure. Timeout, cancellation, signals, output truncation
+and cleanup errors cannot stand in for a normal expected exit.
+An expected nonzero exit can be valid reproduction evidence, but does not by itself
+qualify the remaining collection for deferral or early finish.
+
+An observation's `execution` records physical exit/signal, timeout, cancellation,
+input digest and copy cleanup. `removed` means cleanup completed, `retained` keeps
+the experiment for reconciliation, and `not-created` means no copy was created.
+Unknown process or cleanup outcomes leave the original invocation pending and block
+further actions. Recovery reads its original receipt rather than executing again
+to guess the result.
+
+### Approved external queries
+
+The `http_read` action's `http` object contains `url`, `method` (GET/HEAD),
+`headers-env`, `timeout-ms`, `max-bytes` and `expect-status`. An approved health
+query might use `headers-env: {"Authorization": "INCIDENT_STATUS_AUTH"}`. The
+variable supplies the complete header value; the contract and receipt do not store
+that secret value. The URL is an exact authorization: no redirects, environment
+proxy or embedded credentials. Go bounds request time and bytes and records the
+actual HTTP status and output digest. A GET/HEAD grant does not authorize arbitrary
+services, production restarts, cache flushes or data repair.
+
+Structured command/HTTP outcomes, such as exit code, status and completeness, use
+`diagnostic-facts` and may participate under the default data policy. Raw output is
+included as a bounded excerpt only when `logs` is explicitly allowed. Otherwise
+the snapshot records that missing content, and JEV can still choose from structured
+facts. File evidence uses `source`. Action approval does not add raw-log sharing
+permission, and a permitted category does not remove the need to protect secrets.
+
 ## CLI and desktop controls
 
 Create the actual task directory, then submit a complete preparation request:
@@ -71,8 +137,9 @@ saves ready preparation without executing actions. To run, submit
 Go starts a background owner under the existing task lifetime lease and token-bound
 stop protocol. In DSH, `flywheel_control` accepts `action: investigate` and the nested
 `investigation` request, associating the exact task with the conversation. The panel
-shows budgets, observations, excerpts, decisions and reports, with continue,
-reconcile, stop and refresh controls.
+shows budgets, observations, excerpts, process exits/HTTP status, cancellation and
+copy cleanup, decisions and reports, with continue, reconcile, stop and refresh
+controls.
 
 ```bash
 flywheel control status --task-dir "$task_dir" --cwd "$repo_dir"
@@ -119,6 +186,13 @@ preparation source cannot bypass scope or accounting.
 Executor prompts recommend targeted checks first. Go still runs the complete frozen
 acceptance against the current candidate before independent Review. This removes a
 fixed requirement to run the full suite twice; it does not cache or remove the gate.
+Packets can declare up to eight approved short `feedback-checks` with the same
+`cmd`/`expect` shape as acceptance commands. They support targeted reproduction
+without changing final acceptance. With JEV enabled, the engine can choose one of
+these checks or recheck a failed L1 command after its prior result is confirmed.
+Short checks offered to JEV also require a nonblank `purpose` of 1–160 characters;
+entries without it remain available to Executor. JEV candidates send the description
+without appending `cmd`/`script`; the description itself must omit secrets and raw logs.
 
 Feedback carries stable check IDs, expected and actual physical outcomes,
 candidate/check-set/environment identities, a full failed-output digest and bounded
@@ -134,75 +208,40 @@ that proof. Contract, verification or scheduling changes, an unknown external HE
 legacy missing proof, explicit Plan or a verification gap require planning again.
 Speed changes the economics of feedback; it does not erase planning or quality gates.
 
-## Optional JEV decisions
-
-Preparation `decision` is independent of legacy `jev-shadow` and absent by default.
-Its schema defines an explicit endpoint, fixed `jev-x.y.z` model, credential
-environment-variable name, timeout, policy version, mode, allowed data categories,
-thresholds and maximum calls. Credential values never enter the contract.
-
-- Off/offline do not contact the service; shadow captures a local snapshot;
-  advisory records advice; adopt can select one approved diagnostic action.
-  Thresholds are explicit experiment parameters, not measured deployment accuracy.
-- At least two legal choices and actual semantic uncertainty are required. One
-  request pairs applicability Noul with Choice and retains full probabilities.
-  Missing applicability, version mismatch, unauthorized fields, insufficient budget
-  or unknown execution cause abstention.
-- Before adoption, recheck task/run/revision, contracts, candidate, observations and
-  action binding. Consume the decision and bind a unique action invocation in one
-  CAS before dispatch. JEV cannot invent commands, skip acceptance or declare success.
-- An unknown optional request is not resent. Usage remains unknown and the task can
-  take its legal deterministic baseline. An unknown action outcome blocks. Ending,
-  cancellation and deadline expiration still reconcile the optional request read-only.
-- Maximum calls include unknowns. Hard budgets skip optional JEV when the API cannot
-  enforce a provable request ceiling. Character estimates are not reservations.
-
-Legacy workflow shadow captures only a local bounded summary; explicit `shadow run`
-evaluates it later. That switch cannot adopt actions or authorize new source/log
-sharing. Offline or shadow results do not establish a causal speedup. Compare full
-tasks using the existing baseline, core improvements without JEV, and those same
-improvements plus one action family.
-
-### Offline replay and explicit advisory evaluation
-
-The general decision capture is a `*.snapshot.json` document containing the frozen
-`snapshot`, `policy` and source `target-hash`. It is distinct from the legacy workflow
-shadow dataset. Review its facts and data permissions before any live evaluation.
-
-```bash
-flywheel decision replay --input frozen.snapshot.json --response native-response.json \
-  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
-```
-
-Replay accepts a recorded native System One response or a fixture, forces `offline`,
-does not read a credential, sends no HTTP and writes no journal or task state. The
-endpoint and equal fixed model IDs identify the intended target; the version above
-is an example and must match the response under evaluation. A bare Snapshot JSON
-requires `--policy reviewed-policy.json`. That flag also replaces the entire captured
-policy when used with a wrapper; omitted data permissions are not inherited.
-
-For an explicitly authorized live experiment:
-
-```bash
-flywheel decision evaluate --input frozen.snapshot.json --policy reviewed-policy.json \
-  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0 \
-  --directory ./decision-evaluation --key-env MEROUTER_API_KEY --max-calls 5
-```
-
-`evaluate` always forces `advisory`, even if the source policy says `adopt`. The
-credential environment-variable name, fixed target, separate private journal and
-cumulative call cap are explicit. It preserves source data-category permissions and
-requires them to cover the snapshot. `--hard-budget` skips the optional call because
-the native API cannot enforce a request usage ceiling. Reusing the same journal and
-snapshot reads the original receipt; unknown requests consume the cap and are never
-resent. The command does not execute an action or change task state.
-
-Both commands print the baseline, effective policy, probabilities and receipt with
-`adopted: false`. Live errors or unknown outcomes return exit code 3 with that receipt;
-input/configuration errors return 1, cancellation before dispatch returns 143. A
-successful offline replay is parser/fixture evidence, not a measured model success.
-Limited task adoption still requires the separate preparation policy, data opt-in,
-frozen concrete Go action and current-state checks described above.
+## JEV decisions
+
+Use the single `jev.enabled` setting described in the [JEV guide](jev.md). Start
+resolves configuration and freezes the policy automatically; Task, New and Run do
+not maintain separate decision modes. The default disabled path retains the
+original action order and collection limits. Enabled decisions may choose the
+next action, defer redundant evidence collection, or stop collection for a report
+when Go's evidence prerequisites are met.
+
+Deferred actions and early completion of collection are persisted with decision
+and observation references. They do not classify a hypothesis as proven or
+contradicted. The analyst still writes the evidence-grounded report, and repair
+still uses the original scope plus the ordinary verification and review flow.
+`awaiting-report` does not restart collection when Run is repeated.
+
+After handoff to implementation, the same switch also controls the next step after
+a failure: continue repair, collect an approved feedback check, request replanning,
+or select a model/effort from allowed execution bindings. These choices share the
+task decision allowance, including calls already used during investigation. Changing
+packet, replanning or resuming does not reset that allowance. Feedback checks collect
+facts and never replace complete final acceptance. See the [JEV guide](jev.md) for
+candidate and state semantics.
+
+The effective target, model, data categories, thresholds and budget are frozen at
+preparation time. Current OFF, incompatible target changes or tightened policy
+stop further optional decisions. In-flight results are rechecked before adoption;
+known/unknown receipts are reconciled without resending. A preparation initially
+created with JEV off keeps its baseline policy; a new preparation receives a newly
+enabled policy. The desktop labels its stored status as last observed.
+
+The [JEV guide](jev.md#replay-and-explicit-evaluation) documents local replay and
+explicit online evaluation. Replay stays available without JEV. Online evaluation
+requires the same enabled master and configured target; its data/call limits cannot
+loosen configuration. Neither tool executes actions or changes task state.
 
 ## Measurement and remaining boundaries
 
@@ -214,6 +253,11 @@ model and internal tool breakdown remains unknown. Investigation actions/runs us
 the same phase API; unobserved host-preparation time is never filled with zero.
 
 Offline checks do not establish fewer tokens, lower cost or equal final quality.
-This change does not enable a new default model, JEV, prewarming or higher
-concurrency. Ready queues, persistent workers and importing existing candidates
-remain conditional on measurement and their own recovery/acceptance evidence.
+JEV remains off by default; enabling the master switch activates the supported
+decisions. Default models and concurrency are unchanged. The
+[ready queue and bounded DSH runtime preparation](configuration.md#ready-queues-and-runtime-preparation)
+are now available as explicit scheduler settings, with batch dispatch and no
+prewarming remaining the defaults. Real performance and any default change still
+need measurement. Long-lived workers and general external-patch import remain
+separate work; the existing managed Session claim/return path keeps its original
+recovery and acceptance requirements.

package/docs/en/jev-shadow.md

@@ -1,67 +1,5 @@
-# Optional JEV shadow evaluation
+# JEV guide moved
 
-[Documentation](../README.md) · English · [简体中文](../zh-CN/jev-shadow.md)
+[English](../en/jev-shadow.md) · [简体中文](../zh-CN/jev-shadow.md)
 
-This guide covers the optional workflow-shadow experiment. It captures a bounded
-task summary for later, explicit evaluation and does not choose the production workflow. Start with the
-[normal workflow](workflow.md); enable shadow evaluation only when collecting
-comparison evidence for a configured endpoint.
-
-## Enable or disable
-
-JEV is **off by default**. Missing `jev-shadow` in older configuration also means off: no credential lookup, network requests or shadow records. Existing Go Quick/Full selection stays in charge.
-
-In the desktop, open **Flywheel → Configuration**, choose the global or project
-scope, then open **JEV shadow advice**. Configuration loads automatically; review
-the endpoint and save. Alternatively merge this section into the effective
-complete `flywheel.config.json`:
-
-```json
-{
-  "jev-shadow": {
-    "enabled": false,
-    "endpoint": "https://merouter.play.one2x.ai/v1/systemone",
-    "model": "jev",
-    "expected-model": "jev-1.14.0",
-    "key-env": "MEROUTER_API_KEY",
-    "timeout-ms": 5000
-  }
-}
-```
-
-The shared template leaves the endpoint empty. Configuration stores the environment variable **name**, never the key. Local capture does not look up credentials; the process running an explicit `shadow run` must inherit the variable. Never put credentials in endpoint or model fields. Discovery selects one complete file in task → project → global → embedded order, without merging. Inspect the source with `config inspect --json`; saves affect subsequent starts. Disabling preserves previous records.
-
-Enabling captures task goals, requirement/acceptance descriptions and planning evidence privately for later review and labeling. The task itself sends nothing to JEV. No source files, diffs, execution logs or provider conversations are read. URL/home-prefix removal and common credential-pattern rejection are best effort, not universal anonymization. Review the business summary before explicitly sending it to your configured endpoint. This setting never authorizes a new data category or automatic adoption of diagnostic decisions.
-
-Only a new task's first ordinary run is captured, after existing workflow state is saved. It writes the bounded input and pinned target locally, with no HTTP wait, credential lookup or background goroutine. Resume, retry and single-step commands do not backfill observations. Invalid targets, rejected summaries and record failures log a warning and leave the primary workflow running. Hard-budget tasks can also capture, because capture creates no API usage. Cancellation skips capture and retains the normal task-stop behavior. Explicit Full and structural Quick exclusions remain deterministic blockers when a later experiment evaluates the snapshot.
-
-Advice never changes Quick/Full, routing, permissions, sessions, acceptance or PR/Merge gates. Independent usage and latency records do not enter the task budget. Unknown usage stays unknown; no billing savings are implied.
-
-## Explicit experiments
-
-Automatic captures live under `~/.config/flywheel/shadow/<target-digest>/<input-digest>/` (0700 directories, 0600 files). Logs identify the directory. `cases.json` holds the bounded summary; `target.json` pins endpoint, model, questions and policy. Before explicit evaluation, the report shows these cases as not run. The later `shadow run` owns its lifetime and separate call budget; it adds probabilities, suggestions, actual baseline, response model and usage. An intent without a terminal remains unknown and is not replayed. A different directory represents an explicit new experiment.
-
-With a Flywheel version that provides `shadow prepare|run|report`:
-
-```bash
-flywheel shadow prepare --task-dir docs/my-task > /tmp/jev-cases.json
-# Review the summary before sending it; supply MEROUTER_API_KEY in your environment.
-flywheel shadow run --input /tmp/jev-cases.json \
-  --directory /tmp/my-jev-experiment \
-  --endpoint https://merouter.play.one2x.ai/v1/systemone \
-  --max-calls 20 --timeout 5s
-flywheel shadow report --input /tmp/jev-cases.json \
-  --directory /tmp/my-jev-experiment
-```
-
-These explicit commands remain usable with automatic observation disabled. They do not start or mutate a task. Preparation requires a prepared or quiescent task. Reporting is offline and needs no key. For an automatic capture, use its `cases.json` as input. Copy it elsewhere before adding independent labels (`mode`, `status`, `author`, `reason`); labels are excluded from both requests and prediction cache identity. Preserve original captures.
-
-Datasets are limited to 100 cases and 1 MiB, requests to 64 KiB. Explicit `--max-calls` is 1–100; timeout is at most 30 seconds. A batch exceeding the new-call limit is rejected before dispatch. There are no HTTP redirects or retries; error response bodies are not logged. Commands print one JSON document on stdout, errors on stderr. Exit codes: 0 report success, 1 invalid input/runtime failure, 3 failed/unknown/not-run cases, 143 cancellation.
-
-## Interpretation
-
-Eight atomic Noul questions use fixed experimental thresholds: every positive condition ≥0.8 and every risk ≤0.2 yields a Quick candidate; any risk ≥0.8 yields Full; otherwise abstain. The manifest pins questions, thresholds and versions. Individual probabilities are not an overall accuracy score. Unexpected response models abstain until an operator reviews and updates the pin.
-
-This policy is **not production calibrated**. Reports separate decision-time, prepared, replay, historical and synthetic cases, and provisional versus confirmed labels. Current historical state need not be its initial Auto decision. Missing/provisional labels do not establish a false-Quick rate. Auto already uses preparation-time contract evidence; this experiment adds usage rather than removing a classifier call that never existed.
-
-The [six historical summaries](../evaluation/jev-historical-provisional.json) reference completed commits, with unknown actual modes and provisional labels. They test the interface and expose counterexamples, not production benefits. Real automatic workflow routing would require independently confirmed decision-time samples and measured false-Quick/abstention rates. There is no JEV Quick/Full routing switch. The separate bounded diagnostic decision policy cannot inherit this experiment's permissions or thresholds.
+The current [JEV decisions guide](jev.md) describes the single `jev.enabled` switch, actual diagnostic adoption, evidence-based collection controls and evaluation tools. The old automatic shadow observer and separate network client have been retired. Historical results remain in the [original validation record](../validation/2026-11-10-jev-shadow.md).

package/docs/en/jev.md

@@ -0,0 +1,240 @@
+# JEV decisions
+
+[Documentation](../README.md) · English · [简体中文](../zh-CN/jev.md)
+
+Flywheel has one JEV switch: **Enable JEV** (`jev.enabled`). It is off by default.
+Enabling it activates every supported JEV decision point automatically. There is
+no separate shadow, advice, adoption, or per-feature switch in the task workflow.
+
+## Enable once, use the usual task entries
+
+In the desktop, open **Flywheel → Settings → JEV** and choose the intended global
+or project scope. Turn on **Enable JEV** to reveal the connection fields, fill or
+confirm the System One endpoint, fixed model version and credential
+environment-variable name, then select **Save changes**. The switch edits a draft;
+activation takes effect when you save. Editing and saving do not test service
+connectivity. Tasks do not ask for the same approval again.
+
+The process running Flywheel must receive that environment variable. Configuration
+stores its name, never its value. Advanced fields bound timeout, call count,
+thresholds and shared data.
+
+`key-env` accepts 1–120 ASCII letters, digits and underscores, beginning with a
+letter or underscore. Uppercase, lowercase and mixed-case names retain their exact
+spelling when an investigation freezes its configuration and reloads its state.
+
+The equivalent configuration section is:
+
+```json
+{
+  "jev": {
+    "enabled": true,
+    "endpoint": "https://your-service.example/v1/systemone",
+    "model": "jev-1.14.0",
+    "key-env": "MEROUTER_API_KEY",
+    "timeout-ms": 5000,
+    "max-calls": 8,
+    "min-applicability": 0.8,
+    "min-choice": 0.6,
+    "allowed-data": ["task-summary", "diagnostic-facts", "source"]
+  }
+}
+```
+
+Replace the example endpoint with your service. The model must be a fixed
+`jev-x.y.z` version matching the response. The distributed template leaves the
+endpoint empty and JEV disabled. Enabled configurations with an invalid target
+fail validation. Missing credentials at execution keep the deterministic baseline.
+Existing decision/request records preserve their actual skip or failure reasons;
+an implementation task can fail a precondition before creating its first runtime
+decision ledger, so not every bypass has a receipt.
+
+Configuration selects **one complete file** in task → project → global → embedded
+order. A project configuration that leaves JEV off overrides a globally enabled
+configuration; fields are not merged across files. Use `config inspect --cwd
+<project> --task-dir <task> --json` to inspect the actual source. See
+[configuration](configuration.md) for discovery and editing.
+
+Use the normal entries after configuration:
+
+- **Task** prepares and runs authorized investigation or implementation from your goal. Go resolves
+  the JEV policy automatically; the host does not handwrite a decision mode.
+- **New** prepares an investigation contract or an implementation proposal and stops before execution.
+- **Run** starts or resumes the prepared investigation or implementation task in its original directory.
+- Auto, Quick and Full remain implementation workflow choices. Their eligibility,
+  acceptance and review requirements continue to be enforced by Go.
+
+## What the switch controls
+
+| Decision point | JEV enabled | JEV disabled |
+| --- | --- | --- |
+| Next evidence action | Choose among approved reads, searches, directory lists, diagnostic commands and HTTP queries when the choice is uncertain | Original deterministic action order |
+| Redundant evidence collection | May defer remaining actions for an already observed hypothesis through an evidence-bound control choice | Original action set remains |
+| Enough evidence for a report | May end collection early once the engine's evidence prerequisites are met | Collection ends at the original action, time or output limit |
+| Next step after a confirmed failure | Choose among legal local repair, feedback-check and replanning candidates | Existing bounded repair and escalation rules |
+| Model / effort selection | Choose a complete approved execution binding and record the actual switch | Existing fixed binding and deterministic quality/channel fallback |
+| Feedback-check priority | Select an approved check to collect facts before continuing bounded execution | Existing feedback and acceptance order |
+| Explicit online evaluation | Available under the same enabled setting, target and configured limits | Refused before a request or evaluation journal is created |
+| Recorded offline replay | Local parser/evaluation tool; no model call | Still readable; no model call |
+
+“All supported decision points” does not mean every task makes a JEV request.
+Single legal actions and deterministic choices execute directly. Missing data
+permission, hard budgets without an enforceable request ceiling, exhausted calls,
+low applicability, errors and invalid responses retain the baseline. Any decision
+or request records already created preserve their actual reasons; preconditions
+that fail before recording do not imply a new skip receipt.
+Auto still uses Go contract eligibility to choose Quick or Full. Entry routing does
+not gain a mandatory JEV classification request.
+
+Early finish and deferred actions are collection decisions, not proof of a root
+cause. Go records the exact decision, observation and action bindings. The analyst
+must still submit a report covering all hypotheses with actual observation
+references and any uncertainty. An inconclusive report remains inconclusive. A
+repair still needs its originally authorized scope and the ordinary implementation,
+review and verification flow. See [investigation](investigation.md).
+
+## Next steps after failure and model selection
+
+Before generating candidates, the engine confirms that the previous invocation has
+ended, its result has been consumed, candidate/failure evidence can be reconciled,
+and attempts and budget remain. JEV returns a concrete action ID. Go rechecks the
+identity and current switch and persists selection/effect atomically. Existing
+failure caps, one-way Quick → Full upgrades, full acceptance and independent Review
+remain effective. JEV cannot treat an unknown executor outcome as permission to retry.
+
+| Action | Effect | Prerequisite |
+| --- | --- | --- |
+| `repair` | Continue local repair within the same packet | Another execution attempt and budget remain legal |
+| `feedback-N` | Run one short check from the contract's `feedback-checks` and supply its physical result to the next attempt | The check is explicitly approved and has a `purpose`; models cannot create or change its command |
+| `recheck-N` | Rerun a failed L1 check with a complete prior observation to collect fresh feedback | The check belongs to frozen acceptance and its failure is confirmed |
+| `replan` | Use the existing bounded planning / workflow-upgrade path | Planning is legal, with original scope, revision limits and history retained |
+| `model-N` | Select a specific allowed execution configuration | `execution-policy` is configured and the complete binding and switch limits are valid |
+
+`N` indexes the frozen candidate set; it is not a model name or arbitrary command.
+A model candidate resolves to its actual binding ID, harness, Provider, account channel,
+model, effort, permission and session policy. Missing approved candidates do not
+authorize guessing a model name or adding a paid channel. Model/effort changes
+retain the existing cold-start rules and never pass Executor history to Reviewer.
+AUTH/QUOTA and other channel failures keep their corresponding fallback rules;
+they are not evidence of insufficient reasoning ability. See
+[configuration](configuration.md) for the allowed binding set.
+
+A short check's `purpose` is a nonblank description of 1–160 characters. The JEV
+candidate sends this description without appending the `cmd`/`script` text. Keep
+secrets, raw logs and commands out of the description itself.
+Entries without `purpose` remain available to Executor but do not become targeted
+JEV candidates. This field belongs only to `feedback-checks`; it does not extend
+acceptance fields or task authority.
+
+A feedback check supplies evidence for the next action. Even if it passes, the
+engine still runs every required acceptance check against the final candidate;
+the choice cannot remove checks. Task and node views show the request, adoption or
+baseline reason, feedback check and recorded effect. `applied` means the control
+decision was applied; subsequent repair, planning and model sessions remain in
+the node records. `completed` means this control action settled, not that the whole
+task was delivered. `feedback-completed` likewise means only that feedback settled.
+`pending` requires request reconciliation. `feedback-running` and `feedback-unknown`
+require the original action to be reconciled and must not be replayed automatically.
+`feedback-stale` blocks execution because feedback changed candidate or verification
+inputs. `replan-running` means replanning has not settled; recovery must reconcile
+the original Plan session rather than dispatching again to guess its outcome.
+Applied model changes show the actual before/after bindings, attempt,
+reason and time. The UI never guesses a model from `model-N` or treats a configuration
+change as proof that a new session ran successfully.
+
+## Data, budgets and recovery
+
+For an investigation, Go freezes the effective JEV target, data categories,
+thresholds and call budget when preparation is created. Task-provided historical `decision` modes cannot turn
+JEV on while the effective master setting is off. The default enabled data set
+allows the task summary, diagnostic hypotheses, structured command/HTTP outcomes,
+and bounded excerpts of approved file evidence. `allowed-data` can narrow this set.
+Raw command/HTTP output is included only with explicit `logs` permission; otherwise
+the snapshot records that missing content and uses structured facts. Permission is
+not automatic redaction: any remaining unauthorized category skips the complete
+request, and summarization cannot bypass the original data policy.
+
+Disabling the setting stops subsequent JEV dispatches and adoption in existing
+runs, including a result returned after the switch was disabled. Already dispatched
+requests are reconciled using their frozen identity, and their known or unknown
+usage is retained. Unknown requests are not retried. Unknown **action** outcomes
+still block execution until reconciled.
+
+An investigation preparation created while JEV was off stays on its baseline;
+enabling JEV does not rewrite that preparation. A newly created preparation can
+freeze the enabled policy.
+
+Implementation freezes its own runtime decision policy at the first eligible
+failure in an enabled run. If the current process started with JEV off and has no
+runtime decision ledger, saving an enabled setting does not activate that process
+immediately: start or resume the task so it reads the enabled configuration. Once a
+runtime decision ledger exists, turning JEV off and back on retains its frozen
+target, records and remaining allowance, including imported investigation calls.
+Changes that invalidate a frozen target or tighten its permissions/limits disable
+further optional decisions rather than silently rewriting the policy. Check the
+reported JEV status and reason; do not copy ledgers or reset budgets to bypass it.
+
+`max-calls` is a task allowance that includes unknown dispatched requests. Calls
+used during investigation are imported into implementation's allowance. Multiple
+packets, model switches, replanning and resume cannot reset it. This is a call cap,
+not a guaranteed token or currency ceiling. A configured hard budget skips JEV when
+the service cannot enforce a provable per-request bound. Requests record actual
+usage when available; missing usage remains unknown.
+
+Implementation's `runtime-decisions` record lives in `state.json` and retains the
+frozen policy, used/imported call counts, requests, selections and effects. It
+follows the existing state commit and delivery rules. The request journal under
+`.investigation/runtime-decisions` is private and excluded from automatic delivery;
+that exclusion does not apply to the copy of decision information in `state.json`.
+
+The desktop displays bounded summaries and omits raw snapshots and target
+configuration from its projection. This display projection does not redact Git
+delivery. As with existing failure feedback, approved goals, facts, bindings and
+feedback output must follow the existing rule against recording credentials.
+Pending requests/actions are reconciled in their original task, without a new
+journal or model switch bypassing an unknown outcome.
+
+## Replay and explicit evaluation
+
+Normal tasks save frozen `*.input.json` documents and receipts in their private
+decision journal. Offline replay also accepts historical `*.snapshot.json` captures:
+
+```bash
+flywheel decision replay --input frozen.input.json --response native-response.json \
+  --endpoint "$JEV_ENDPOINT" --model jev-1.14.0 --expected-model jev-1.14.0
+```
+
+Replay reads no credential, makes no HTTP request and writes no journal or task
+state. A bare Snapshot requires `--policy reviewed-policy.json`; an explicit policy
+replaces the complete captured policy rather than inheriting missing fields.
+
+For a deliberate online evaluation, enable JEV in the relevant scope first:
+
+```bash
+flywheel decision evaluate --cwd "$repo_dir" --input frozen.input.json \
+  --directory ./decision-evaluation --max-calls 5
+```
+
+The endpoint, fixed model and credential variable come from the same configuration.
+Legacy explicit target flags must match it. Evaluation forces advisory behavior;
+it never dispatches an action or changes task state. Its call cap, timeout,
+thresholds and data categories cannot loosen the configured bounds. Reusing an
+input and journal reads the original receipt; it does not resend an unknown call.
+
+Both tools return `adopted: false`. Live failures and unknown outcomes return exit
+code 3, input/configuration errors return 1, and cancellation returns 143. Offline
+fixture success is not evidence of live model accuracy or lower task latency.
+
+## Migration from shadow evaluation
+
+The old automatic observer and separate shadow network client have been removed.
+Old `jev-shadow` configuration remains readable for migration: connection hints are
+retained, but the old enabled flag never activates online decisions. An explicit
+new `jev` section takes precedence. Saving through the editor writes the unified
+section and removes the legacy key while preserving the normal backup/revision
+checks. The retired `shadow` command reports the migration path without running
+an experiment. Historical records and their schema remain available as evidence.
+
+To assess value, compare complete tasks with JEV off and on: time to useful evidence,
+actions performed/deferred, total latency, actual/unknown usage, and final quality.
+A different action order or a passing fixture alone does not establish a speedup.

package/docs/en/model-policy.md

@@ -125,6 +125,13 @@ attempt/token budgets and an explicit switch limit. This deterministic rule
 does not prove the next model is better. Channel errors use separately declared
 fallbacks; neither mechanism may select an undeclared model or payment channel.
 
+When the single [JEV switch](jev.md) is enabled, a confirmed failure can also
+offer the already allowed bindings as decision candidates. The engine checks
+the frozen allowlist, permission, remaining attempts and switch budget before
+adoption. No extra JEV model-routing switch is required. Without an allowed
+alternative, the configured binding stays in use. A semantic choice is recorded
+as a choice, not as measured proof that the selected model is faster or better.
+
 Effort changes cold-start the role and record complete before/after bindings.
 Comparisons must include rereading, startup and actual known/unknown usage and
 cost. Offline tests run real engine repair and recovery paths with controlled