@orkestrel/scaffold 0.0.134 → 0.0.135

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +610 -79
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +307 -16
  3. package/dist/bin/main.js +253 -35
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/AGENTS.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  7. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +782 -115
  8. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
  10. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +379 -27
  11. package/dist/host/claude/agents/orkestrel.md +14 -14
  12. package/dist/host/claude/rules/architecture.md +1 -1
  13. package/dist/host/claude/rules/patterns.md +2 -0
  14. package/dist/host/claude/rules/workspace.md +64 -63
  15. package/dist/host/configs/helpers.ts +88 -67
  16. package/dist/host/dotfiles/oxlintrc.json +1 -57
  17. package/dist/host/guides/agent.md +989 -395
  18. package/dist/host/guides/database.md +357 -342
  19. package/dist/host/guides/middleware.md +5 -5
  20. package/dist/host/guides/ollama.md +41 -42
  21. package/dist/host/guides/scaffold.md +177 -105
  22. package/dist/host/guides/study.md +12 -12
  23. package/dist/host/guides/test.md +158 -46
  24. package/dist/host/guides/toolbox.md +127 -81
  25. package/dist/host/guides/workspace.md +21 -14
  26. package/dist/host/manifest.json +23 -23
  27. package/dist/host/tests/config.test.ts +166 -112
  28. package/dist/src/core/index.cjs +491 -195
  29. package/dist/src/core/index.cjs.map +1 -1
  30. package/dist/src/core/index.d.cts +217 -24
  31. package/dist/src/core/index.d.ts +217 -24
  32. package/dist/src/core/index.js +482 -193
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +18 -8
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +4 -3
  37. package/dist/src/server/index.d.ts +4 -3
  38. package/dist/src/server/index.js +19 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +2 -2
@@ -129,7 +129,7 @@ The `triage` role sends System One requests to `/v1/systemone`. Its `StudySystem
129
129
 
130
130
  A provider declares `triage` and `digest.triage` together. Both metadata passes verify the pin through tags and show, configuration identity retains it, and a declared daemon includes it in its verified maintenance population. A transport fault on this leg fails the trial even if the consumer catches it; it cannot produce successful recording completion. A well-transported answer the consumer semantically refuses remains the consumer's decision to refer onward. Study chooses no model name or probability cutoff.
131
131
 
132
- Recording reads version and optional procedure from the exchange sink's opening declaration. The transport refuses metadata or model pins that differ from that row. Preflight and postflight verify version, tags, and show for each distinct pinned model. Ordered exact steps compare UTF-8 bytes and verify their declared SHA-256 receipt; capture steps require their declared positive safe byte length and forbid body or input members. Goal, role, route, policy, and order are checked before sending. A second request and verification during request admission refuse. The sink supplies each HTTP ordinal, which joins dispatch and wire evidence even without passive observation. An attempt retains request bytes before sending. A validated response retains native status, selected headers, exact bytes, and chunk lengths; a failure retains bounded partial bytes and cannot produce completion. Successful postflight appends completion after the admitted execution sequence; a declared procedure also requires every step to finish. The parent composes the declaration, and the worker retains that row after verifying any maintenance prefix.
132
+ Recording reads the optional procedure from the exchange sink's opening declaration. The transport refuses metadata or model pins that differ from that row. Preflight and postflight each fetch the serving version, then verify tags and show for each distinct pinned model. The version is an observation for debugging: each pass appends a `version` evidence row to its goal, `{ version }` with the reply's nonempty string or `null` when the reply names none, and Study compares it with nothing, so no recording, replay, or continuation refuses because of a version. The sidecar retains each version reply's exact bytes. Ordered exact steps compare UTF-8 bytes and verify their declared SHA-256 receipt; capture steps require their declared positive safe byte length and forbid body or input members. Goal, role, route, policy, and order are checked before sending. A second request and verification during request admission refuse. The sink supplies each HTTP ordinal, which joins dispatch and wire evidence even without passive observation. An attempt retains request bytes before sending. A validated response retains native status, selected headers, exact bytes, and chunk lengths; a failure retains bounded partial bytes and cannot produce completion. Successful postflight appends completion after the admitted execution sequence; a declared procedure also requires every step to finish. The parent composes the declaration, and the worker retains that row after verifying any maintenance prefix.
133
133
 
134
134
  The transport owns its configuration before validation and snapshots each outbound URL, settings, headers, and request correlation before awaiting admission. Later caller mutation cannot change the admitted request. Cancellation signals, the timing callback, and the optional fetch collaborator retain their live identity.
135
135
 
@@ -216,9 +216,9 @@ The Ollama transport appends a `stop` evidence row after its `wire` row when com
216
216
 
217
217
  ## Native command
218
218
 
219
- Recording declares positive safe `record.bytes`, `record.calls`, and `record.duration` allowances on the profile. The manifest retains the same declaration, and the parent reserves that complete allowance separately for each trial before starting workers. The allowance covers every serialized sidecar byte, including base64 expansion, opening and terminal rows, and LF framing. It consumes series custody without consuming goal evidence or model quota. Recording profiles explicitly supply `settings.version` and `settings.metadata`. Omitting `settings.procedure` selects open recording; supplying it keeps ordered exact or capture admission. The parent calls `buildStudyExchangeDeclaration` with the profile, trial, scenario, and whether it owns a daemon session. Each destination carries that declaration, and the driver, session, and worker check its members against the profile and trial they hold before constructing the adapter driver. The transport takes version and procedure from the sink, with no duplicate options.
219
+ Recording declares positive safe `record.bytes`, `record.calls`, and `record.duration` allowances on the profile. The manifest retains the same declaration, and the parent reserves that complete allowance separately for each trial before starting workers. The allowance covers every serialized sidecar byte, including base64 expansion, opening and terminal rows, and LF framing. It consumes series custody without consuming goal evidence or model quota. Recording profiles explicitly supply `settings.metadata`, and name no serving version. Omitting `settings.procedure` selects open recording; supplying it keeps ordered exact or capture admission. The parent calls `buildStudyExchangeDeclaration` with the profile, trial, scenario, and whether it owns a daemon session. Each destination carries that declaration, and the driver, session, and worker check its members against the profile and trial they hold before constructing the adapter driver. The transport takes the procedure from the sink, with no duplicate options.
220
220
 
221
- The declaration retains `record`, the ordered `goals`, and a `configuration` digest alongside version, pinned models, metadata bounds, maintenance, and optional procedure. Configuration hashes canonical room, settings, and daemon configuration with the daemon executable path omitted. Profile record and elapsed bounds stay outside that digest. Maintenance lists the daemon's declared models when the parent owns a daemon session for this execution, and is empty otherwise.
221
+ The declaration retains `record`, the ordered `goals`, and a `configuration` digest alongside pinned models, metadata bounds, maintenance, and optional procedure. It holds no version, and a declaration that carries one refuses. Configuration hashes canonical room, settings, and daemon configuration with the daemon executable path omitted; the daemon declaration holds no executable digest, so an updated executable leaves configuration unchanged. Profile record and elapsed bounds stay outside that digest. Maintenance lists the daemon's declared models when the parent owns a daemon session for this execution, and is empty otherwise.
222
222
 
223
223
  The `record.calls` allowance counts execution attempts retained by the sidecar, including replayed exchanges. A request past the cap refuses before append or send with CAPACITY and the scope stop Recording calls. The `record.duration` allowance sums execution send-to-settlement milliseconds; metadata retains its independent budget. When the remaining model time binds a request, its recording deadline starts immediately before send and expires with DEADLINE and the scope stop Recording duration. An exhausted allowance refuses before append or send. A refusal keeps prior charges and prevents completion; an admitted attempt retains its failure terminal, including any bounded partial reply. Such a result stays interrupted.
224
224
 
@@ -238,11 +238,11 @@ The `StudyIdentity` interface retains location-independent runtime and content d
238
238
 
239
239
  The replay manifest's ancestor retains the source result id, seal, and complete source identity. The replay sidecar's ancestor also retains its source file identity and exchange prefix. The manifest's own identity describes the executing build, so both contents remain available. The worker rechecks the ancestor and recorded goal prefix. The `scanStudyDivergence` function accepts a strictly read history and strictly read replay rows, aligns non-maintenance attempts by position, and returns the first differing or unmatched request. It performs no second validation. An extra request pairs with the recorded attempt at its position; after the last recorded execution, that is the first postflight request; an early end has no actual attempt. An attempt past the complete recording has no expected attempt and uses the recording's completion count plus one as its ordinal.
240
240
 
241
- Continuation selects `--extend <result>` on check or execute and refuses a simultaneous replay selection. The ancestor must be sealed, recorded in open form, and complete without operational failures or partial products. The executing profile must declare open recording and a dedicated daemon. The definition, driver, ordered trials, runtime, content, version, models, and configuration must match. Every scenario keeps its id and strictly extends its ancestor's goals, including their canonical input values. Fixture identity changes with the grown scenario. Recording and elapsed bounds may rise because they stay outside configuration; no bound rises automatically.
241
+ Continuation selects `--extend <result>` on check or execute and refuses a simultaneous replay selection. The ancestor must be sealed, recorded in open form, and complete without operational failures or partial products. The executing profile must declare open recording, and it can declare a dedicated daemon or none, with empty maintenance. The definition, driver, ordered trials, runtime, content, models, and configuration must match; the serving version and the daemon executable can differ, so a recording continues under a later Ollama. Every scenario keeps its id and strictly extends its ancestor's goals, including their canonical input values. Fixture identity changes with the grown scenario. Recording and elapsed bounds may rise because they stay outside configuration; no bound rises automatically.
242
242
 
243
- The parent derives a live replay prefix ending immediately before each ancestor's postflight. It starts and verifies the daemon, then records live unloads before opening the worker. The worker reconstructs state through the real adapter with exact recorded preflight and execution responses, sending no prefix request to the daemon. It checks the consumed prefix at the ancestor's last goal. An extra request in that goal refuses before forwarding and retains its attempt and failure. The first request in a later goal goes live; postflight verifies the live daemon at the extended horizon's last goal. Each segment's first live goal starts cold, so its timing and cache state can differ from a continuous execution.
243
+ The parent derives a live replay prefix ending immediately before each ancestor's postflight. With a declared daemon, it starts and verifies the daemon, then records live unloads before opening the worker; without one, it records no maintenance and live requests go to the external daemon at the provider URL. The worker reconstructs state through the real adapter with exact recorded preflight and execution responses, sending no prefix request to the daemon. It checks the consumed prefix at the ancestor's last goal. An extra request in that goal refuses before forwarding and retains its attempt and failure. The first request in a later goal goes live; postflight verifies the live daemon at the extended horizon's last goal. With a declared daemon, each segment's first live goal starts cold, so its timing and cache state can differ from a continuous execution; an external daemon keeps whatever models it holds.
244
244
 
245
- The descendant retains a complete flat sidecar: its extended declaration and ancestor prefix, live maintenance, replayed request and response bytes with recorded chunk lengths, live execution, live postflight, and completion. Its manifest links the immediate ancestor, so a later segment needs only that complete descendant. Replayed goals emit their evidence again and count against recording calls; their send-to-settlement time follows the executing recording duration allowance.
245
+ The descendant retains a complete flat sidecar: its extended declaration and ancestor prefix, any live maintenance, replayed request and response bytes with recorded chunk lengths, live execution, live postflight, and completion. Its manifest links the immediate ancestor, so a later segment needs only that complete descendant. Replayed goals emit their evidence again and count against recording calls; their send-to-settlement time follows the executing recording duration allowance.
246
246
 
247
247
  Triage participates in open recording and in exact or capture procedures using its System One route and policy. Strict sidecar reading checks the same identity, ordering, receipts, and completion as for other roles. Prefix and keyed replay retain original response bytes and chunk lengths. An offline replay sends nothing, and a keyed triage miss cannot borrow another role's recorded answer. Replayed triage usage still charges admission budgets, while progress and reports attribute it to `triage`, count it as replayed, and exclude it from live spending. Continuation requires open recording, replays the ancestor goals, and sends only the grown horizon's suffix live. Keyed replay remains exclusive with `--extend`, and every keyed execution still requires recording.
248
248
 
@@ -300,9 +300,9 @@ isStudyExchangeAncestor(reference)
300
300
 
301
301
  The process driver accepts `StudyProcessDriverOptions`. Its optional `prepare` callback runs in the parent before session construction, preserves the reserved destination and allowance, and never crosses structured cloning or IPC. Offline replay refuses a preparation callback. A worker verifies any retained maintenance prefix before resuming the sidecar and projects those ordinals into its first goal's evidence.
302
302
 
303
- A provider's optional `daemon` declaration makes live execution own a dedicated Ollama session at the provider URL. The declaration pins a canonical absolute executable, its SHA-256 digest, the exact version, explicit environment overrides, and distinct model names and inventory digests equal to the provider's model, judge, and triage pins. Shared pins require one entry. A maintenance-only model, a relative executable, port 11434, a missing model digest, or conflicting environment-name casing refuses at profile load. The daemon owns the effective OLLAMA_HOST value. Without this declaration, the provider URL selects an external daemon.
303
+ A provider's optional `daemon` declaration makes live execution own a dedicated Ollama session at the provider URL. The declaration names a canonical absolute executable, explicit environment overrides, and distinct model names and inventory digests equal to the provider's model, judge, and triage pins. It names no executable digest and no version, and a declaration that carries either refuses. Shared pins require one entry. A maintenance-only model, a relative executable, port 11434, a missing model digest, or conflicting environment-name casing refuses at profile load. The daemon owns the effective OLLAMA_HOST value. Without this declaration, the provider URL selects an external daemon.
304
304
 
305
- The `StudyDaemonSession` class starts and verifies the daemon before trial execution. The manifest's `host.daemon` string retains the verified startup identity; startup version and inventory probes belong to no trial sidecar. Before each trial worker opens, preparation unloads the declared models in order. The `StudyDaemonTrial` class synchronizes each maintenance attempt before sending, retains status, allowed headers, original sender chunk lengths, and exact body bytes, and closes the prefix after daemon validation. A failed exchange retains a failure row. The worker joins the maintenance ordinals to the scenario's first declared goal. Every execution ending awaits daemon stop and process-tree join; an unconfirmed cleanup refuses completion. Offline replay constructs no daemon or preparation callback and sends no maintenance request.
305
+ The `StudyDaemonSession` class starts and verifies the daemon before trial execution. Each start reads the executable's SHA-256 and hands it to the daemon as the identity to start. The manifest's `host.daemon` string retains the verified startup identity, including that digest and the version the daemon reported. Study compares neither with an earlier reading, so an updated executable or version never refuses a run. Startup version and inventory probes belong to no trial sidecar. Before each trial worker opens, preparation unloads the declared models in order. The `StudyDaemonTrial` class synchronizes each maintenance attempt before sending, retains status, allowed headers, original sender chunk lengths, and exact body bytes, and closes the prefix after daemon validation. A failed exchange retains a failure row. The worker joins the maintenance ordinals to the scenario's first declared goal. Every execution ending awaits daemon stop and process-tree join; an unconfirmed tree stop refuses completion, and an executable that changed or became unreadable while the daemon ran refuses nothing. Offline replay constructs no daemon or preparation callback and sends no maintenance request.
306
306
 
307
307
  Install the package in the consumer workspace, then run the study executable from that workspace. The selected declaration lives at studies/<name>/study.json, and its declared rubric path resolves inside that same directory. Its driver field selects a bundle at studies/<driver>/ containing scenarios/<scenario>.json, profiles/<profile>.json, and the adapter module index.ts. Several declarations can share one driver bundle while each keeps its own rubric. The profile defaults to local. JSON declarations use the public definition, scenario, profile, and rubric contracts.
308
308
 
@@ -405,7 +405,7 @@ The following declarations describe this concept.
405
405
  | `STUDY_CHECKPOINT_EVENT` | const | `"checkpoint"` | Names the evidence event whose row a seeded execution hands its trial at open. |
406
406
  | `STUDY_COMMAND_DURATION` | const | `86400000` | Caps declared execution duration at the native supervisor's host ceiling. |
407
407
  | `STUDY_COMMAND_GRADER` | const | `"consumer-adapter"` | Names the trusted command's independent offline predicate. |
408
- | `STUDY_COMMAND_HELP` | const | `"study check <study> [--profile <name>] [--closure <directory>] [--extend <result>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy freeze <study> --profile <name> --to <directory>\nstudy execute <study> [--profile <name>] [--out <path>] [--expected <sha256>] [--closure <directory>] [--extend <result> \| --replay <result> --prefix <JSON trial counts> --offline <true\|false> \| --replay <result> --roles <JSON roles> --offline <true\|false>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy grade <result> --rubric <path>\nstudy label <result> --assessment <sha256> --labels <path>\nstudy report <result> --assessment <sha256>\nstudy progress <result> [--from <goal>]\nstudy --help\nstudy --version\n\nProfiles default to local; freeze requires --profile. Flags require values and may appear only once.\nResults default to tmp/studies/<result>; scratch also uses tmp/studies.\nA result is its id under tmp/studies, a root-relative path, or an absolute path.\nRelative paths, including --out, must stay inside the consumer working directory.\nOutput directories must be new; existing results are never overwritten.\n--expected pins the fingerprint returned by check. --assessment selects an exact assessment.\n--rubric selects independent criteria. --labels imports caller-supplied semantic labels.\n--closure selects retained artifacts. Replay requires explicit prefix counts or roles, and offline behavior.\n--roles serves a listed role's request whose path, method, and body bytes equal a recorded attempt's.\n--extend continues a sealed open recording with further goals and requires a declared daemon.\ncheck carries --extend into next and binds the ancestor seal into its fingerprint.\ncheck binds --trial, --goals, and --seed into its fingerprint and carries them into next.\nSuccess writes one JSON document; next contains suggested argv, never executed automatically.\ncheck, freeze, grade, label, report and progress have a fixed allowance of 60 seconds.\nexecute checks first, then uses the declared series duration plus 15 seconds for cleanup.\nExit codes: 0 success, 64 invalid input, 124 deadline, 130 interruption, 1 operational failure.\n"` | Defines the complete public CLI reference shared by help and grammar diagnostics. |
408
+ | `STUDY_COMMAND_HELP` | const | `"study check <study> [--profile <name>] [--closure <directory>] [--extend <result>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy freeze <study> --profile <name> --to <directory>\nstudy execute <study> [--profile <name>] [--out <path>] [--expected <sha256>] [--closure <directory>] [--extend <result> \| --replay <result> --prefix <JSON trial counts> --offline <true\|false> \| --replay <result> --roles <JSON roles> --offline <true\|false>] [--trial <name>] [--goals <first>..<last>] [--seed <result>:<trial>:<goal>]\nstudy grade <result> --rubric <path>\nstudy label <result> --assessment <sha256> --labels <path>\nstudy report <result> --assessment <sha256>\nstudy progress <result> [--from <goal>]\nstudy --help\nstudy --version\n\nProfiles default to local; freeze requires --profile. Flags require values and may appear only once.\nResults default to tmp/studies/<result>; scratch also uses tmp/studies.\nA result is its id under tmp/studies, a root-relative path, or an absolute path.\nRelative paths, including --out, must stay inside the consumer working directory.\nOutput directories must be new; existing results are never overwritten.\n--expected pins the fingerprint returned by check. --assessment selects an exact assessment.\n--rubric selects independent criteria. --labels imports caller-supplied semantic labels.\n--closure selects retained artifacts. Replay requires explicit prefix counts or roles, and offline behavior.\n--roles serves a listed role's request whose path, method, and body bytes equal a recorded attempt's.\n--extend continues a sealed open recording with further goals; the profile can omit a daemon.\ncheck carries --extend into next and binds the ancestor seal into its fingerprint.\ncheck binds --trial, --goals, and --seed into its fingerprint and carries them into next.\nSuccess writes one JSON document; next contains suggested argv, never executed automatically.\ncheck, freeze, grade, label, report and progress have a fixed allowance of 60 seconds.\nexecute checks first, then uses the declared series duration plus 15 seconds for cleanup.\nExit codes: 0 success, 64 invalid input, 124 deadline, 130 interruption, 1 operational failure.\n"` | Defines the complete public CLI reference shared by help and grammar diagnostics. |
409
409
  | `STUDY_COMMAND_OPERATION` | const | `"study-command"` | Names the command route beneath the native supervisor. |
410
410
  | `STUDY_CUSTODY_BYTES` | const | `number` | Limits untrusted metadata before JSON parsing or file allocation. |
411
411
  | `STUDY_DRAIN_DURATION` | const | `1000` | Bounds how long inherited output handles stay open after native exit, in milliseconds. |
@@ -749,7 +749,7 @@ The following declarations describe this concept.
749
749
  | `readStudyDeclarationBytes` | function | `(root: string, path: string) => Promise<Uint8Array>` | Reads one declaration file and refuses a missing or linked path with its root-relative path. |
750
750
  | `readStudyVersion` | function | `(entry: string) => string` | Reads the version of the study package that owns an executable entry. |
751
751
  | `matchesSystemError` | function | `(value: unknown, code: string) => boolean` | Reports whether a caught value is a Node error carrying the given system code. |
752
- | `StudyDaemon` | interface | `{ executable, digest, version, environment?, models }` | Pins an executable and the model population an execution owns until cleanup. |
752
+ | `StudyDaemon` | interface | `{ executable, environment?, models }` | Pins an executable and the model population an execution owns until cleanup. |
753
753
  | `StudyDaemonModel` | interface | `{ name, digest }` | Pins one model the declared daemon verifies and unloads before each trial. |
754
754
  | `StudyRecord` | interface | `{ bytes, calls, duration }` | Bounds serialized exchange bytes, execution calls and summed model time for each trial. |
755
755
  | `ArtifactErrorCode` | type | `'ARTIFACT' \| 'TRAVERSAL' \| 'REDIRECT' \| 'ALIAS' \| 'NAME' \| 'DUPLICATE' \| 'OCCUPIED' \| 'OVERLAP' \| 'PARENT' \| 'STALE' \| 'VOLUME' \| 'DRIFT' \| 'LIMIT'` | Names the refused boundary of a captured or materialized artifact graph. |
@@ -782,7 +782,7 @@ The following declarations describe this concept.
782
782
  | `StudyExchangeDestination` | interface | `{ path, declaration, retained? }` | Holds the parent-reserved destination of one trial's exchange sidecar. |
783
783
  | `StudyExchangeBytes` | interface | `{ body, digest, size }` | Retains an application HTTP body's exact bytes independently of text decoding. |
784
784
  | `StudyExchangeIdentity` | interface | `{ ordinal, goal, role, path, method, stage, step? }` | Binds one HTTP exchange to its trial-local position and declared execution stage. |
785
- | `StudyExchangeDeclaration` | interface | `{ phase, trial, version, models, metadata, record, goals, configuration, procedure?, maintenance, ancestor?, keyed? }` | Declares a bounded trial horizon and serving identities before any exchange attempt. |
785
+ | `StudyExchangeDeclaration` | interface | `{ phase, trial, models, metadata, record, goals, configuration, procedure?, maintenance, ancestor?, keyed? }` | Declares a bounded trial horizon and serving identities before any exchange attempt. |
786
786
  | `StudyExchangeAttempt` | interface | `{ phase }` | Retains admitted request bytes durably before the corresponding send begins. |
787
787
  | `StudyExchangeReply` | interface | `{ status, headers, chunks }` | Retains response status, headers, and original application-body chunk lengths. |
788
788
  | `StudyExchangeResponse` | interface | `{ phase }` | Retains a fully consumed response only after status and terminal validation succeed. |
@@ -3346,7 +3346,7 @@ try {
3346
3346
 
3347
3347
  ## Tests
3348
3348
 
3349
- The staging proofs drive the real command and worker over a Node protocol daemon on an ephemeral loopback port. The daemon records whether each unload's attempt was already readable on disk. The source suite proves repeated maintenance prefixes, exact ordinal joins, offline replay without a daemon or request, and startup, trial, unload, and cancellation cleanup while an unrelated sentinel survives. Setup proofs validate fixture declarations without starting a child.
3349
+ The staging proofs drive the real command and worker over a Node protocol daemon on an ephemeral loopback port. The daemon records whether each unload's attempt was already readable on disk. The source suite proves repeated maintenance prefixes, exact ordinal joins, offline replay without a daemon or request, startup, trial, unload, and cancellation cleanup while an unrelated sentinel survives, and a stop that completes after the executable changed under the running daemon. Setup proofs validate fixture declarations without starting a child.
3350
3350
 
3351
3351
  ### Call exchange and replay helpers
3352
3352
 
@@ -30,6 +30,10 @@ at the type boundary, where a value nothing declares meets a claim its caller ow
30
30
  `flattenHeaders` is outside them on the comparison side, turning any header initializer into one
31
31
  frozen record.
32
32
 
33
+ `ProgressReporter` and `readProgress` sit outside them on the runner side: the reporter appends
34
+ one JSON line per Vitest run event to a file while the run is live, and the reader summarizes that
35
+ file at any moment, so a long run's progress and its first failure are readable before it ends.
36
+
33
37
  The journey layer drives a real interface by role and accessible name through the installed Vitest
34
38
  provider, measures what a reader can see of the result, records the scenario and the page's own
35
39
  output as it goes, and generates the capture portfolio from the same journeys. Around it sit the
@@ -60,10 +64,12 @@ npm install --save-dev @orkestrel/test
60
64
  ```
61
65
 
62
66
  `@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face — the
63
- filesystem helpers, the process and socket readings, the cookie jar, and the pure leaves they are
64
- built from. `@orkestrel/test/browser` is the
67
+ filesystem helpers, the process and socket readings, the cookie jar, the Vitest progress reporter
68
+ and its reader, and the pure leaves they are built from. `@orkestrel/test/browser` is the
65
69
  journey layer, which drives a real browser through the installed Vitest provider. Core touches
66
70
  neither `node:*` nor the DOM, so a browser test project imports it unchanged.
71
+ `@orkestrel/test/reporter` is the runner entry Vitest's `--reporter` flag loads: its default
72
+ export is `ProgressReporter`, and it ships ES only.
67
73
 
68
74
  The browser face ships ES only. It is built on `vitest/browser`, which is an ES-only module, so no
69
75
  CommonJS consumer can reach it and no `.d.cts` is emitted for it.
@@ -1012,59 +1018,104 @@ collision refusal before writing.
1012
1018
  Imported from `@orkestrel/test/server`.
1013
1019
 
1014
1020
  The provider command consumes the browser journey's resolved selector inside Vitest's tester frame.
1021
+ The progress reporter is a Vitest reporter a run lists beside its others.
1015
1022
 
1016
- | Name | Kind | Signature | Summary |
1017
- | ------------- | -------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
1018
- | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1023
+ | Name | Kind | Signature | Summary |
1024
+ | ------------------ | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1025
+ | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1026
+ | `ProgressReporter` | class | `new () => Reporter` | Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live run's progress and each failure's first error can be read before the run ends. |
1019
1027
 
1020
1028
  #### Types
1021
1029
 
1022
- | Name | Kind | Signature | Summary |
1023
- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
1024
- | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
1025
- | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1026
- | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1027
- | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1028
- | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1029
- | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1030
- | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1031
- | `UpgradeResult` | type | `{ readonly claimed: true; readonly protocol: string \| undefined; } \| { readonly claimed: false; readonly status: number; }` | Represents what one server did with a client upgrade request. |
1032
- | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1030
+ | Name | Kind | Signature | Summary |
1031
+ | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1032
+ | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
1033
+ | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1034
+ | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1035
+ | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1036
+ | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1037
+ | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1038
+ | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1039
+ | `UpgradeResult` | type | `{ readonly claimed: true; readonly protocol: string \| undefined; } \| { readonly claimed: false; readonly status: number; }` | Represents what one server did with a client upgrade request. |
1040
+ | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1041
+ | `ProgressError` | interface | `{ message, location? }` | Represents one error a progress line carries: its first message line and where it was thrown. |
1042
+ | `ProgressSpecification` | interface | `{ project, module }` | Names one module a run starts, under the project that runs it, as one Vitest specification. |
1043
+ | `ProgressStamp` | interface | `{ time, pid }` | Represents the stamp every progress line carries. |
1044
+ | `ProgressInitEvent` | interface | `{ event, version, wall, bail }` | Represents the line a reporter writes when Vitest initializes it. |
1045
+ | `ProgressStartEvent` | interface | `{ event, specifications }` | Represents the line a reporter writes when a run starts, listing the modules it runs. |
1046
+ | `ProgressCollectedEvent` | interface | `{ event, project, module, planned, errors }` | Represents the line a reporter writes when Vitest collects one module's cases. |
1047
+ | `ProgressReadyEvent` | interface | `{ event, project, id, name }` | Represents the line a reporter writes when a planned case starts. |
1048
+ | `ProgressCaseState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending'` | Names the state a case result reports, mirroring Vitest's `TestState`. |
1049
+ | `ProgressCaseEvent` | interface | `{ event, project, module, id, name, state, duration?, start?, errors? }` | Represents the line a reporter writes once for each planned case's result. |
1050
+ | `ProgressCancelEvent` | interface | `{ event, reason, wall }` | Represents the line a reporter writes each time Vitest cancels the run. |
1051
+ | `ProgressModuleState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending' \| 'queued'` | Names the state a finished module reports, mirroring Vitest's `TestModuleState`. |
1052
+ | `ProgressModuleEvent` | interface | `{ event, project, module, state, duration }` | Represents the line a reporter writes when a module finishes. |
1053
+ | `ProgressEndReason` | type | `'passed' \| 'interrupted' \| 'failed'` | Names why a run ended, mirroring Vitest's `TestRunEndReason`. |
1054
+ | `ProgressEndEvent` | interface | `{ event, reason, overhead, unhandled }` | Represents the line a reporter writes when a run ends. |
1055
+ | `ProgressEvent` | type | `ProgressInitEvent \| ProgressStartEvent \| ProgressCollectedEvent \| ProgressReadyEvent \| ProgressCaseEvent \| ProgressCancelEvent \| ProgressModuleEvent \| ProgressEndEvent` | Represents one line of a progress file, discriminated by `event`. |
1056
+ | `ProgressState` | type | `'live' \| ProgressEndReason` | Names a run's state as a reader sees it: `live` until its `end` line, then the end reason. |
1057
+ | `ProgressRelation` | type | `'first' \| 'bail' \| 'later'` | Names how a failure relates to the run's bail: `first` is the earliest failure, `bail` is a failure past the bail setting whose result arrived or whose case ended after the first cancel, and `later` is any other failure. |
1058
+ | `ProgressProject` | interface | `{ name, planned, done, passed, failed, skipped, modules, collected }` | Represents one project's tallies in a progress reading. |
1059
+ | `ProgressCase` | interface | `{ project, name, duration }` | Represents a case that started and has not reported a result. |
1060
+ | `ProgressFailure` | interface | `{ project, module, name, time, relation, error }` | Represents one failed case, or one module that failed to collect, in a progress reading. |
1061
+ | `ProgressCancel` | interface | `{ reason, time }` | Represents the first cancel a run recorded. |
1062
+ | `ProgressRun` | interface | `{ pid, wall, state, bail, elapsed, done, planned, exact, rate, remaining, projects, running, cancel, failures, overhead, unhandled }` | Represents where one run stands, read from its progress lines. |
1033
1063
 
1034
1064
  #### Constants
1035
1065
 
1036
- | Name | Kind | Signature | Summary |
1037
- | ----------------------------- | ----- | ------------------- | ---------------------------------------------------------------------------------- |
1038
- | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1039
- | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1040
- | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1066
+ | Name | Kind | Signature | Summary |
1067
+ | ----------------------------- | ----- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
1068
+ | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1069
+ | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1070
+ | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1071
+ | `PROGRESS_VERSION` | const | `1` | Names the format version a progress file's `init` line carries; a reader refuses any other. |
1072
+ | `PROGRESS_MESSAGE_LIMIT` | const | `300` | Caps the characters a progress error message keeps. |
1073
+ | `PROGRESS_LABELS` | const | `Readonly<Record<ProgressRelation, string>>` | Names the label a rendered progress reading prints for each failure relation. |
1074
+
1075
+ #### Validators
1076
+
1077
+ | Name | Kind | Signature | Summary |
1078
+ | ----------------- | ----- | ---------------------- | ------------------------------------------------------------ |
1079
+ | `isProgressError` | const | `Guard<ProgressError>` | Checks whether a value is one error a progress line carries. |
1080
+ | `isProgressEvent` | const | `Guard<ProgressEvent>` | Checks whether a value is one line of a progress file. |
1041
1081
 
1042
1082
  #### Helpers
1043
1083
 
1044
- | Name | Kind | Signature | Summary |
1045
- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
1046
- | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1047
- | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1048
- | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1049
- | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1050
- | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1051
- | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1052
- | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1053
- | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1054
- | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1055
- | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1056
- | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1057
- | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1058
- | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1059
- | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process. |
1060
- | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1061
- | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1062
- | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1063
- | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1064
- | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1065
- | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1066
- | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1067
- | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1084
+ | Name | Kind | Signature | Summary |
1085
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
1086
+ | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1087
+ | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1088
+ | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1089
+ | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1090
+ | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1091
+ | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1092
+ | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1093
+ | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1094
+ | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1095
+ | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1096
+ | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1097
+ | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1098
+ | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1099
+ | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process. |
1100
+ | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1101
+ | `normalizeProgressPath` | function | `(file: string, root: string) => string` | Normalizes a module or stack-frame path to the form a progress line carries. |
1102
+ | `extractProgressError` | function | `(error: SerializedError, root: string) => ProgressError` | Extracts the message line and location a progress line keeps from one Vitest error. |
1103
+ | `matchesPlannedCase` | function | `(test: { readonly options: { readonly mode: string; }; }) => boolean` | Reports whether a collected case is one the run plans to report. |
1104
+ | `readFileSnapshot` | function | `(path: string) => Buffer` | Reads the bytes a file holds when it is opened, leaving out every byte appended during the read. |
1105
+ | `filterProgressEvents` | function | `<TName extends ProgressEvent['event']>(events: readonly ProgressEvent[], name: TName) => ReadonlyArray<Extract<ProgressEvent, { readonly event: TName; }>>` | Filters the progress lines of one event. |
1106
+ | `extractProgressEvents` | function | `(text: string) => readonly ProgressEvent[]` | Extracts the progress lines a text holds, skipping a partial last line. |
1107
+ | `computeProgressRun` | function | `(events: readonly ProgressEvent[], now: number) => ProgressRun \| undefined` | Computes where the run one process wrote stands, from its last `init` line on. |
1108
+ | `computeProgress` | function | `(events: readonly ProgressEvent[], now: number) => readonly ProgressRun[]` | Computes where every run a progress file holds stands, one run per writing process. |
1109
+ | `readProgress` | function | `(path: string, now?: number) => readonly ProgressRun[]` | Reads where every run a progress file holds stands, live or finished. |
1110
+ | `renderDuration` | function | `(milliseconds: number) => string` | Renders a duration as whole minutes and seconds. |
1111
+ | `renderProgress` | function | `(runs: readonly ProgressRun[]) => string` | Renders progress runs as the text a person reads mid-run. |
1112
+ | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1113
+ | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1114
+ | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1115
+ | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1116
+ | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1117
+ | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1118
+ | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1068
1119
 
1069
1120
  `hasScratchPath` takes a scratch's absolute path and a relative or absolute target. It checks
1070
1121
  containment before inspecting the root, returns `false` for a missing root or entry, and refuses a
@@ -2997,7 +3048,7 @@ Object.keys(
2997
3048
  readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
2998
3049
  )
2999
3050
  // ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
3000
- // 'src/core/types.ts', 'src/core/validators.ts']
3051
+ // 'src/core/types.ts', 'src/core/validators.ts', 'src/reporter/main.ts']
3001
3052
 
3002
3053
  // An exclusion also applies to a target you name, so naming one file below an excluded directory
3003
3054
  // does not reinstate it.
@@ -3204,6 +3255,67 @@ rejects with the client's own `ECONNREFUSED` rather than reporting a refusal, an
3204
3255
  accepts the connection and answers nothing rejects on the budget, which defaults to `1000`
3205
3256
  milliseconds and names the port and path it was waiting on.
3206
3257
 
3258
+ ### Read a long run while it runs
3259
+
3260
+ This configuration lists the progress reporter beside the dot reporter and names its file the way
3261
+ `--outputFile.json` names the JSON report's file.
3262
+
3263
+ ```ts
3264
+ import { defineConfig } from 'vitest/config'
3265
+ import { ProgressReporter } from '@orkestrel/test/server'
3266
+
3267
+ export default defineConfig({
3268
+ test: {
3269
+ reporters: ['dot', new ProgressReporter()],
3270
+ outputFile: { progress: 'tmp/runs/progress.jsonl' },
3271
+ },
3272
+ })
3273
+ ```
3274
+
3275
+ The reporter refuses to initialize when no `progress` file is named. It appends with one
3276
+ synchronous write per line, so a second process can read the file at any moment. It writes `ready`
3277
+ and `case` lines only for the cases each module plans to run, so a name filter's removed cases
3278
+ never count, and it writes one `case` line per planned case even where a bail makes Vitest report a
3279
+ case twice. It records every `cancel` Vitest delivers, registering its listener once a module
3280
+ queues, because Vitest clears cancel listeners after `onTestRunStart`.
3281
+
3282
+ This read summarizes the file once, from another process or the same one, and renders it.
3283
+
3284
+ ```ts
3285
+ import { readProgress, renderProgress } from '@orkestrel/test/server'
3286
+
3287
+ const runs = readProgress('tmp/runs/progress.jsonl')
3288
+ runs[0]?.state // 'live' until the run writes its end line
3289
+ runs[0]?.failures[0]?.relation // 'first'
3290
+ console.log(renderProgress(runs))
3291
+ ```
3292
+
3293
+ `readProgress` reads up to the file's length at open, decodes complete lines only, holds no timer,
3294
+ and writes nothing. It returns one run per writing process, each read from that process's last
3295
+ `init` line, and each run carries that line's `wall` time. The rendered text gives cases done
3296
+ against planned per project, with `+` on the total until every module is collected, the elapsed
3297
+ time, rate, and estimate, the running cases, the cancel, and each failure under its module and case
3298
+ with its first message line and location. A module that fails to collect, such as one that throws
3299
+ while it is imported, reads as a failure under its module alone, and as `FIRST` when its line comes
3300
+ before every other failure line. The earliest failure line reads `FIRST` even when Vitest wrote the
3301
+ cancel before its result. Only a failed case can trigger a bail, so under a bail the first failed
3302
+ case reads as a cause even after a collection failure. A later failure past the bail setting that
3303
+ arrived or ended after the cancel reads `AFTER-BAIL`, and any other reads `FAILED`. A project's
3304
+ `failed` tally counts its failed cases and its modules that failed to collect.
3305
+
3306
+ The format reads one `vitest run` per process. The reporter appends and never truncates, so delete
3307
+ the file before each run. A file that still holds earlier runs reads as one run per process, each
3308
+ from its last `init` line, and `wall` tells them apart. A run killed before its `end` line reads
3309
+ `live` until its file is deleted. Watch mode initializes the reporter once, so its reruns pile under
3310
+ one `init` line and are outside what the format reads.
3311
+
3312
+ Without a configuration, name the published entry and its file on the command line. Vitest
3313
+ constructs the entry's default export, `ProgressReporter`.
3314
+
3315
+ ```bash
3316
+ npx vitest run --reporter=@orkestrel/test/reporter --outputFile.progress=tmp/runs/progress.jsonl
3317
+ ```
3318
+
3207
3319
  ### Probe what the host supports
3208
3320
 
3209
3321
  Gate a proof on the mechanism it needs rather than on the platform name. Each probe allocates its own