@orkestrel/scaffold 0.0.113 → 0.0.115

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 (94) hide show
  1. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +83 -16
  2. package/dist/bin/main.js +71 -23
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/agents/orchestration.md +5 -3
  5. package/dist/host/agents/platforms/windows.md +1 -0
  6. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  7. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  8. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  9. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  10. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  13. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  14. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
  15. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +31 -11
  16. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +150 -49
  17. package/dist/host/claude/agents/analyst.md +1 -1
  18. package/dist/host/claude/agents/astra.md +2 -2
  19. package/dist/host/claude/agents/builder.md +4 -4
  20. package/dist/host/claude/agents/opus.md +3 -3
  21. package/dist/host/claude/agents/orkestrel.md +57 -59
  22. package/dist/host/claude/agents/planner.md +8 -2
  23. package/dist/host/claude/rules/campaign.md +2 -1
  24. package/dist/host/claude/rules/documentation.md +1 -0
  25. package/dist/host/claude/rules/tests.md +13 -8
  26. package/dist/host/claude/rules/workspace.md +28 -28
  27. package/dist/host/claude/rules/writing.md +1 -0
  28. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  31. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  32. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  35. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  36. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  37. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  38. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  39. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  40. package/dist/host/codex/agents/analyst.toml +8 -5
  41. package/dist/host/codex/agents/astra.toml +4 -5
  42. package/dist/host/codex/agents/builder.toml +5 -5
  43. package/dist/host/codex/agents/opus.toml +3 -4
  44. package/dist/host/codex/agents/orkestrel.toml +2 -1
  45. package/dist/host/codex/agents/planner.toml +8 -5
  46. package/dist/host/codex/agents/reviewer.toml +5 -4
  47. package/dist/host/guides/agent.md +13 -13
  48. package/dist/host/guides/brief.md +4 -0
  49. package/dist/host/guides/browser.md +162 -44
  50. package/dist/host/guides/budget.md +1 -1
  51. package/dist/host/guides/capture.md +4 -0
  52. package/dist/host/guides/console.md +13 -0
  53. package/dist/host/guides/contract.md +38 -3
  54. package/dist/host/guides/csv.md +5 -0
  55. package/dist/host/guides/database.md +58 -8
  56. package/dist/host/guides/form.md +17 -0
  57. package/dist/host/guides/guide.md +36 -33
  58. package/dist/host/guides/html.md +72 -44
  59. package/dist/host/guides/indexeddb.md +4 -0
  60. package/dist/host/guides/lsp.md +49 -8
  61. package/dist/host/guides/markdown.md +146 -1
  62. package/dist/host/guides/mcp.md +117 -22
  63. package/dist/host/guides/middleware.md +194 -26
  64. package/dist/host/guides/msg.md +9 -5
  65. package/dist/host/guides/pool.md +8 -1
  66. package/dist/host/guides/probe.md +13 -1
  67. package/dist/host/guides/process.md +102 -90
  68. package/dist/host/guides/program.md +4 -0
  69. package/dist/host/guides/qualifier.md +4 -0
  70. package/dist/host/guides/rater.md +4 -0
  71. package/dist/host/guides/reason.md +6 -4
  72. package/dist/host/guides/relation.md +4 -0
  73. package/dist/host/guides/scaffold.md +32 -14
  74. package/dist/host/guides/server.md +29 -13
  75. package/dist/host/guides/sqlite.md +6 -0
  76. package/dist/host/guides/sse.md +6 -0
  77. package/dist/host/guides/study.md +473 -473
  78. package/dist/host/guides/table.md +3 -0
  79. package/dist/host/guides/template.md +3 -0
  80. package/dist/host/guides/test.md +38 -20
  81. package/dist/host/guides/tool.md +3 -0
  82. package/dist/host/guides/toolbox.md +21 -0
  83. package/dist/host/guides/websocket.md +3 -1
  84. package/dist/host/guides/workflow.md +103 -11
  85. package/dist/host/guides/workspace.md +4 -0
  86. package/dist/host/manifest.json +84 -84
  87. package/dist/host/tests/config.test.ts +7 -13
  88. package/dist/src/core/index.cjs +20 -28
  89. package/dist/src/core/index.cjs.map +1 -1
  90. package/dist/src/core/index.d.cts +7 -7
  91. package/dist/src/core/index.d.ts +7 -7
  92. package/dist/src/core/index.js +20 -28
  93. package/dist/src/core/index.js.map +1 -1
  94. package/package.json +12 -12
@@ -112,15 +112,15 @@ A `Shape` cell holds the constant's declared type.
112
112
  | `MSG_PREFIX_RECIPIENT` | const | `string` | Holds the storage name prefix for a recipient entry (`'__recip_version1.0'`). |
113
113
  | `MSG_PREFIX_DOCUMENT` | const | `string` | Holds the stream name prefix for a MAPI property document (substg) entry (`'__substg1.'`). |
114
114
  | `MSG_PREFIX_NAMEID` | const | `string` | Holds the storage name of the named-property mapping table (`'__nameid_version1.0'`). |
115
- | `MSG_FIELD_NAME_MAPPING` | const | `Readonly<Record<string, string>>` | Maps a MAPI property tag's hex to its short field name, for example `subject`. |
116
- | `MSG_FIELD_FULL_NAME_MAPPING` | const | `Readonly<Record<string, string>>` | Maps a compound tag's full 8-character hex to its fully-qualified field name. |
117
- | `MSG_FIELD_TYPE_MAPPING` | const | `Readonly<Record<string, MSGFieldType>>` | Maps a MAPI property type tag's hex to its `MSGFieldType` decode tag. |
115
+ | `MSG_FIELD_NAMES` | const | `Readonly<Record<string, string>>` | Maps a MAPI property tag's hex to its short field name, for example `subject`. |
116
+ | `MSG_FIELD_FULL_NAMES` | const | `Readonly<Record<string, string>>` | Maps a compound tag's full 8-character hex to its fully-qualified field name. |
117
+ | `MSG_FIELD_TYPES` | const | `Readonly<Record<string, MSGFieldType>>` | Maps a MAPI property type tag's hex to its `MSGFieldType` decode tag. |
118
118
  | `MSG_FIELD_CLASS_ATTACHMENT_DATA` | const | `string` | Identifies the MAPI tag naming an attachment's binary data stream (`'3701'`). |
119
119
  | `MSG_FIELD_DIR_TYPE_INNER_MSG` | const | `string` | Names the MAPI type tag identifying an embedded `.msg` attachment storage (`'000d'`). |
120
120
  | `MSG_MAPI_RECIPIENT_TO` | const | `number` | Names the MAPI recipient-type value mapping to `MSGRecipientRole` `'to'` (`1`). |
121
121
  | `MSG_MAPI_RECIPIENT_CC` | const | `number` | Names the MAPI recipient-type value mapping to `MSGRecipientRole` `'cc'` (`2`). |
122
122
  | `MSG_MAPI_RECIPIENT_BCC` | const | `number` | Names the MAPI recipient-type value mapping to `MSGRecipientRole` `'bcc'` (`3`). |
123
- | `MSG_PIDLID_MAPPING` | const | `Readonly<Record<string, Readonly<Record<number, string>>>>` | Maps a named-property set GUID to its long-ID-to-field-name table. |
123
+ | `MSG_PIDLIDS` | const | `Readonly<Record<string, Readonly<Record<number, string>>>>` | Maps a named-property set GUID to its long-ID-to-field-name table. |
124
124
  | `MSG_BURNER_INTS_PER_SECTOR` | const | `number` | Holds the number of 32-bit FAT and DIFAT entries one standard sector carries (128). |
125
125
  | `MSG_BURNER_DIFAT_HEADER_SLOTS` | const | `number` | Caps the DIFAT entries stored directly in the CFB header (109). |
126
126
  | `MSG_BURNER_FAT_SECTOR_MARKER` | const | `number` | Marks a sector as itself part of the FAT (-3). |
@@ -157,6 +157,10 @@ try {
157
157
  }
158
158
  ```
159
159
 
160
+ The constructor adds an own, non-enumerable, non-writable symbol brand whose value is the error itself.
161
+ The guard accepts errors from another installed copy and subclasses without requiring a particular name.
162
+ It refuses transparent proxies, unbranded errors, and plain objects carrying the brand.
163
+
160
164
  ### Helpers
161
165
 
162
166
  Pure, mostly-total leaves from [`helpers.ts`](../src/core/helpers.ts) — the `Result` constructors/guards, the CFB byte/string/UUID readers and magic check `MSG.ts` composes, the format sniffer, and the MIME/text codecs `parsers.ts` and `shapers.ts` compose.
@@ -299,7 +303,7 @@ parseMIMEPart('Subject: Hi\n\nBody text') // MIMEPart — { headers, body: 'Body
299
303
 
300
304
  ### Validators
301
305
 
302
- The from-unknown guards from [`validators.ts`](../src/core/validators.ts). Each validates an arbitrary `unknown` value from scratch, against the `EmailChain`, `EmailMessage`, or `EmailAttachment` shape, or the `EmailFormat` union, using `isRecord` from `@orkestrel/contract`. `isMSGError` differs: it narrows a value that is already typed.
306
+ The from-unknown guards from [`validators.ts`](../src/core/validators.ts). Each validates an arbitrary `unknown` value from scratch, against the `EmailChain`, `EmailMessage`, or `EmailAttachment` shape, or the `EmailFormat` union, using `isRecord` from `@orkestrel/contract`. `isMSGError` validates the global Error instance, its package brand, its code, and its context.
303
307
 
304
308
  In a guard table a `Shape` cell holds the type the guard narrows to.
305
309
 
@@ -56,7 +56,7 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
56
56
 
57
57
  | API | Kind | Shape | Summary |
58
58
  | -------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
59
- | `isPoolError` | function | `PoolError` | Tests whether an unknown value is a `PoolError`, returning `false` for hostile proxies. |
59
+ | `isPoolError` | function | `PoolError` | Tests whether an unknown value is a branded `PoolError` with declared code and context. |
60
60
  | `isPoolLimit` | function | `number` | Tests whether a value is a positive safe integer for a pool record or lease limit. |
61
61
  | `isPoolSignal` | function | `AbortSignal` | Tests whether a value is a native `AbortSignal` for the acquire boundary, returning `false` for hostile proxies. |
62
62
 
@@ -306,6 +306,13 @@ The original thrown value is retained as `cause`; aggregate cleanup values are a
306
306
  `context.failures`. Message construction and `isPoolError` avoid unsafe string coercion and
307
307
  return safely for hostile proxies.
308
308
 
309
+ Recognition requires an own identity brand at `Symbol.for('@orkestrel/pool.PoolError')`,
310
+ the global `Error` base with a subclass prototype, a declared code, and valid optional context.
311
+ The brand is non-enumerable and non-writable. Guards from separate installed copies and module
312
+ formats recognize each other's errors. Subclasses pass without reading `name`; transparent
313
+ proxies, unbranded look-alikes, and plain objects carrying only the brand fail. Errors created
314
+ by older releases without this brand no longer pass the guard.
315
+
309
316
  ## Observing
310
317
 
311
318
  The composed `Emitter` isolates listener throws through the optional `error` handler and
@@ -253,7 +253,7 @@ Pure leaves and workspace readers, from [`helpers.ts`](../src/server/helpers.ts)
253
253
  | `inferDocumentLanguage` | function | `(path: string) => string` | Selects the Language Server Protocol language identifier for a source path. |
254
254
  | `buildRevisionPath` | function | `(workspace: string, path: string, revision: string) => string` | Builds the fresh sibling path a revision's file is written at, preserving the test's resolution directory. |
255
255
  | `matchesWorkspaceModule` | function | `(path: string) => boolean` | Reports whether a path is a workspace module Vitest can cache. |
256
- | `matchesLiveProcess` | function | `(id: number) => boolean` | Reports whether the host that wrote one file is still running. |
256
+ | `matchesLiveProcess` | function | `(id: number) => boolean` | Reports whether a file's owning host is running or cannot be judged. |
257
257
  | `collectWorkspaceFiles` | function | `(workspace: string) => readonly string[]` | Collects every regular file a target workspace holds, skipping the trees no inspection reads. |
258
258
  | `filterUniqueIssues` | function | `(issues: readonly Issue[]) => readonly Issue[]` | Filters one issue list to the distinct issues it carries, in the order they arrived. |
259
259
  | `describeUnknown` | function | `(value: unknown) => string` | Normalizes a caught or foreign error into readable text. |
@@ -306,6 +306,11 @@ The stage implements the preceding `StageInterface` contract.
306
306
 
307
307
  #### `TypeStageInterface`
308
308
 
309
+ `destroy()` abandons inspections and awaits Windows compiler tree termination before removing the
310
+ mirror. Each termination utility has the existing `PROBE_DEADLINE` budget of 30,000 ms; the attempts
311
+ run concurrently. POSIX teardown retains `SIGTERM`. Warming settles before mirror removal on either
312
+ host. The termination attempt remains best effort if the host utility fails.
313
+
309
314
  | Method | Returns | Summary |
310
315
  | --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
311
316
  | `start` | `Promise<void>` | Begins the warm or joins the warm already begun. |
@@ -504,6 +509,9 @@ Measured on 2026-08-20: `computeDigest(workspace, cyclic)` raises
504
509
  `isProbeError` reads a global brand rather than the constructor, so it admits a failure raised by a
505
510
  second copy of this package — a duplicate installation, or the ESM and CommonJS builds loaded
506
511
  together — where `instanceof` refuses a failure the other copy raised.
512
+ The own brand holds the error itself. Recognition requires an `Error` with a non-base prototype,
513
+ a declared origin and code, and context members of their declared types. A subclass may replace
514
+ `name`. A transparent proxy, a plain branded object, and a lookalike without the brand are refused.
507
515
 
508
516
  ## Prerequisites
509
517
 
@@ -952,6 +960,10 @@ the stage, and the mirror is this stage's own tree: where the workspace holds a
952
960
  draft declares a directory under, the mirrored copy of that file is removed so the draft can be
953
961
  written, and the next refresh restores it.
954
962
 
963
+ The stale-resource sweep retains an owner whose liveness cannot be judged. `matchesLiveProcess`
964
+ keeps its invalid-identity guard and uses process 0.0.16's `inspectProcess` for the host probe. An
965
+ indeterminate answer preserves the resource; only confirmed absence permits the sweep to remove it.
966
+
955
967
  **A read is contained lexically only, and that is the reach to plan for.** The mirror carries
956
968
  regular files inside the workspace only: a symbolic link is not carried, so a file reached only
957
969
  through one is absent from the mirror and the compiler reports what its absence causes, as a
@@ -9,7 +9,7 @@
9
9
  `evidence` beside a live `stderr` event, publishes a typed lifecycle emitter, and ends every
10
10
  observation channel at one terminal moment through a bounded termination. `Session` publishes one
11
11
  owned `Uint8Array` per stdout chunk instead, with an `end` that closes stdin without terminating
12
- anything and the child's own `ending` beside the terminal `exit`. A buffered run settles with an
12
+ anything and the child's own `ended` beside the terminal `exit`. A buffered run settles with an
13
13
  `ExecuteResult` carrying the captured output and the exit, while a detached child owns no stdio and
14
14
  is unreferenced, so nothing in this process observes its outcome. `ProcessManager` launches and
15
15
  stops its children by id and reports each moment through its own emitter. An argument a batch
@@ -141,14 +141,22 @@ The byte-bounding and result-assembly building blocks, from `@orkestrel/process/
141
141
  The signalling and confirmation building blocks a bounded stop composes, from
142
142
  `@orkestrel/process/server`.
143
143
 
144
- | API | Kind | Summary |
145
- | -------------- | -------- | ----------------------------------------------------------------------------------- |
146
- | `isExited` | function | Checks whether a child process has reached its native exit. |
147
- | `killProcess` | function | Signals one owned child process, or its detached process group on a POSIX host. |
148
- | `killTree` | function | Kills one Windows process tree through `taskkill`. |
149
- | `waitForExit` | function | Waits for one child process's native exit, bounded by a deadline. |
150
- | `waitForClose` | function | Waits for one child process's streams to close, bounded by a deadline. |
151
- | `stopChild` | function | Terminates one child process tree and reports whether its native exit was observed. |
144
+ | API | Kind | Summary |
145
+ | ---------------- | -------- | ----------------------------------------------------------------------------------- |
146
+ | `inspectProcess` | function | Reports whether a process or POSIX process group still exists. |
147
+ | `isExited` | function | Checks whether a child process has reached its native exit. |
148
+ | `killProcess` | function | Signals one owned child process, or its detached process group on a POSIX host. |
149
+ | `killTree` | function | Kills one Windows process tree through `taskkill`. |
150
+ | `waitForExit` | function | Waits for one child process's native exit, bounded by a deadline. |
151
+ | `waitForClose` | function | Waits for one child process's streams to close, bounded by a deadline. |
152
+ | `stopChild` | function | Terminates one child process tree and reports whether its native exit was observed. |
153
+
154
+ `inspectProcess` returns `true` while the process or POSIX process group exists, including
155
+ when the host refuses the probe with `EPERM`. It returns `false` after the target is gone
156
+ (`ESRCH`), and `undefined` for any other host failure. It throws a `ProcessError` coded
157
+ `invalid` for a value that is not a safe integer, zero, or minus one. Windows accepts only
158
+ positive process ids and refuses every negative id before the host call. On POSIX, a negative
159
+ id other than minus one probes the process group identified by its magnitude.
152
160
 
153
161
  ### Validators
154
162
 
@@ -188,29 +196,29 @@ The contracts and options, all from `@orkestrel/process`.
188
196
 
189
197
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
190
198
 
191
- | API | Kind | Shape | Summary |
192
- | ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
193
- | `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }` | Represents one spawnable command: the executable, its argument vector, and optional environment overrides and initial standard input. |
194
- | `ProcessExit` | interface | `{ code, signal, drained }` | Represents the observed terminal state of a child process: its exit code or the signal that ended it, and how its observation ended. |
195
- | `SpawnInput` | interface | `{ file, arguments, verbatim }` | Represents the resolved spawn form of one command: the executable to launch, the argument vector to pass, and whether the host receives that vector verbatim. |
196
- | `ExecutableOptions` | interface | `{ workspace?, environment? }` | Supplies the lookup inputs for resolving a command file to an executable path. |
197
- | `ProcessEventMap` | type | `{ stderr, error, exit }` | Represents the push observation surface of a `ProcessInterface` — the moments a fire-and-forget observer subscribes to, alongside the `lines` stream and the `exit` promise. |
198
- | `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }` | Configures one supervised child process. |
199
- | `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, stopping, exit } plus send, stop, destroy` | Represents one supervised child process with framed output, a bounded backlog, and bounded termination. |
200
- | `SessionEventMap` | type | `{ stdout, stderr, error, exit }` | Represents the push observation surface of a `SessionInterface` — the moments a byte-oriented observer subscribes to, alongside the `ending` and `exit` promises. |
201
- | `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }` | Configures one raw byte session over a supervised child. |
202
- | `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, stopping, ending, exit } plus write, end, stop, destroy` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
203
- | `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }` | Represents the settled outcome of a one-shot run: the buffered output and the terminal state. |
204
- | `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }` | Represents the captured bytes and terminal facts one settled `ExecuteResult` is built from. |
205
- | `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }` | Configures a one-shot run. |
206
- | `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }` | Configures a synchronous one-shot run. |
207
- | `DetachOptions` | interface | `{ workspace? }` | Configures a detached fire-and-forget spawn. |
208
- | `ProcessManagerEventMap` | type | `{ launch, exit }` | Represents the push observation surface of a `ProcessManagerInterface` — the fleet-level moments a fire-and-forget observer subscribes to. |
209
- | `ProcessManagerOptions` | interface | `{ on?, error? }` | Configures a `ProcessManagerInterface`. |
210
- | `ProcessManagerInterface` | interface | `{ emitter, count } plus process, processes, launch, stop, destroy` | Represents a keyed registry of live supervised child processes. |
211
- | `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]` | Names the machine-readable `ProcessError` categories, derived from `PROCESS_ERROR_CODES`: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
212
- | `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }` | Represents structured context carried by a `ProcessError`. |
213
- | `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }` | Configures a `ProcessError`. |
199
+ | API | Kind | Shape | Summary |
200
+ | ------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
201
+ | `ProcessCommand` | interface | `{ file, arguments, environment?, input?, isolated? }` | Represents one spawnable command: the executable, its argument vector, and optional environment overrides and initial standard input. |
202
+ | `ProcessExit` | interface | `{ code, signal, drained }` | Represents the observed terminal state of a child process: its exit code or the signal that ended it, and how its observation ended. |
203
+ | `SpawnInput` | interface | `{ file, arguments, verbatim }` | Represents the resolved spawn form of one command: the executable to launch, the argument vector to pass, and whether the host receives that vector verbatim. |
204
+ | `ExecutableOptions` | interface | `{ workspace?, environment? }` | Supplies the lookup inputs for resolving a command file to an executable path. |
205
+ | `ProcessEventMap` | type | `{ stderr, error, exit }` | Represents the push observation surface of a `ProcessInterface` — the moments a fire-and-forget observer subscribes to, alongside the `lines` stream and the `exit` promise. |
206
+ | `ProcessOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, backlog?, delivery?, writable?, signal? }` | Configures one supervised child process. |
207
+ | `ProcessInterface` | interface | `{ pid, code, signal, emitter, lines, evidence, truncated, settled, terminated, exit } plus send, stop, destroy` | Represents one supervised child process with framed output, a bounded backlog, and bounded termination. |
208
+ | `SessionEventMap` | type | `{ stdout, stderr, error, exit }` | Represents the push observation surface of a `SessionInterface` — the moments a byte-oriented observer subscribes to, alongside the `ended` and `exit` promises. |
209
+ | `SessionOptions` | interface | `{ on?, error?, command, workspace, grace?, drain?, evidence?, delivery?, signal? }` | Configures one raw byte session over a supervised child. |
210
+ | `SessionInterface` | interface | `{ pid, code, signal, emitter, evidence, settled, terminated, ended, exit } plus write, end, stop, destroy` | Represents one supervised child process read as raw bytes, with an open standard-input channel and bounded termination. |
211
+ | `ExecuteResult` | interface | `{ command, stdout, stderr, code, signal, failed, expired, aborted, truncated }` | Represents the settled outcome of a one-shot run: the buffered output and the terminal state. |
212
+ | `ExecuteInput` | interface | `{ command, stdout, stderr, code, signal, expired, aborted, truncated, limit, cause? }` | Represents the captured bytes and terminal facts one settled `ExecuteResult` is built from. |
213
+ | `ExecuteOptions` | interface | `{ workspace?, environment?, input?, timeout?, grace?, signal?, strict?, limit? }` | Configures a one-shot run. |
214
+ | `ExecuteSyncOptions` | interface | `{ workspace?, environment?, input?, timeout?, strict?, limit? }` | Configures a synchronous one-shot run. |
215
+ | `DetachOptions` | interface | `{ workspace? }` | Configures a detached fire-and-forget spawn. |
216
+ | `ProcessManagerEventMap` | type | `{ launch, exit }` | Represents the push observation surface of a `ProcessManagerInterface` — the fleet-level moments a fire-and-forget observer subscribes to. |
217
+ | `ProcessManagerOptions` | interface | `{ on?, error? }` | Configures a `ProcessManagerInterface`. |
218
+ | `ProcessManagerInterface` | interface | `{ emitter, count } plus process, processes, launch, stop, destroy` | Represents a keyed registry of live supervised child processes. |
219
+ | `ProcessErrorCode` | type | `(typeof PROCESS_ERROR_CODES)[number]` | Names the machine-readable `ProcessError` categories, derived from `PROCESS_ERROR_CODES`: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
220
+ | `ProcessErrorContext` | interface | `{ id?, command?, code?, signal?, value? }` | Represents structured context carried by a `ProcessError`. |
221
+ | `ProcessErrorOptions` | interface | `{ code, context?, cause?, result? }` | Configures a `ProcessError`. |
214
222
 
215
223
  ### Server contracts
216
224
 
@@ -230,16 +238,16 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
230
238
  ### Surface notes
231
239
 
232
240
  Every member a `Shape` cell names before `plus` is a readonly data property, so it stays a Surface
233
- row. `ending` and `exit` are among them: a promise you await is a value the entity holds, not a call
241
+ row. `ended` and `exit` are among them: a promise you await is a value the entity holds, not a call
234
242
  you make. A `SupervisorFace` member is among them too: it holds a function the caller supplies
235
243
  rather than declaring one the contract implements. The call-signature members after `plus` are
236
244
  documented under [Methods](#methods).
237
245
 
238
246
  The `Supervisor` class publishes readonly data members of its own: `stdout`, `pid`, `code`, `signal`,
239
- `evidence`, `settled`, `stopping`, `ending`, and `exit`. It declares no interface, so they are named
247
+ `evidence`, `settled`, `terminated`, `ended`, and `exit`. It declares no interface, so they are named
240
248
  here rather than in a Surface row. `stdout` holds the child's standard-output stream, and it is the
241
249
  stream a composing face attaches its own consumer to, because the engine frames no output and owns
242
- no observation surface. `pid`, `code`, and `signal` read the host child directly and `ending` settles
250
+ no observation surface. `pid`, `code`, and `signal` read the host child directly and `ended` settles
243
251
  with it, while `evidence`, `settled`, and `exit` reach
244
252
  [the terminal moment](#the-terminal-moment) after the read channels close or the `drain` window cuts
245
253
  them off.
@@ -337,19 +345,19 @@ fault, and the terminal `exit`, alongside the `exit` promise.
337
345
 
338
346
  `ProcessOptions` requires `command` and `workspace`; the rest are optional:
339
347
 
340
- | Option | Type | Required | Meaning |
341
- | ----------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
342
- | `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
343
- | `workspace` | `string` | yes | The working directory the child runs in. |
344
- | `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
345
- | `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its ending, before cutting them off; `0` cuts them off immediately. Default: `PROCESS_DRAIN` (`1_000`). |
346
- | `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
347
- | `backlog` | `number` | no | Soft high-water mark in bytes; termination retains at most twice `backlog`. Default: `PROCESS_BACKLOG`. |
348
- | `delivery` | `number` | no | Milliseconds an unconfirmed `send` waits before resolving `false`; `0` or omitted disables the bound. |
349
- | `writable` | `boolean` | no | When `true`, stdin stays open for `send`; when `false` or omitted, stdin closes after any initial `input`. |
350
- | `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
351
- | `on` | `EmitterHooks<ProcessEventMap>` | no | Initial `stderr`, `error`, and `exit` listeners installed at construction. |
352
- | `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
348
+ | Option | Type | Required | Meaning |
349
+ | ----------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
350
+ | `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
351
+ | `workspace` | `string` | yes | The working directory the child runs in. |
352
+ | `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
353
+ | `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its ended, before cutting them off; `0` cuts them off immediately. Default: `PROCESS_DRAIN` (`1_000`). |
354
+ | `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
355
+ | `backlog` | `number` | no | Soft high-water mark in bytes; termination retains at most twice `backlog`. Default: `PROCESS_BACKLOG`. |
356
+ | `delivery` | `number` | no | Milliseconds an unconfirmed `send` waits before resolving `false`; `0` or omitted disables the bound. |
357
+ | `writable` | `boolean` | no | When `true`, stdin stays open for `send`; when `false` or omitted, stdin closes after any initial `input`. |
358
+ | `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
359
+ | `on` | `EmitterHooks<ProcessEventMap>` | no | Initial `stderr`, `error`, and `exit` listeners installed at construction. |
360
+ | `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
353
361
 
354
362
  There is no completion deadline for a running child. Nothing here ends a child that is still
355
363
  working, the `exit` promise carries no deadline of its own, and a caller that wants one arms its own
@@ -389,24 +397,24 @@ it, so no switch selects whether one exists.
389
397
 
390
398
  `SessionOptions` requires `command` and `workspace`; the rest are optional:
391
399
 
392
- | Option | Type | Required | Meaning |
393
- | ----------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
394
- | `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
395
- | `workspace` | `string` | yes | The working directory the child runs in. |
396
- | `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
397
- | `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its ending, before cutting them off; `0` cuts them off immediately. Default: `PROCESS_DRAIN` (`1_000`). |
398
- | `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
399
- | `delivery` | `number` | no | Milliseconds an unconfirmed `write` waits before resolving `false`; `0` or omitted disables the bound. |
400
- | `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
401
- | `on` | `EmitterHooks<SessionEventMap>` | no | Initial `stdout`, `stderr`, `error`, and `exit` listeners installed at construction. |
402
- | `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
400
+ | Option | Type | Required | Meaning |
401
+ | ----------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
402
+ | `command` | `ProcessCommand` | yes | The executable, its argument vector, and optional environment overrides and stdin `input`. |
403
+ | `workspace` | `string` | yes | The working directory the child runs in. |
404
+ | `grace` | `number` | no | POSIX milliseconds between `SIGTERM` and `SIGKILL`. Default: `PROCESS_GRACE` (`5_000`). |
405
+ | `drain` | `number` | no | Milliseconds the package waits for the child's read ends to close after its ended, before cutting them off; `0` cuts them off immediately. Default: `PROCESS_DRAIN` (`1_000`). |
406
+ | `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
407
+ | `delivery` | `number` | no | Milliseconds an unconfirmed `write` waits before resolving `false`; `0` or omitted disables the bound. |
408
+ | `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`. |
409
+ | `on` | `EmitterHooks<SessionEventMap>` | no | Initial `stdout`, `stderr`, `error`, and `exit` listeners installed at construction. |
410
+ | `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
403
411
 
404
412
  A session names the child's ending and the supervision's ending apart, because a transport acts on
405
- each differently. `ending` settles at the child's own native exit and resolves no value: `code` and
413
+ each differently. `ended` settles at the child's own native exit and resolves no value: `code` and
406
414
  `signal` already carry the terminal facts, so a second copy of them here could only drift from them.
407
415
  `exit` settles at [the terminal moment](#the-terminal-moment), which is that native exit plus at most
408
416
  `drain` while a descendant holds the inherited read ends. Race a cooperative shutdown window against
409
- `ending`; a window raced against `exit` escalates against a child that already ended.
417
+ `ended`; a window raced against `exit` escalates against a child that already ended.
410
418
 
411
419
  `end` closes the stdin channel and leaves the child running. That is the cooperative shutdown a
412
420
  protocol client runs: end the input, let the child finish its own work, and terminate only when it
@@ -426,12 +434,12 @@ session.emitter.on('stdout', (chunk) => received.push(chunk))
426
434
 
427
435
  await session.write(new TextEncoder().encode('ping')) // true — the host accepted the bytes
428
436
  await session.end() // the child sees end of input; nothing terminated it
429
- await session.ending // it exited on its own
437
+ await session.ended // it exited on its own
430
438
 
431
439
  Buffer.concat(received).toString('utf8') // 'ping' — the exact bytes, with no terminator added
432
440
  const exit = await session.exit
433
441
  exit.code // 0
434
- session.stopping // false — no termination was initiated
442
+ session.terminated // false — no termination was initiated
435
443
  await session.destroy()
436
444
  ```
437
445
 
@@ -445,7 +453,7 @@ surface is shaped around.
445
453
  - **The supervision's ending** is the terminal moment: `settled`, `exit`, `evidence`, and `lines`.
446
454
  They reach it together.
447
455
 
448
- `Session` gives the child's ending a member of its own, `ending`, which settles at the native exit
456
+ `Session` gives the child's exit a member of its own, `ended`, which settles at the native exit
449
457
  and resolves no value. `Process` carries no such member: a line consumer reads that ending from
450
458
  `code` and `signal`, which have always reported it.
451
459
 
@@ -478,16 +486,16 @@ A `Session` reaches the same moment through the same paths, with its byte events
478
486
  the last `stdout` and `stderr` events are delivered before the `exit` event, and none follows it.
479
487
 
480
488
  `end` is the one member on either face that does not reach the moment. It closes a session's stdin
481
- channel and leaves the child running, so `stopping` stays false, no drain window is armed, and `exit`
489
+ channel and leaves the child running, so `terminated` stays false, no drain window is armed, and `exit`
482
490
  stays pending until the child ends itself or something terminates it. Every other verb here ends the
483
491
  observation; `end` ends only the input.
484
492
 
485
493
  `stop` reaches the terminal moment as well as `destroy` does. A caller that terminates a child and
486
494
  keeps reading it therefore reaches the end of the stream instead of waiting on a child it already
487
- ended, and needs no second call to release it. `stopping` reports the initiation rather than the
495
+ ended, and needs no second call to release it. `terminated` reports the initiation rather than the
488
496
  arrival: it turns `true` when `stop`, `destroy`, or an abort of `signal` begins a termination, and it stays
489
497
  `true` from then on, including after `settled` turns `true`. A child that exited on its own reports
490
- `stopping` as `false` with `settled` as `true`.
498
+ `terminated` as `false` with `settled` as `true`.
491
499
 
492
500
  A consumer handed the terminal value never reads a child that still reports itself unfinished. The
493
501
  latch runs before the `exit` event and before the read ends are released, so a listener on that
@@ -509,7 +517,7 @@ const child = createProcess({
509
517
  const exit = await child.exit
510
518
  exit.drained // true — the child's own streams closed
511
519
  child.settled // true — evidence is frozen and lines has ended
512
- child.stopping // false — this child ended on its own
520
+ child.terminated // false — this child ended on its own
513
521
  child.evidence // 'done\n' — the frozen tail every later read returns
514
522
  await child.destroy()
515
523
  ```
@@ -661,7 +669,7 @@ after the frozen state exists, so a consumer watching the `stderr` event and a c
661
669
  `evidence` end on the same bytes.
662
670
 
663
671
  `Session` terminates through the same verbs with the same bounds and the same barriers. Run its
664
- cooperative shutdown first where the child supports one: call `end`, race `ending` against a window
672
+ cooperative shutdown first where the child supports one: call `end`, race `ended` against a window
665
673
  of your own, and call `stop` when that window expires.
666
674
 
667
675
  POSIX detachment creates the process group that tree termination signals. The child therefore
@@ -1150,10 +1158,11 @@ value with `isProcessError`, then branch on `code`.
1150
1158
 
1151
1159
  `isProcessError` recognizes an error thrown by another installed copy of the package. It reads a
1152
1160
  global own-property brand rather than `instanceof`, so a duplicate installation and an ESM/CommonJS
1153
- module copy both narrow, where a prototype check would refuse both. Recognition holds across copies
1154
- at 0.0.4 or later: a copy earlier than 0.0.4 stamps no brand, so an error it throws stays outside the
1155
- type. The guard admits exactly the codes `PROCESS_ERROR_CODES` declares, so a code added there is
1156
- admitted with no further edit.
1161
+ module copy both narrow. Recognition holds across copies that stamp their own identity under
1162
+ `Symbol.for('@orkestrel/process.error')` as a non-enumerable, non-writable own property. The guard
1163
+ requires the native `Error` base, a prototype other than `Error.prototype`, a declared code, and
1164
+ correctly shaped optional context and result members. It never reads `name`, so subclass instances
1165
+ pass. Older boolean brands, transparent proxies, and branded plain objects fail recognition.
1157
1166
 
1158
1167
  A run failure carries its `ExecuteResult` on `error.result`, and its command line, exit `code`, and
1159
1168
  `signal` on `error.context`. A duplicate-id and a protocol failure carry the offending `id` on
@@ -1305,7 +1314,7 @@ const session = createSession({
1305
1314
  // …on shutdown: end the input, give the child a window of your own, then terminate if it overruns.
1306
1315
  const window = new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 2_000))
1307
1316
  const flushed = await Promise.race([session.end().then(() => true), window])
1308
- const finished = flushed ? await Promise.race([session.ending.then(() => true), window]) : false
1317
+ const finished = flushed ? await Promise.race([session.ended.then(() => true), window]) : false
1309
1318
  if (!finished) await session.stop()
1310
1319
  await session.destroy()
1311
1320
  ```
@@ -1423,9 +1432,9 @@ isExited(reporter) // whether the native exit arrived
1423
1432
  - **Reach for `Session` when the child speaks a protocol** — `lines` frames text, and a
1424
1433
  length-prefixed header, a binary payload, or a NUL byte survives no line framer. A session hands
1425
1434
  you the exact bytes and lets you frame them.
1426
- - **Close a session with `end`, then race `ending`, then `stop`** — `end` closes the input and
1427
- terminates nothing, `ending` reports the child's own exit, and `stop` is the escalation for a child
1428
- that overruns the window you gave it. Race `ending` rather than `exit`: `exit` waits out `drain`
1435
+ - **Close a session with `end`, then race `ended`, then `stop`** — `end` closes the input and
1436
+ terminates nothing, `ended` reports the child's own exit, and `stop` is the escalation for a child
1437
+ that overruns the window you gave it. Race `ended` rather than `exit`: `exit` waits out `drain`
1429
1438
  for a descendant holding the pipe, so a window raced against it escalates against a child that
1430
1439
  already ended.
1431
1440
  - **Give `execute` a `timeout` when the command can start a descendant** — an unbounded run waits on
@@ -1461,13 +1470,13 @@ Each name on this surface that reads against a house rule is settled here rather
1461
1470
  | `truncated` | One name on both surfaces, because it reports one fact: the surface omitted output. Each entity names its own bound — a `Process` omits `lines` past a retention bound, and an `ExecuteResult` omits captured text past `limit`. |
1462
1471
  | `run` | Kept as the English noun for one invocation — a terminated run, a run that stays pending. It never names a function; `execute` and `executeSync` are named by their identifiers, so the concept carries one term. |
1463
1472
  | `settled` | Derives literally: it is `true` exactly when `exit` has settled. `closed` was refused because it borrows a Node event name into `ProcessInterface`, which is host-independent enough to type `signal` as a `string`. |
1464
- | `stopping` | A present participle for a latched fact, documented as monotonic rather than renamed. It reports that a termination was initiated, not that one is in flight, because the initiation is what a consumer acts on: a child that was asked to end is not a child to send new work to. |
1473
+ | `terminated` | A latched fact that records an initiated termination. It reports that a termination was initiated, not that one is in flight, because the initiation is what a consumer acts on: a child that was asked to end is not a child to send new work to. |
1465
1474
  | `drain`, `drained` | The option names the window and the result names its outcome, so one concept carries one term across the option and the result. `drain: 0` is an immediate cutoff rather than a disabled bound, unlike the sibling `delivery`, because an unbounded drain is the defect the option prevents. |
1466
1475
  | `Session` | A second entity rather than a byte mode on `Process`, because a mode would falsify `lines`, `truncated`, and `backlog` on half the instances of one class. `Child` collides with the published `ProcessChildInterface` contract, `Channel` is this package's word for the stdin pipe, and `Stream` and `Duplex` borrow Node class names into contracts typed to stay host-independent. |
1467
1476
  | `Supervisor` | The spawn, capture, channel, and termination engine `Process` and `Session` compose. It is barrelled because its constructor takes a `ProcessOptions` and a `SupervisorFace`, and a consumer holds both, so a consumer composing a face of its own reaches the same engine `Process` and `Session` do. |
1468
1477
  | `SupervisorFace` | The callback record a face hands the engine at construction, not a face and not the `Supervisor`'s own face. It carries `Face` rather than the `{Entity}Hooks` form `EmitterHooks` uses, because hooks are optional listeners on an entity that runs without them, while every callback here is a moment the engine must deliver. `{Entity}Interface` was refused because the type declares no behavior of its own: each member holds a function the composing face supplies. It is published because `types.ts` declares it and the server barrel star-exports that module. |
1469
- | `ending`, `exit` | The endings are named apart, because a transport acts on each differently. `ending` is the child's own exit and resolves no value, because `code` and `signal` already carry the facts and a second copy could only drift. `exit` stays on the terminal moment, so `exit`, `settled`, and the `exit` event name one moment on both faces. |
1470
- | `end` | The consistency class of `destroy`: an idempotent lifecycle member returning the barrier every call shares. `close` was refused for borrowing a Node event name, the reason `settled` already records. It resolves `void` because every fact a result could carry is derivable — a later `write` reports `false`, and `ending` reports the exit. |
1478
+ | `ended`, `exit` | The endings are named apart, because a transport acts on each differently. `ended` is the child's own exit and resolves no value, because `code` and `signal` already carry the facts and a second copy could only drift. `exit` stays on the terminal moment, so `exit`, `settled`, and the `exit` event name one moment on both faces. |
1479
+ | `end` | The consistency class of `destroy`: an idempotent lifecycle member returning the barrier every call shares. `close` was refused for borrowing a Node event name, the reason `settled` already records. It resolves `void` because every fact a result could carry is derivable — a later `write` reports `false`, and `ended` reports the exit. |
1471
1480
  | `write`, `send` | Different verbs because they promise different things. `send` frames a line and appends the terminator; `write` puts the exact bytes on the channel and appends nothing. One name over both would hide the terminator at the call site, which is the defect the split prevents. |
1472
1481
  | `stdout`, `stderr` | One face decodes one stream and not the other, because they are read differently. Standard output is a payload a parser consumes, so it stays bytes; standard error is a diagnostic a person reads, so it is decoded, and `evidence` bounds those same bytes. |
1473
1482
  | `backlog`, `writable` | Omitted from `SessionOptions` rather than falsified on it. A session retains no lines, so no backlog bound applies; its channel is open until `end` closes it, so no switch selects whether one exists. An option that could only ever hold one value is a member a consumer must learn and can never use. |
@@ -1541,7 +1550,7 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
1541
1550
  event and the tail stopping together, `lines` ending an in-flight read after its queued lines, the
1542
1551
  `exit` promise settling at the cutoff when the streams never close, the `drain` bound driven shorter
1543
1552
  and longer than a descendant release, `stop` alone reaching the moment with no `destroy` call, the
1544
- latched `stopping` refusing a `send`, the released abort listener, the spawn-fault path, and the
1553
+ latched `terminated` refusing a `send`, the released abort listener, the spawn-fault path, and the
1545
1554
  `drain` refusals at each end of its range.
1546
1555
  - [`tests/src/server/processes/Session.test.ts`](../tests/src/server/processes/Session.test.ts) —
1547
1556
  the byte face: a binary payload carrying NUL bytes, an invalid UTF-8 sequence, a lone carriage return, and an embedded line
@@ -1559,7 +1568,7 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
1559
1568
  - [`tests/src/server/processes/Supervisor.test.ts`](../tests/src/server/processes/Supervisor.test.ts)
1560
1569
  — the engine driven through a literal face: the moment order that ends the face's read pipeline, freezes the
1561
1570
  terminal state, and only then releases the face; the backpressure release reaching a face holding
1562
- a paused stdout before the termination sequence rather than after it; `ending` settling at the
1571
+ a paused stdout before the termination sequence rather than after it; `ended` settling at the
1563
1572
  native exit while `exit` waits out the drain a descendant holds open; a `deliver` refused once a
1564
1573
  termination has begun; and the one barrier every `end` call shares, with the child ending itself
1565
1574
  because its input ended.
@@ -1586,13 +1595,15 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
1586
1595
  and its percent-sign refusal, the environment merge under each platform input, the UTF-8-safe
1587
1596
  byte bounds retreating a cut to a code-point boundary, the per-chunk capture bound and the byte it
1588
1597
  keeps past `limit`, the validators, the termination helpers, and `waitForClose` across a close
1589
- inside its deadline, a deadline that elapsed first, and the listeners it leaves behind. The runs
1590
- carry their own rows: the asynchronous one-shot run's owned inputs, buffered outcomes, failure
1591
- delivery, cancellation, timeout, capture bounds, spawn faults, and pre-spawn refusal; the blocking
1592
- run's root-only timeout and argument integrity beside its own owned inputs, buffered outcomes,
1593
- failure delivery, capture bounds, spawn faults, and pre-spawn refusal; and the fire-and-forget
1594
- spawn's owned inputs, detached process-group behavior, invalid-input refusal, and the validated
1595
- working directory.
1598
+ inside its deadline, a deadline that elapsed first, and the listeners it leaves behind. The
1599
+ fire-and-forget spawn covers owned inputs, detached process-group behavior, invalid-input
1600
+ refusal, and the validated working directory.
1601
+ - [`tests/src/server/execution/execute.test.ts`](../tests/src/server/execution/execute.test.ts)
1602
+ — the asynchronous one-shot run: owned inputs, buffered outcomes, failure delivery,
1603
+ cancellation, timeout, capture bounds, spawn faults, and pre-spawn refusal.
1604
+ - [`tests/src/server/execution/executeSync.test.ts`](../tests/src/server/execution/executeSync.test.ts)
1605
+ — the blocking run: root-only timeout and argument integrity beside owned inputs, buffered
1606
+ outcomes, failure delivery, capture bounds, spawn faults, and pre-spawn refusal.
1596
1607
  - [`tests/guides.test.ts`](../tests/guides.test.ts) — this guide: the `## Surface` bijection against
1597
1608
  each published face's barrel, the interface-to-class method bijections, and the equality gate:
1598
1609
  every `Summary` cell against its declaration's description paragraph, the titled
@@ -1608,7 +1619,8 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
1608
1619
  vector each mode produces.
1609
1620
  - [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the same builders spawned for real:
1610
1621
  the fixture's own exit code, stdout, and stderr for a supplied detail, its own default when the
1611
- caller omits one, and the argument vector reaching it unmodified.
1622
+ caller omits one, and the argument vector reaching it unmodified; the exit-boundary fixture's
1623
+ listener identity and removal behavior.
1612
1624
 
1613
1625
  ## See also
1614
1626
 
@@ -178,6 +178,10 @@ checks membership through `STATUSES`.
178
178
 
179
179
  ### Errors
180
180
 
181
+ The error guard recognizes the shared brand across package copies and accepts
182
+ subclasses without requiring their name. It refuses transparent proxies and
183
+ unbranded look-alikes.
184
+
181
185
  | API | Kind | Summary |
182
186
  | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
183
187
  | `ProgramError` | class | Reports a coded programmer error thrown by the program layer, carrying a machine-readable code and an optional context and cause. |
@@ -120,6 +120,10 @@ and `context.cause` preserves the original throw. A `DEFINITION`/`INVALID` or
120
120
  `DESTROYED` engine throw maps to the matching code instead, and a `DEFINITION` throw
121
121
  raised by `qualify`'s own validation carries `context.definition`.
122
122
 
123
+ The guard recognizes the error's own identity brand across package copies and module
124
+ formats. It accepts subclasses regardless of their `name` and refuses transparent
125
+ proxies, unbranded look-alikes, and plain branded objects.
126
+
123
127
  ```ts
124
128
  import { isQualifierError, QualifierError } from '@orkestrel/qualifier'
125
129
 
@@ -103,6 +103,10 @@ and an optional `context` record of structured detail beside its message.
103
103
  The `isRaterError` guard narrows a caught value, so a handler reads the `code` member
104
104
  off it:
105
105
 
106
+ The guard recognizes the error's own identity brand across package copies and module
107
+ formats. It accepts subclasses regardless of their `name` and refuses transparent
108
+ proxies, unbranded look-alikes, and plain branded objects.
109
+
106
110
  ```ts
107
111
  import { isRaterError, RaterError } from '@orkestrel/rater'
108
112