@getmagical/cli 0.14.4 → 0.15.4

package/README.md

@@ -124,10 +124,10 @@ feasibility evaluations, reported with actual evaluations in `targetDiscovery`.
 This read-only command does not generate definitions,
 backfill signatures, or start runs.
 
-Only record-mode runs with status `COMPLETE` or `EARLY_TERMINATION` and a recorded
-finish timestamp qualify, including implicit and explicit recordings, with
-draft/test runs excluded. Runs missing `finished_at` are excluded even when their
-status indicates completion.
+Only record-mode runs with status `COMPLETE` or `EARLY_TERMINATION` and recorded
+start and finish timestamps qualify, including implicit and explicit recordings,
+with draft/test runs excluded. Runs missing `started_at` or `finished_at` are
+excluded even when their status indicates completion.
 `--max-candidate-runs` accepts 1–10,000 and defaults to **1,000**; the limit applies
 before classification. Compatible signatures identify historical pathways without
 requiring a deviation-free run. Each historical input must also satisfy the
@@ -187,6 +187,12 @@ Human-readable output includes target pathway keys and labels, required nested
 calls, opaque steps, distinct-input counts, `1/2 selected` recording counts, gaps,
 and diagnostics. Input-only examples include their original inputs and work-item
 IDs. JSON also includes recorded samples' original inputs and signature evidence.
+Each scenario reports `observedRunCount`: the number of runs in the searched history
+(see `--max-candidate-runs`) that match the scenario, including runs that cannot
+become samples. JSON also gives `averageDurationMs`: the mean time from start to
+finish of those runs, in whole milliseconds, including any pause. It is null when
+the scenario has no observed run. A null value while `observedRunCount` is greater
+than 0 means that the server does not send the field.
 Errors and warnings go to stderr; `--json` stdout remains valid JSON, including partial results.
 A scenario is covered after its first verified recording, independently of the
 requested sample count.
@@ -457,14 +463,14 @@ transfer, including response-body streaming, has a separate 120-second
 deadline.
 
 Local inspection uses mitmproxy's supported archive reader and requires Python
-3.12 or newer with exactly `mitmproxy==12.2.3`. mgcl does not install this
-optional runtime. Create a dedicated environment and point mgcl at its Python
-executable:
+3.12 or newer with `mitmproxy==12.3.0`; existing `12.2.3` environments remain
+supported. mgcl does not install this optional runtime. Create a dedicated
+environment and point mgcl at its Python executable:
 
 ```bash
-python3 -m venv ~/.local/share/mgcl/mitmproxy-12.2.3
-~/.local/share/mgcl/mitmproxy-12.2.3/bin/python -m pip install 'mitmproxy==12.2.3'
-export MGCL_MITMPROXY_PYTHON=~/.local/share/mgcl/mitmproxy-12.2.3/bin/python
+python3 -m venv ~/.local/share/mgcl/mitmproxy-12.3.0
+~/.local/share/mgcl/mitmproxy-12.3.0/bin/python -m pip install 'mitmproxy==12.3.0'
+export MGCL_MITMPROXY_PYTHON=~/.local/share/mgcl/mitmproxy-12.3.0/bin/python
 ```
 
 Exchange output includes a recording-specific stable reference, flow ordinal,
@@ -645,19 +651,24 @@ Replay also requires `captures:read`; supplying `--initial-store-json` requires
 required for starts without replay, recording runs, and reruns. The sandbox
 grant does not authorize published or live execution paths.
 
+`verifications:write` allows `verification-records upload`. The key owner must
+also be a Magical employee. Reading verification records and verdicts requires
+only `runs:read`.
+
 ### Operator rollout and rollback
 
 Deploy the backend before releasing the CLI flow. In WorkOS, create these
 permissions and grant the appropriate subset to member roles. Also enable
-`draft-runs:execute-sandbox` under Authorization > Configuration > API key
-permissions > Users before user API keys can include it:
+`draft-runs:execute-sandbox` and `verifications:write` under Authorization >
+Configuration > API key permissions > Users before user API keys can include
+them:
 
 ```text
 automations:read automations:write runs:read runs:execute runs:control
 draft-runs:execute-sandbox
 store:read store:write skills:read skills:write credentials:read
 captures:read captures:write regressions:read regressions:run
-knowledge:read memory:read files:write
+knowledge:read memory:read files:write verifications:write
 ```
 
 The Knowledge Base, Memory, and replay-upload commands remain pending until the