@getmagical/cli 0.14.2 → 0.14.4

package/README.md

@@ -98,6 +98,15 @@ immutable automation version:
 mgcl pathway-regression coverage --automation-version-id <uuid> --org <org> --max-candidate-runs 1000 --runs-per-scenario 2 --max-recording-checks 100 --json
 ```
 
+Use `--starting-agent-id <uuid>` to restrict the report to one starting agent and
+its descendants. The ID must identify a top-level agent in the supplied version;
+imported library agent IDs are also accepted. Historical runs are filtered to
+runs started by the selected agent before `--max-candidate-runs` is applied.
+Descendant agent executions within those runs remain included; separately
+started descendant runs are excluded. This works with
+`--ignore-unsupported-agent-types` as well. Omit the option to cover all starting
+agents. The report echoes the filter in `startingAgentId` (`null` when omitted).
+
 The supplied version determines the target scenarios. Compatible historical runs
 from any version of the same automation can supply examples. Scenario identity
 uses durable agent pathway keys and required nested calls. Required agents must
@@ -115,8 +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` qualify,
-including implicit and explicit recordings, with draft/test runs excluded.
+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.
 `--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
@@ -547,6 +558,15 @@ organization. The CLI validates identity and necessary permissions before the
 business request and never retries that request under another key. Organization
 discovery also rejects configured keys owned by different users.
 
+Key metadata is cached locally for 10 minutes per API origin, so a burst of
+commands validates each key once. The cache file name is a SHA-256 digest and
+never contains the key. `mgcl auth status`, `mgcl org list`, and `mgcl org use`
+always re-validate. A command re-validates before reporting a missing
+permission, and any request the server rejects with 401 evicts the cached
+metadata. When the server answers 429, mgcl waits for `Retry-After` (or backs
+off 1s, 2s, 4s) and retries up to three times, giving up at once when asked to
+wait longer than 30 seconds.
+
 Use live, sanitized metadata to inspect or choose an organization:
 
 ```bash