@orkestrel/scaffold 0.0.137 → 0.0.139
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.
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +489 -23
- package/dist/bin/main.js +6 -6
- package/dist/host/agents/skills/orkestrel-journey/SKILL.md +33 -27
- package/dist/host/agents/skills/orkestrel-journey/references/captures.md +37 -16
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
- package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +5 -0
- package/dist/host/claude/agents/orkestrel.md +54 -54
- package/dist/host/claude/rules/typescript.md +4 -1
- package/dist/host/claude/rules/workspace.md +6 -4
- package/dist/host/guides/capture.md +442 -313
- package/dist/host/guides/contract.md +314 -210
- package/dist/host/guides/middleware.md +489 -259
- package/dist/host/guides/process.md +139 -53
- package/dist/host/guides/router.md +282 -165
- package/dist/host/guides/scaffold.md +35 -23
- package/dist/host/guides/server.md +417 -181
- package/dist/host/guides/test.md +353 -232
- package/dist/host/manifest.json +18 -18
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +19 -27
- package/dist/src/core/index.cjs +139 -60
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +139 -60
- package/dist/src/core/index.js.map +1 -1
- package/package.json +6 -6
|
@@ -139,22 +139,49 @@ The byte-bounding and result-assembly building blocks, from `@orkestrel/process/
|
|
|
139
139
|
The signalling and confirmation building blocks a bounded stop composes, from
|
|
140
140
|
`@orkestrel/process/server`.
|
|
141
141
|
|
|
142
|
-
| Name | Kind | Signature | Summary
|
|
143
|
-
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
144
|
-
| `inspectProcess` | function | `(pid: number) => boolean \| undefined` | Reports whether a process or POSIX process group still exists.
|
|
145
|
-
| `isExited` | function | `(child: Pick<ProcessChildInterface, 'exitCode' \| 'signalCode'>) => boolean` | Checks whether a child process has reached its native exit.
|
|
146
|
-
| `killProcess` | function | `(child: Pick<ProcessChildInterface, 'pid' \| 'kill'>, signal: NodeJS.Signals) => void` | Signals one owned child process, or its detached process group on a POSIX host.
|
|
147
|
-
| `killTree` | function | `(pid: number, timeout: number) => Promise<boolean>` | Kills one Windows process tree through `taskkill`.
|
|
148
|
-
| `waitForExit` | function | `(child: Pick<ProcessChildInterface, 'exitCode' \| 'signalCode' \| 'once' \| 'off'>, timeout: number) => Promise<void>` | Waits for one child process's native exit, bounded by a deadline.
|
|
149
|
-
| `waitForClose` | function | `(child: Pick<ProcessChildInterface, 'once' \| 'off'>, timeout: number) => Promise<boolean>` | Waits for one child process's streams to close, bounded by a deadline.
|
|
150
|
-
| `stopChild` | function | `(child: ProcessChildInterface, grace: number, confirm: number) => Promise<boolean>` | Terminates one child process tree and reports whether its native exit was observed.
|
|
142
|
+
| Name | Kind | Signature | Summary |
|
|
143
|
+
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
144
|
+
| `inspectProcess` | function | `(pid: number) => boolean \| undefined` | Reports whether a process or POSIX process group still exists. |
|
|
145
|
+
| `isExited` | function | `(child: Pick<ProcessChildInterface, 'exitCode' \| 'signalCode'>) => boolean` | Checks whether a child process has reached its native exit. |
|
|
146
|
+
| `killProcess` | function | `(child: Pick<ProcessChildInterface, 'pid' \| 'kill'>, signal: NodeJS.Signals) => void` | Signals one owned child process, or its detached process group on a POSIX host. |
|
|
147
|
+
| `killTree` | function | `(pid: number, timeout: number) => Promise<boolean>` | Kills one Windows process tree through `taskkill`. |
|
|
148
|
+
| `waitForExit` | function | `(child: Pick<ProcessChildInterface, 'exitCode' \| 'signalCode' \| 'once' \| 'off'>, timeout: number) => Promise<void>` | Waits for one child process's native exit, bounded by a deadline. |
|
|
149
|
+
| `waitForClose` | function | `(child: Pick<ProcessChildInterface, 'once' \| 'off'>, timeout: number) => Promise<boolean>` | Waits for one child process's streams to close, bounded by a deadline. |
|
|
150
|
+
| `stopChild` | function | `(child: ProcessChildInterface, grace: number, confirm: number) => Promise<boolean>` | Terminates one child process tree and reports whether its native exit was observed. |
|
|
151
|
+
| `stopGroup` | function | `(child: ProcessChildInterface, grace: number, members: readonly ProcessMember[]) => Promise<void>` | Terminates the POSIX process group an exited child led, while the group still has a member. |
|
|
151
152
|
|
|
152
153
|
`inspectProcess` returns `true` while the process or POSIX process group exists, including
|
|
153
154
|
when the host refuses the probe with `EPERM`. It returns `false` after the target is gone
|
|
154
155
|
(`ESRCH`), and `undefined` for any other host failure. It throws a `ProcessError` coded
|
|
155
156
|
`invalid` for a value that is not a safe integer, zero, or minus one. Windows accepts only
|
|
156
157
|
positive process ids and refuses every negative id before the host call. On POSIX, a negative
|
|
157
|
-
id other than minus one probes the process group identified by its magnitude.
|
|
158
|
+
id other than minus one probes the process group identified by its magnitude. A zombie still
|
|
159
|
+
answers the probe signal, so where the host publishes a `/proc` process table, `inspectProcess`
|
|
160
|
+
returns `false` for an id whose every thread, or every group member's every thread, reads `Z` or
|
|
161
|
+
`X` in two readings taken one after the other. A reading it cannot take reads as live, and so does
|
|
162
|
+
every group while the table's mount carries a `hidepid` option other than `0` or `off`, because
|
|
163
|
+
that mount hides other users' processes and a hidden member can be live. A host without the table,
|
|
164
|
+
and a table whose `self/stat` names a process other than this one or cannot be read, keep the signal's answer.
|
|
165
|
+
|
|
166
|
+
### Process-table readers
|
|
167
|
+
|
|
168
|
+
The Linux `/proc` reading `inspectProcess` reads a zombie through and `stopGroup` confirms a
|
|
169
|
+
group's identity through, from `@orkestrel/process/server`. Each reader takes the table's root as
|
|
170
|
+
an argument that defaults to `PROCESS_TABLE`, so a proof can point it at an inert table, and
|
|
171
|
+
`matchesProcessEnded` also takes the scan it repeats.
|
|
172
|
+
|
|
173
|
+
| Name | Kind | Signature | Summary |
|
|
174
|
+
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
175
|
+
| `parseProcessStat` | function | `(text: string) => ProcessStat \| undefined` | Parses one process-table `stat` line into the state, the process group, and the start time a liveness reading needs. |
|
|
176
|
+
| `scanProcessThreads` | function | `(pid: string, table?: string) => readonly ProcessTask[] \| undefined` | Scans the state of every thread of one process from a process table. |
|
|
177
|
+
| `scanGroupMembers` | function | `(group: number, table?: string) => readonly ProcessMember[] \| undefined` | Scans the members of one process group from a process table, each with its start time. |
|
|
178
|
+
| `scanProcessTasks` | function | `(pid: number, table?: string) => readonly ProcessTask[] \| undefined` | Scans every thread of one process, or of every member of one process group, from a process table. |
|
|
179
|
+
| `matchesEndedTasks` | function | `(first: readonly ProcessTask[], second: readonly ProcessTask[]) => boolean` | Checks whether two process-table readings show the same threads, every one of them exited. |
|
|
180
|
+
| `matchesOwnTable` | function | `(table?: string) => boolean` | Checks whether a process table numbers processes the way this process signals them. |
|
|
181
|
+
| `matchesTableHidden` | function | `(table?: string) => boolean` | Checks whether the mount of a process table hides other users' processes from this reader. |
|
|
182
|
+
| `matchesProcessEnded` | function | `(pid: number, table?: string, scan?: (pid: number, table: string) => readonly ProcessTask[] \| undefined) => boolean` | Checks whether a process or a process group has ended while the host still answers its id. |
|
|
183
|
+
| `matchesGroupMembers` | function | `(group: number, members: readonly ProcessMember[], table?: string) => boolean` | Checks whether a process group still holds a member a snapshot of that group named. |
|
|
184
|
+
| `collectGroupMembers` | function | `(child: Pick<ProcessChildInterface, 'pid'>, table?: string) => readonly ProcessMember[]` | Collects the members of the POSIX process group an exited child led, as of the call. |
|
|
158
185
|
|
|
159
186
|
### Validators
|
|
160
187
|
|
|
@@ -184,6 +211,8 @@ The defaults and host bounds, from `@orkestrel/process`.
|
|
|
184
211
|
| `PROCESS_OUTPUT` | const | `10485760` | Names the default maximum captured bytes, 10485760 each, for a one-shot run's stdout and stderr. |
|
|
185
212
|
| `PROCESS_TIMER` | const | `2147483647` | Names the largest timer delay, 2147483647 ms, the host schedules without truncating it to one. |
|
|
186
213
|
| `PROCESS_PATHEXT` | const | `".COM;.EXE;.BAT;.CMD"` | Lists the executable extensions a Windows lookup applies when the environment declares no `PATHEXT`, `.COM;.EXE;.BAT;.CMD`. |
|
|
214
|
+
| `PROCESS_TABLE` | const | `"/proc"` | Names the directory where a Linux host publishes its process table, `/proc`. |
|
|
215
|
+
| `PROCESS_ENDED` | const | `readonly string[]` | Lists the process-table states of a thread that has exited: `Z` for a zombie its parent has not reaped, and `X` for one the kernel is releasing. |
|
|
187
216
|
| `PROCESS_ERROR_CODES` | const | `readonly ["spawn", "timeout", "input", "duplicate", "protocol", "invalid"]` | Lists the machine-readable failure categories a `ProcessError` carries, in declaration order: `spawn`, `timeout`, `input`, `duplicate`, `protocol`, and `invalid`. |
|
|
188
217
|
|
|
189
218
|
### Types
|
|
@@ -219,13 +248,18 @@ The contracts and options, all from `@orkestrel/process`.
|
|
|
219
248
|
The Node-side contracts, from `@orkestrel/process/server`. Each sits in this face rather than
|
|
220
249
|
the host-independent one for its own reason: `ProcessChildInterface` names `NodeJS.Signals`, which
|
|
221
250
|
a host-independent contract cannot, and `SupervisorFace` names no Node type but its consumer is the
|
|
222
|
-
Node-only `Supervisor` engine, so the contract sits with the face that constructs one.
|
|
251
|
+
Node-only `Supervisor` engine, so the contract sits with the face that constructs one.
|
|
252
|
+
`ProcessStat`, `ProcessTask`, and `ProcessMember` describe what the Node-side process-table readers
|
|
253
|
+
parse. See
|
|
223
254
|
[Vocabulary](#vocabulary) for the `Face` suffix.
|
|
224
255
|
|
|
225
256
|
| Name | Kind | Signature | Summary |
|
|
226
257
|
| ----------------------- | --------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
227
258
|
| `ProcessChildInterface` | interface | `{ pid?, exitCode, signalCode, kill(), once(), off() }` | Represents the child boundary the termination helpers drive. |
|
|
228
259
|
| `SupervisorFace` | interface | `{ chunk, fault, relieve?, close, terminal, teardown }` | Represents the composing face's callbacks for each lifecycle moment of one supervised child. |
|
|
260
|
+
| `ProcessStat` | interface | `{ state, group, start }` | Represents the fields of one process-table `stat` entry a liveness reading needs. |
|
|
261
|
+
| `ProcessMember` | interface | `{ pid, start }` | Represents one process-group member as a group snapshot names it: its id and its start time. |
|
|
262
|
+
| `ProcessTask` | interface | `{ id, state }` | Represents one thread a process-table reading found: its `<pid>/<tid>` key and its state. |
|
|
229
263
|
|
|
230
264
|
### Surface notes
|
|
231
265
|
|
|
@@ -347,7 +381,7 @@ fault, and the terminal `exit`, alongside the `exit` promise.
|
|
|
347
381
|
| `backlog` | `number` | no | Soft high-water mark in bytes; termination retains at most twice `backlog`. Default: `PROCESS_BACKLOG`. |
|
|
348
382
|
| `delivery` | `number` | no | Milliseconds an unconfirmed `send` waits before resolving `false`; `0` or omitted disables the bound. |
|
|
349
383
|
| `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
|
|
384
|
+
| `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`; a signal already aborted refuses the spawn. |
|
|
351
385
|
| `on` | `EmitterHooks<ProcessEventMap>` | no | Initial `stderr`, `error`, and `exit` listeners installed at construction. |
|
|
352
386
|
| `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
|
|
353
387
|
|
|
@@ -397,7 +431,7 @@ it, so no switch selects whether one exists.
|
|
|
397
431
|
| `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`). |
|
|
398
432
|
| `evidence` | `number` | no | Maximum retained stderr tail in bytes. Default: `PROCESS_EVIDENCE` (`2_048`). |
|
|
399
433
|
| `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
|
|
434
|
+
| `signal` | `AbortSignal` | no | Aborting this signal terminates the child through the same bounded `stop`; a signal already aborted refuses the spawn. |
|
|
401
435
|
| `on` | `EmitterHooks<DuplexEventMap>` | no | Initial `stdout`, `stderr`, `error`, and `exit` listeners installed at construction. |
|
|
402
436
|
| `error` | `EmitterErrorHandler` | no | Receives a listener's throw, isolated from the engine. |
|
|
403
437
|
|
|
@@ -650,9 +684,10 @@ true` keeps it open until termination.
|
|
|
650
684
|
`stop` terminates the child tree, awaits its observed exit, and reports whether that exit arrived. It
|
|
651
685
|
resolves `true` when the child's native exit was observed and `false` when the confirmation wait
|
|
652
686
|
elapsed without it. Every call shares one termination, and the liveness fields are read again before
|
|
653
|
-
each signal, so no signal
|
|
654
|
-
|
|
655
|
-
|
|
687
|
+
each signal, so no signal reaches the child's own pid after an observed exit. On a POSIX host the
|
|
688
|
+
group the child led can still receive one, through `stopGroup`, as the host table later in this
|
|
689
|
+
section states. The window between initiating a signal and the host delivering it belongs to the
|
|
690
|
+
operating system, which is the limit of what any caller can hold. `destroy` runs `stop`, destroys stdin so every pending `send` settles, then destroys
|
|
656
691
|
the emitter last; it always resolves, including when termination was never confirmed.
|
|
657
692
|
|
|
658
693
|
`stop` and `destroy` each settle after [the terminal moment](#the-terminal-moment), bounded by
|
|
@@ -687,10 +722,10 @@ timeout must terminate the child tree.
|
|
|
687
722
|
|
|
688
723
|
POSIX and Windows terminate differently, and only POSIX has a cooperative phase.
|
|
689
724
|
|
|
690
|
-
| Host | Sequence
|
|
691
|
-
| ------- |
|
|
692
|
-
| POSIX | `SIGTERM` to the process group, wait `grace`, then `SIGKILL` to the group — each signal reaching the child directly when no group owns its pid. | used |
|
|
693
|
-
| Windows | `taskkill /F /T` on the whole tree at once, with a direct kill after the utility reports failure.
|
|
725
|
+
| Host | Sequence | `grace` |
|
|
726
|
+
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
727
|
+
| POSIX | `SIGTERM` to the process group, wait `grace`, then `SIGKILL` to the group — each signal reaching the child directly when no group owns its pid. After the child's exit, the same pair reaches the group while a member recorded at that exit remains and a member has not exited, the `grace` wait ending early when the read ends close. | used |
|
|
728
|
+
| Windows | `taskkill /F /T` on the whole tree at once, with a direct kill after the utility reports failure. | not used |
|
|
694
729
|
|
|
695
730
|
Windows has no signal a process group can receive, so `killTree` ends the tree through the
|
|
696
731
|
`taskkill.exe` utility addressed by its absolute `System32` path, which stops a `PATH` override
|
|
@@ -704,9 +739,24 @@ host. The host has reaped that number and can have handed it to another process,
|
|
|
704
739
|
naming it to `taskkill` reaches a process this package never spawned. Nothing recoverable is given
|
|
705
740
|
up by returning: measured on Windows 11 with Node v24.18.1 on 2026-08-21, `taskkill /F /T` against a
|
|
706
741
|
live root reaped every descendant in the fixture set, and against an exited root it reported the
|
|
707
|
-
process as not found while the descendant kept the pipe open and delivered for a further 2.28s.
|
|
708
|
-
descendant whose root has exited is beyond every mechanism here, and the `drain` bound is
|
|
709
|
-
the wait for it.
|
|
742
|
+
process as not found while the descendant kept the pipe open and delivered for a further 2.28s. On
|
|
743
|
+
Windows a descendant whose root has exited is beyond every mechanism here, and the `drain` bound is
|
|
744
|
+
what ends the wait for it.
|
|
745
|
+
|
|
746
|
+
A POSIX process group outlives its leader's exit while it has a member, but its id alone does not
|
|
747
|
+
prove that: after every member has left, the host can hand the id to an unrelated group. `Process`,
|
|
748
|
+
`Duplex`, and `execute` spawn every POSIX child as the leader of its own group, apart from the
|
|
749
|
+
caller's. When they observe the child's exit, `collectGroupMembers` records the members the group
|
|
750
|
+
still holds, each as its id and its start time. After `stopChild` returns they call `stopGroup`,
|
|
751
|
+
which signals the group only while `inspectProcess` reads a member that has not exited and, checked
|
|
752
|
+
last, the group still holds a member with an identical id and start time from that record. One
|
|
753
|
+
identity scan is all that separates that check from each signal. An exited child that left no
|
|
754
|
+
descendant therefore costs no wait. An empty or unreadable record signals nothing, and so does a
|
|
755
|
+
host that publishes no `/proc` process table, or a table whose `self/stat` names another process,
|
|
756
|
+
as one mounted from another PID namespace does; there only the drain bound ends the wait. A
|
|
757
|
+
descendant that left the group, by starting a session of its own, is beyond this route. So is a
|
|
758
|
+
descendant forked after the child's exit, from the moment no recorded member remains in the group,
|
|
759
|
+
its own ancestors included; the drain bound is what ends the wait for either.
|
|
710
760
|
|
|
711
761
|
After an undrained cutoff, no mechanism here can report whether further diagnostics existed, and that
|
|
712
762
|
is a limit rather than an omission. Node exposes no count of the writers still holding a pipe, and a
|
|
@@ -724,7 +774,10 @@ check and the call, and the child's native exit stays the authoritative terminal
|
|
|
724
774
|
|
|
725
775
|
`pid` is the host id of the spawned child, and `code` and `signal` are the terminal pair the host
|
|
726
776
|
recorded for it. The spawn is eager, so `pid` carries a number by the time `createProcess` returns,
|
|
727
|
-
and a spawn that produced no child reports `undefined` for that child's whole lifetime. `
|
|
777
|
+
and a spawn that produced no child reports `undefined` for that child's whole lifetime. A `signal`
|
|
778
|
+
that already aborted refuses the spawn: no child starts, `pid` stays `undefined`, `terminated` reads
|
|
779
|
+
`true`, and the terminal moment arrives after the constructor's caller yields, with
|
|
780
|
+
`{ code: null, signal: null, drained: true }`. `code` and
|
|
728
781
|
`signal` are `null` while the child runs; the host records them at the native exit, which arrives
|
|
729
782
|
before the terminal moment whenever a descendant holds the child's stdio open, so a supervisor
|
|
730
783
|
inside that window reads the child's own ending from them. A spawn fault records the host's negative
|
|
@@ -839,7 +892,9 @@ buildSpawn({ file: 'node', arguments: ['--version'] }).verbatim // false
|
|
|
839
892
|
`mergeEnvironment` builds the environment one child receives. Later maps override earlier ones, an
|
|
840
893
|
`undefined` value unsets a key, and on Windows the keys fold case-insensitively with the last writer
|
|
841
894
|
winning, so `PATH` followed by `Path` yields one variable rather than a rival pair the host would
|
|
842
|
-
resolve unpredictably.
|
|
895
|
+
resolve unpredictably. On every other host the parent environment drops each variable whose
|
|
896
|
+
lower-cased name an override claims, an unset included, because a tool such as npm reads its
|
|
897
|
+
`npm_config_` variables case-insensitively there too; the overrides keep their exact-case keys. `readVariable` reads one variable back under the same folding rule. Their
|
|
843
898
|
`mergePlatformEnvironment` and `readPlatformVariable` leaves accept an explicit platform, so every
|
|
844
899
|
folding decision executes on every test host.
|
|
845
900
|
|
|
@@ -884,16 +939,16 @@ the exit and the captured output together, without managing a live stream.
|
|
|
884
939
|
|
|
885
940
|
`ExecuteOptions` are all optional:
|
|
886
941
|
|
|
887
|
-
| Option | Type | Default | Meaning
|
|
888
|
-
| ------------- | ------------------------------------- | --------------------- |
|
|
889
|
-
| `workspace` | `string` | current directory | The working directory.
|
|
890
|
-
| `environment` | `Record<string, string \| undefined>` | inherit the parent | Overrides applied last; `undefined` unsets a key.
|
|
891
|
-
| `input` | `string` | the command's `input` | Standard-input payload, including NUL, overriding `command.input`.
|
|
892
|
-
| `timeout` | `number` | `0` (disabled) | Milliseconds before the child is terminated; `0` or omitted disables it.
|
|
893
|
-
| `grace` | `number` | `PROCESS_GRACE` | The POSIX `SIGTERM` to `SIGKILL` window when a timeout or abort ends it.
|
|
894
|
-
| `signal` | `AbortSignal` | none | Aborting this signal terminates the run and reports `aborted
|
|
895
|
-
| `strict` | `boolean` | `true` | When `false`, resolve with the result on failure instead of rejecting.
|
|
896
|
-
| `limit` | `number` | `PROCESS_OUTPUT` | Maximum captured bytes for stdout and for stderr, each.
|
|
942
|
+
| Option | Type | Default | Meaning |
|
|
943
|
+
| ------------- | ------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
944
|
+
| `workspace` | `string` | current directory | The working directory. |
|
|
945
|
+
| `environment` | `Record<string, string \| undefined>` | inherit the parent | Overrides applied last; `undefined` unsets a key. |
|
|
946
|
+
| `input` | `string` | the command's `input` | Standard-input payload, including NUL, overriding `command.input`. |
|
|
947
|
+
| `timeout` | `number` | `0` (disabled) | Milliseconds before the child is terminated; `0` or omitted disables it. |
|
|
948
|
+
| `grace` | `number` | `PROCESS_GRACE` | The POSIX `SIGTERM` to `SIGKILL` window when a timeout or abort ends it. |
|
|
949
|
+
| `signal` | `AbortSignal` | none | Aborting this signal terminates the run and reports `aborted`; a signal already aborted refuses the run before the spawn. |
|
|
950
|
+
| `strict` | `boolean` | `true` | When `false`, resolve with the result on failure instead of rejecting. |
|
|
951
|
+
| `limit` | `number` | `PROCESS_OUTPUT` | Maximum captured bytes for stdout and for stderr, each. |
|
|
897
952
|
|
|
898
953
|
`ExecuteSyncOptions` carries the same set without `grace` and without `signal`, because the
|
|
899
954
|
synchronous host offers neither a cooperative termination window nor in-flight cancellation.
|
|
@@ -915,10 +970,12 @@ const echoed = executeSync(
|
|
|
915
970
|
echoed.stdout === input // true
|
|
916
971
|
```
|
|
917
972
|
|
|
918
|
-
The `execute` function writes `input` with a host callback. A fault while that write is pending
|
|
919
|
-
the run by design and makes `failed` true. With
|
|
920
|
-
|
|
921
|
-
with `strict: false`, the result carries no
|
|
973
|
+
The `execute` function writes `input` with a host callback. A fault while that write is pending,
|
|
974
|
+
before any timeout or abort began, ends the run by design and makes `failed` true. With
|
|
975
|
+
`strict: true`, the rejection is coded `input`, its message states that standard-input writing
|
|
976
|
+
failed, and it carries the host fault as its `cause`; with `strict: false`, the result carries no
|
|
977
|
+
cause member. A fault that arrives after a termination began is that termination's consequence, so
|
|
978
|
+
the run rejects as `timeout` or `spawn` instead. This behavior is distinct from the quiet
|
|
922
979
|
constructor input phase of `Process`.
|
|
923
980
|
|
|
924
981
|
A run with no `timeout` and no `signal` is unbounded, and what it waits for is stdio completion
|
|
@@ -952,8 +1009,8 @@ A spawn fault reports the host's negative errno in `ProcessExit.code` and an asy
|
|
|
952
1009
|
`ExecuteResult.code`. The synchronous `executeSync` result reports `null` instead.
|
|
953
1010
|
|
|
954
1011
|
By default a failed run rejects with a `ProcessError` carrying the `ExecuteResult` on its `result`
|
|
955
|
-
property. An expired run carries code `timeout`, and a host fault while writing standard input
|
|
956
|
-
carries code `input`; every other failure carries code `spawn`. Passing `strict: false` settles with
|
|
1012
|
+
property. An expired run carries code `timeout`, and a host fault while writing standard input,
|
|
1013
|
+
before any termination began, carries code `input`; every other failure carries code `spawn`. Passing `strict: false` settles with
|
|
957
1014
|
the result even on failure, so you inspect `failed` yourself.
|
|
958
1015
|
|
|
959
1016
|
```ts
|
|
@@ -1046,8 +1103,9 @@ environment merge, the same `input` override, the same `limit` bounding, and the
|
|
|
1046
1103
|
behavior.
|
|
1047
1104
|
|
|
1048
1105
|
`execute` also bounds what follows termination. After a timeout or an abort ends the child,
|
|
1049
|
-
`stopChild` runs
|
|
1050
|
-
|
|
1106
|
+
`stopChild` runs, then `stopGroup` ends a POSIX descendant still in the child's group, and the
|
|
1107
|
+
outcome is then awaited for one further `PROCESS_CONFIRMATION`, so a descendant still holding the
|
|
1108
|
+
child's stdio cannot keep a terminated run pending forever. Nothing
|
|
1051
1109
|
bounds a run that was never terminated: with no `timeout` and no `signal` there is no deadline to
|
|
1052
1110
|
reach, and the run waits on stdio completion for as long as the descendant holds the pipe.
|
|
1053
1111
|
|
|
@@ -1143,7 +1201,7 @@ value with `isProcessError`, then branch on `code`.
|
|
|
1143
1201
|
| ----------- | --------------------------------------------------------------------------------------------------------- |
|
|
1144
1202
|
| `spawn` | A rejecting run failed outside its own timeout or input write. |
|
|
1145
1203
|
| `timeout` | A rejecting run's own `timeout` elapsed before completion. |
|
|
1146
|
-
| `input` | `execute` alone: a rejecting run's standard-input write reported a host fault.
|
|
1204
|
+
| `input` | `execute` alone: a rejecting run's standard-input write reported a host fault before any termination. |
|
|
1147
1205
|
| `duplicate` | `ProcessManager.launch` reused an id that is already live. |
|
|
1148
1206
|
| `protocol` | `ProcessManager.launch` ran after `destroy` began, or a supervised channel's open stdin reported a fault. |
|
|
1149
1207
|
| `invalid` | A public input was refused before anything was spawned. |
|
|
@@ -1159,7 +1217,12 @@ pass. Older boolean brands, transparent proxies, and branded plain objects fail
|
|
|
1159
1217
|
A run failure carries its `ExecuteResult` on `error.result`, and its command line, exit `code`, and
|
|
1160
1218
|
`signal` on `error.context`. A duplicate-id and a protocol failure carry the offending `id` on
|
|
1161
1219
|
`error.context`. A validation failure carries the rejected input on `error.context.value`. The
|
|
1162
|
-
underlying cause, when one exists, is retained on `error.cause
|
|
1220
|
+
underlying cause, when one exists, is retained on `error.cause`; an aborted run carries the
|
|
1221
|
+
`reason` of the caller's signal there. A standard-input fault that arrives after a timeout or an abort
|
|
1222
|
+
began is that termination's consequence, so the run still rejects as `timeout` or `spawn`. A signal
|
|
1223
|
+
that already aborted refuses the run before the spawn and rejects the way an abort during the run
|
|
1224
|
+
does, as a `spawn`-coded error whose `result` reports `aborted`; its `code` and `signal` are both
|
|
1225
|
+
`null`, because no child ran.
|
|
1163
1226
|
|
|
1164
1227
|
```ts
|
|
1165
1228
|
import { createDuplicateError, createInvalidError, createProtocolError } from '@orkestrel/process'
|
|
@@ -1440,8 +1503,9 @@ isExited(reporter) // whether the native exit arrived
|
|
|
1440
1503
|
after `exit` settles and keep no copy of your own.
|
|
1441
1504
|
- **Read `drained` before you treat the diagnostics as complete** — `true` reports that the child's
|
|
1442
1505
|
streams closed, so the diagnostics are everything the child wrote. `false` reports that the `drain`
|
|
1443
|
-
bound cut them off, and nothing can report whether more existed, because a descendant
|
|
1444
|
-
|
|
1506
|
+
bound cut them off, and nothing can report whether more existed, because a descendant the tree
|
|
1507
|
+
kill cannot reach can hold an inherited pipe, and the host counts no remaining writers. That is a
|
|
1508
|
+
descendant outside the child's POSIX process group, or one whose Windows root already exited.
|
|
1445
1509
|
- **Lower `drain` for a shutdown with a deadline of its own** — the default `PROCESS_DRAIN` bounds
|
|
1446
1510
|
the wait for a descendant that never releases the pipe. Pass `drain: 0` to cut the streams off as
|
|
1447
1511
|
soon as the bound is armed.
|
|
@@ -1540,10 +1604,14 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1540
1604
|
the isolated environment, the `invalid` refusals, and `destroy`. The terminal moment carries its
|
|
1541
1605
|
own rows: the frozen `evidence` tail read against a descendant that keeps writing, the `stderr`
|
|
1542
1606
|
event and the tail stopping together, `lines` ending an in-flight read after its queued lines, the
|
|
1543
|
-
`exit` promise settling
|
|
1607
|
+
`exit` promise settling after `destroy` ends a descendant through the group its exited root led
|
|
1608
|
+
where a POSIX group reaches it and at the cutoff where none does, the `drain` bound driven shorter
|
|
1544
1609
|
and longer than a descendant release, `stop` alone reaching the moment with no `destroy` call, the
|
|
1545
1610
|
latched `terminated` refusing a `send`, the released abort listener, the spawn-fault path, and the
|
|
1546
|
-
`drain` refusals at each end of its range.
|
|
1611
|
+
`drain` refusals at each end of its range. The child leads a process group apart from the
|
|
1612
|
+
parent's, a signal that already aborted refuses the spawn and still reaches the terminal moment, a
|
|
1613
|
+
teardown after a natural exit with no descendant waits out no `grace`, and the multibyte
|
|
1614
|
+
`evidence` tail reads the same whatever chunks the stderr pipe delivers.
|
|
1547
1615
|
- [`tests/src/server/processes/Duplex.test.ts`](../tests/src/server/processes/Duplex.test.ts) —
|
|
1548
1616
|
the byte face: a binary payload carrying NUL bytes, an invalid UTF-8 sequence, a lone carriage return, and an embedded line
|
|
1549
1617
|
feed arriving byte-identical in one event, a half-megabyte stream reassembled byte for byte, and
|
|
@@ -1556,7 +1624,7 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1556
1624
|
child overruns, keeping an ended channel quiet when a pending write later faults, and changing
|
|
1557
1625
|
nothing after a `stop`. The endings pulled apart by a descendant holding the pipe, the `exit` event
|
|
1558
1626
|
and promise agreeing once, the pid and the frozen `evidence` tail beside the live `stderr` chunks,
|
|
1559
|
-
the spawn-fault path, and the `invalid` refusals.
|
|
1627
|
+
the spawn-fault path, the spawn a signal that already aborted refuses, and the `invalid` refusals.
|
|
1560
1628
|
- [`tests/src/server/processes/Supervisor.test.ts`](../tests/src/server/processes/Supervisor.test.ts)
|
|
1561
1629
|
— the engine driven through a literal face: the moment order that ends the face's read pipeline, freezes the
|
|
1562
1630
|
terminal state, and only then releases the face; the backpressure release reaching a face holding
|
|
@@ -1588,11 +1656,29 @@ The pure decision rows do not prove Windows end to end. They prove the decisions
|
|
|
1588
1656
|
byte bounds retreating a cut to a code-point boundary, the per-chunk capture bound and the byte it
|
|
1589
1657
|
keeps past `limit`, the validators, the termination helpers, and `waitForClose` across a close
|
|
1590
1658
|
inside its deadline, a deadline that elapsed first, and the listeners it leaves behind. The
|
|
1591
|
-
|
|
1592
|
-
|
|
1659
|
+
environment rows drop an inherited variable an added name claims under every platform input. The
|
|
1660
|
+
tail trim keeps the longest code-point suffix at every cut of a mixed-width text, and
|
|
1661
|
+
[`tests/src/server/helpers.bench.ts`](../tests/src/server/helpers.bench.ts) reads its cost at a
|
|
1662
|
+
64 KiB bound against the array walk it replaced. `inspectProcess` reads a real unreaped zombie and
|
|
1663
|
+
its group as ended, the process-table readers run over inert tables, each reading they cannot take
|
|
1664
|
+
included, `matchesTableHidden` reads a `hidepid` mount whose line carries an optional field and an
|
|
1665
|
+
escaped mount point as hiding, a table whose `self/stat` names another process yields no reading and no
|
|
1666
|
+
member, and a second scan that gains a task reads as live through an injected scan. `stopGroup`
|
|
1667
|
+
ends the descendant an exited group leader left behind while it leaves a live root's group alone,
|
|
1668
|
+
sends no `SIGKILL` after the last recorded member has gone though an unrecorded member lives, and
|
|
1669
|
+
signals nothing for a group id an unrelated process leads, against a control that carries that
|
|
1670
|
+
process's own id and start time. The fire-and-forget spawn covers owned inputs, detached process-group behavior,
|
|
1671
|
+
invalid-input refusal, and the validated working directory.
|
|
1593
1672
|
- [`tests/src/server/execution/execute.test.ts`](../tests/src/server/execution/execute.test.ts)
|
|
1594
1673
|
— the asynchronous one-shot run: owned inputs, buffered outcomes, failure delivery,
|
|
1595
|
-
cancellation, timeout, capture bounds, spawn faults, and pre-spawn refusal.
|
|
1674
|
+
cancellation, timeout, capture bounds, spawn faults, and pre-spawn refusal. A signal that already
|
|
1675
|
+
aborted refuses the run before the spawn, an abort carries the signal's `reason` as the rejection
|
|
1676
|
+
`cause`, and a timeout ends a POSIX descendant that holds the pipe after the root exited, settling
|
|
1677
|
+
near the timeout.
|
|
1678
|
+
- [`tests/src/server/parsers.test.ts`](../tests/src/server/parsers.test.ts) — the process-table
|
|
1679
|
+
`stat` parser: the state, the group, and the start time read after the last parenthesis of a
|
|
1680
|
+
command name that holds spaces and parentheses, and the refusal of text that carries no state, no
|
|
1681
|
+
numeric group, or no numeric start time.
|
|
1596
1682
|
- [`tests/src/server/execution/executeSync.test.ts`](../tests/src/server/execution/executeSync.test.ts)
|
|
1597
1683
|
— the blocking run: root-only timeout and argument integrity beside owned inputs, buffered
|
|
1598
1684
|
outcomes, failure delivery, capture bounds, spawn faults, and pre-spawn refusal.
|