opencode-effect-enforcer 0.2.6 → 0.3.0

package/skills/effect-cache/SKILL.md

@@ -15,6 +15,9 @@ the yielded service and `get` / `contextEffect` / `contextEffectOption`: an entr
 can fail when reacquired after successful preloading. Invalidating an active
 RcMap/LayerMap entry releases it after its last borrower closes; a replacement
 entry remains independently owned.
+Preload keys with zero `idleTimeToLive` are skipped, including the default TTL.
+Set a non-zero TTL when construction must eagerly acquire and validate them;
+otherwise acquisition failures surface on first use.
 
 The Effect v4 source is available at `~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/`.
 Browse and read files there directly to look up APIs, types, and implementations.
@@ -47,7 +50,7 @@ interface Cache<Key, A, E = never, R = never> {
 How to think about it:
 
 - **Entries store the lookup `Exit`** — successes *and failures* are cached. A failed lookup keeps failing from cache until the entry expires, is invalidated, or is refreshed.
-- **Concurrent `get`s of the same missing key share one lookup.** The first caller runs the lookup on its own fiber; the rest await the same `Deferred`.
+- **Concurrent `get`s of the same missing key share one lookup fiber.** Each caller waits independently; interrupting one waiter does not cancel work still needed by another. The last departing waiter interrupts a pending lookup.
 - **Insertion-ordered map = LRU.** Reads move the entry to the back; when capacity is exceeded the oldest entries are evicted.
 - **TTL is computed per entry** from the lookup `Exit` and the key, against the fiber's `Clock` — `TestClock` works. Expiry is lazy: entries are removed when next touched.
 - **`ScopedCache`** is the same model where each entry additionally owns a `Scope`: resources acquired during the lookup live exactly as long as the entry is cached.
@@ -191,7 +194,7 @@ If an older in-flight lookup is interrupted after `set` installs a newer value,
 yield* Cache.invalidate(cache, 'k'); // remove one key; no-op if absent
 yield* Cache.invalidateAll(cache); // clear everything
 
-// Conditional: removes only a *resolved successful* value matching the predicate.
+// Conditional: awaits a pending entry, then removes a successful value matching the predicate.
 // Returns false for missing, expired, failed, or non-matching entries.
 const removed: boolean = yield* Cache.invalidateWhen(cache, 'k', (v) => v.stale);
 ```
@@ -205,7 +208,7 @@ const fresh = yield* Cache.refresh(cache, 'k');
 - Always invokes the lookup, even for an unexpired entry, and resets the TTL from the new exit.
 - For an **existing** key, the old entry keeps serving `get` callers until the new lookup completes — built-in stale-while-revalidate.
 - For a **missing** key, a pending entry is inserted immediately; concurrent `get`s wait on it.
-- Concurrent `refresh` calls are **not deduplicated** — each runs the lookup independently (only `get` dedups).
+- `Cache.refresh` calls are **not deduplicated** — each runs the lookup independently. `ScopedCache.refresh` of a missing key delegates to `get` and shares that pending lookup; refreshes of existing keys run independently.
 
 ---
 
@@ -234,6 +237,11 @@ yield* Cache.get(cache, 'd'); // evicts 'b'
 - `Duration.infinity` (the default) means no expiry. `Duration.zero` means the entry expires immediately — effectively "do not cache this result".
 - `refresh` and re-`get`-after-expiry both restart the TTL clock; plain `get` hits do not extend it (no sliding expiration).
 
+`Cache.get` does not retain a zero-TTL result after completion. A synchronous
+zero-TTL lookup does not occupy capacity and evict a live entry; a pending lookup
+still occupies capacity while it is shared. `ScopedCache` has the distinct lazy
+resource-release behavior described in section 8.
+
 Per-key and per-result TTL via `makeWith`:
 
 ```ts
@@ -274,7 +282,7 @@ const robust = yield* Cache.makeWith(fetchUser, {
 });
 ```
 
-**Interruption poisons entries the same way**: the lookup runs on the fiber of the caller that triggered the miss. If that fiber is interrupted mid-lookup, the entry's deferred completes with the interrupt exit — concurrent waiters fail with it, and with an infinite TTL later `get`s keep replaying the interrupt instead of retrying. The exit-aware TTL above also fixes this, because an interrupt is a non-success exit (`Exit.isSuccess(exit) === false`) and gets a zero/short TTL.
+**Interruption is not cached.** Missing-key lookups run in daemon fibers, shared by their waiters. One caller's interruption leaves the lookup alive while another caller is waiting. When the last waiter leaves before completion, the lookup is interrupted and its entry removed; a later `get` starts again. `ScopedCache` also closes that lookup's entry scope. Children forked with `forkChild` inside the lookup end with the lookup fiber, not with the requesting caller; use the entry scope for resource-lifetime background work.
 
 `getSuccess`, `values`, and `entries` skip failed entries; `getOption` and `get` propagate the cached error; `invalidateWhen` returns `false` for failed entries (the predicate only sees successes).
 
@@ -341,6 +349,10 @@ The entry's scope is closed — releasing everything the lookup acquired — whe
 4. **replaced** (`set` over an existing key; `refresh` closes the old entry's scope after the new lookup completes),
 5. **orphaned by cache close** (the owning scope closes).
 
+A pending shared lookup also closes its entry scope when its last waiter leaves.
+Interrupting an existing-key `refresh` closes the replacement scope and leaves
+the previous entry intact.
+
 ```ts
 const tracker: Array<string> = [];
 const cache = yield* ScopedCache.make({
@@ -434,7 +446,7 @@ const cacheB = yield* Cache.make({
 const row = yield* Cache.get(cacheB, 1).pipe(Effect.provideService(Db, dbImpl));
 ```
 
-At runtime the lookup always sees the construction-time context merged with the caller's context (the caller's services win on conflicts). Tracing is connected: the lookup runs on the calling fiber, so spans created inside the lookup are children of the caller's current span. Remember the lookup runs **once per miss** — only the first caller's context matters for a given entry.
+At runtime the lookup sees the construction-time context merged with the initiating caller's context (the caller's services win on conflicts). The shared lookup fiber inherits that caller's tracing context. Remember the lookup runs **once per miss** — later waiters do not replace the context for a pending entry.
 
 The same option exists on `ScopedCache.make`/`makeWith`.
 
@@ -597,9 +609,9 @@ it.effect('expires entries after the TTL', () =>
 2. **v4 renames type parameters, it does not reorder them** — v3's `Cache<Key, Value, Error>` becomes `Cache<Key, A, E, R>`: same value-before-error order with a services parameter appended. Only the pre-v3 `@effect/io` era used `Cache<Key, Error, Value>`.
 3. **`Cache.makeWith(lookup, options)` vs `ScopedCache.makeWith({ lookup, ...options })`** — `Cache.makeWith` takes the lookup as a separate first argument; `ScopedCache.makeWith` (and both `make`s) take one options object containing `lookup`.
 4. **Failures are cached with the default infinite TTL** — one transient lookup error fails that key forever. Use `makeWith` with an exit-aware TTL (`Exit.isSuccess(exit) ? ttl : Duration.zero`).
-5. **Interrupting the fiber that started a lookup poisons the entry** — the lookup runs on the first caller's fiber; if it is interrupted, the interrupt exit is cached and replayed to waiters and later `get`s. The exit-aware TTL in (4) also covers interrupts.
+5. **Confusing caller cancellation with lookup cancellation** — a shared missing-key lookup survives while any waiter remains. The last departing waiter interrupts pending work; interrupted entries are removed, and `ScopedCache` closes their scopes. Failure TTL policy is still needed for ordinary failures.
 6. **`timeToLive` in `make` is a `Duration.Input` value, not a function** — the `(exit, key) => Duration.Input` form only exists on `makeWith`; passing a function to `make` won't compile.
-7. **`refresh` is not deduplicated** — concurrent `refresh` calls each run the lookup; only `get` shares in-flight lookups. Serialize refreshes yourself if the lookup is expensive.
+7. **Assuming all refreshes deduplicate** — `Cache.refresh` and existing-key `ScopedCache.refresh` run independently. Only missing-key `ScopedCache.refresh` delegates to the shared `get` path. Serialize expensive refreshes if needed.
 8. **Don't mutate key objects after first use** — plain objects compare structurally in v4 (equal-content literals do hit), but `Equal`/`Hash` cache their results per object, so a mutated key misbehaves silently. Prefer primitives or immutable `Data.Class`/`Schema.Class` keys.
 9. **Don't `Effect.acquireRelease` inside a plain `Cache` lookup** — `Scope` leaks into `R` and finalizers attach to whatever outer scope is around, not to the entry: nothing is released on eviction/invalidation. Use `ScopedCache`, which provides a per-entry scope.
 10. **ScopedCache values die with their entry** — after `invalidate`/eviction/expiry-purge the value's finalizers have run. Don't hold the value beyond the entry's lifetime; use `effect/Pool` for checkout semantics.

package/skills/effect-cli/SKILL.md

@@ -20,8 +20,11 @@ scalars containing colon-whitespace or a trailing colon: quote those values.
 
 ## Import Pattern
 
+The CLI APIs are marked `@stability unstable` even at the stable package release.
+Inspect `effect@4.0.0:packages/effect/src/cli/` for this baseline's contracts.
+
 ```typescript
-import { Argument, Command, Flag, Prompt } from 'effect/unstable/cli';
+import { Argument, Command, Flag, Prompt } from 'effect/cli';
 ```
 
 Platform services and runtime for the entry point:
@@ -37,7 +40,7 @@ Positional arguments are parsed in order. Use `Flag.Boolean` for toggles or `Arg
 ### Constructors
 
 ```typescript
-import { Argument } from 'effect/unstable/cli';
+import { Argument } from 'effect/cli';
 
 Argument.String('name'); // string
 Argument.Int('count'); // number (integer)
@@ -64,7 +67,7 @@ Argument.FileSchema('config', MySchema); // reads and validates file via Schema
 ### Combinators
 
 ```typescript
-import { Argument } from 'effect/unstable/cli';
+import { Argument } from 'effect/cli';
 
 // Description for help text
 Argument.String('file').pipe(Argument.withDescription('Input file'));
@@ -121,10 +124,16 @@ Argument.Int('count').pipe(
 
 Flags are named options with `--name` or `-alias` syntax.
 
+Negative numeric tokens such as `-3`, `-3.70`, `-.5`, and `-1e-3` are values,
+not short-option bundles: `--lon -3.70` works with `Flag.Finite('lon')`.
+Use `--` to pass trailing operands that otherwise look like options; a lone
+`-` is also retained as a value. Numeric lexing does not replace the chosen
+primitive's validation.
+
 ### Constructors
 
 ```typescript
-import { Flag } from 'effect/unstable/cli';
+import { Flag } from 'effect/cli';
 
 Flag.Boolean('verbose'); // required: --verbose / --no-verbose; omission fails
 Flag.String('config'); // --config value
@@ -152,7 +161,7 @@ Flag.KeyValuePair('env'); // --env FOO=bar → Record<string, string>
 ### Combinators
 
 ```typescript
-import { Flag } from 'effect/unstable/cli';
+import { Flag } from 'effect/cli';
 
 // Alias
 Flag.Boolean('verbose').pipe(
@@ -217,7 +226,7 @@ Bare boolean flags are required. `--verbose` produces `true`, `--no-verbose` pro
 <!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { Prompt } from 'effect/unstable/cli';
+import { Prompt } from 'effect/cli';
 
 Prompt.Int({ message: 'Count', default: 42 });
 Prompt.File({ message: 'Pick file', default: '/workspace/config.json' });
@@ -253,7 +262,7 @@ choice values rather than pre-escaping your domain values.
 
 ```typescript
 import { Console, Effect } from 'effect';
-import { Argument, Command, Flag } from 'effect/unstable/cli';
+import { Argument, Command, Flag } from 'effect/cli';
 
 // Simple command (no config, no handler)
 const version = Command.make('version');
@@ -509,7 +518,7 @@ Command.provideSync(MyService, (config) => makeMyService(config.env));
 ```typescript
 import { NodeRuntime, NodeServices } from '@effect/platform-node';
 import { Effect } from 'effect';
-import { Command, Flag } from 'effect/unstable/cli';
+import { Command, Flag } from 'effect/cli';
 
 const myCommand = Command.make(
 	'myapp',

package/skills/effect-command-executor/SKILL.md

@@ -5,13 +5,16 @@ description: Spawn and manage child processes using Effect's ChildProcess module
 
 # Child Process Execution with Effect v4
 
+Targets **Effect 4.0.0**, checked against the `effect@4.0.0` source tag. Keep platform packages on the same version. The process API is marked `@stability unstable`, so check contracts again before a minor-version upgrade.
+
 ## Overview
 
-Node process-group cleanup waits for the leader and descendants. Without
+On POSIX, Node process-group cleanup waits for the leader and descendants. Without
 `forceKillAfter`, cleanup waits up to one second without escalating. With it,
 the group receives SIGKILL at the deadline, then a final bounded wait. Native
 timers drive escalation even under TestClock. `exitCode` / `isRunning` describe
 the leader, not all descendants; do not use virtual time alone to prove OS cleanup.
+On Windows, Node uses `taskkill` for tree termination and waits for the leader.
 
 The `ChildProcess` module provides type-safe, composable process execution with automatic resource cleanup via `Scope`. Commands are AST values — built first with `make` and `pipeTo`, then executed via the `ChildProcessSpawner` service.
 
@@ -23,12 +26,12 @@ The `ChildProcess` module provides type-safe, composable process execution with
 - Streaming output from long-running processes
 - Managing process lifecycles with scoped cleanup
 
-**Note:** This skill covers child process execution, NOT `@effect/cli` for building CLI applications.
+**Note:** This skill covers child process execution; use `effect/cli` for building CLI applications.
 
 ## Import Pattern
 
 ```typescript
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 ```
 
 Platform layer (Node.js):
@@ -41,8 +44,9 @@ import { NodeServices } from '@effect/platform-node';
 
 ### Template Literal Form
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Simple command — parsed by whitespace
 const cmd = ChildProcess.make`echo hello world`;
@@ -58,8 +62,9 @@ const cmd3 = ChildProcess.make`oxfmt ${files}`;
 
 ### Options + Template Literal Form
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Options object returns a tagged template function
 const cmd = ChildProcess.make({ cwd: '/tmp' })`ls -la`;
@@ -73,8 +78,9 @@ const cmd2 = ChildProcess.make({
 
 ### Array Form
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Explicit command + args array
 const cmd = ChildProcess.make('git', ['status'], {
@@ -99,8 +105,9 @@ const cmd3 = ChildProcess.make('node', {
 
 ### Command Options
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 const cmd = ChildProcess.make('node', ['script.js'], {
 	// Working directory
@@ -141,8 +148,9 @@ The `fd3`/`fd4` names configure child-process stdio channels. Process handles ex
 
 ### Combinators
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Set cwd (applies to all commands in a pipeline)
 const cmd = ChildProcess.make`ls -la`.pipe(ChildProcess.setCwd('/tmp'));
@@ -165,7 +173,7 @@ Commands are `Effect` values: `yield*` on a command evaluates through its `Effec
 
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -175,9 +183,10 @@ const program = Effect.gen(function* () {
 
 ### Capture as String
 
+<!-- typecheck -->
 ```typescript
 import { Effect, String } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -190,39 +199,45 @@ const program = Effect.gen(function* () {
 
 ### Capture as Lines
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Arr from 'effect/Array';
+import * as Str from 'effect/String';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const files = yield* spawner.lines(
 		ChildProcess.make('git', ['diff', '--name-only', 'main...HEAD'])
 	);
-	const tsFiles = files.filter((f) => f.endsWith('.ts'));
+	const tsFiles = Arr.filter(files, Str.endsWith('.ts'));
 });
 ```
 
 ### Progressive Output with Side Effects
 
+<!-- typecheck -->
 ```typescript
 import { Effect, Stream } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-	let output = '';
 	const handle = yield* spawner.spawn(
 		ChildProcess.make('bun', ['test'], {
 			extendEnv: true,
 			stdin: 'ignore'
 		})
 	);
-	yield* Stream.runForEach(Stream.decodeText(handle.all), (chunk) =>
-		Effect.sync(() => {
-			output += chunk;
-		})
-	).pipe(Effect.forkScoped);
+	// Drain to EOF before leaving the scope, propagating read/progress failures.
+	const output = yield* handle.all.pipe(
+		Stream.decodeText(),
+		Stream.tap((chunk) => Effect.logDebug('Process output').pipe(
+			Effect.annotateLogs({ characters: chunk.length })
+		)),
+		Stream.mkString
+	);
 	const exitCode = yield* handle.exitCode;
 	return { output, exitCode };
 }).pipe(Effect.scoped);
@@ -230,29 +245,41 @@ const program = Effect.gen(function* () {
 
 Use this pattern when you need per-chunk side effects (progress reporting, streaming to UI) during command execution. `spawner.string`/`spawner.lines` cannot provide per-chunk callbacks.
 
+Waiting for `handle.exitCode` alone does not drain output. If you fork a reader, join it before closing the scope and returning captured output. `Stream.mkString` buffers all text; for unbounded output, use `Stream.runForEach` without retaining it. Treat process output as potentially sensitive when choosing a progress callback.
+
 ### Get Exit Code
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Schema from 'effect/Schema';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
+
+class CommandFailed extends Schema.TaggedError<CommandFailed>()('CommandFailed', {
+	exitCode: Schema.Number
+}) {}
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const exitCode = yield* spawner.exitCode(
-		ChildProcess.make('test', ['-f', 'package.json'])
+		ChildProcess.make('test', ['-f', 'package.json'], {
+			stdin: 'ignore', stdout: 'ignore', stderr: 'ignore'
+		})
 	);
 	// exitCode: ExitCode (branded number)
 	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-		yield* Effect.fail(new Error('file not found'));
+		return yield* Effect.fail(new CommandFailed({ exitCode }));
 	}
 });
 ```
 
+`string`, `lines`, and stream helpers collect output; they do **not** reject a nonzero exit code. Use a scoped handle when success requires both captured output and a checked status. When using `exitCode` alone, inherit or ignore stdout/stderr so an unread pipe cannot fill and stall a noisy process. Output helpers default to stdout; pass `{ includeStderr: true }` to consume combined output, or configure stderr as `inherit`/`ignore` when only stdout is needed.
+
 ### Stream Output (Long-Running Processes)
 
 ```typescript
 import { Console, Effect, Stream } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -273,9 +300,15 @@ const program = Effect.gen(function* () {
 
 Use `spawner.spawn` when you need the process handle for interactive control, streaming output while running, or checking exit codes.
 
+<!-- typecheck -->
 ```typescript
 import { Console, Effect, Stream } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Schema from 'effect/Schema';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
+
+class LintFailed extends Schema.TaggedError<LintFailed>()('LintFailed', {
+	exitCode: Schema.Number
+}) {}
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -298,7 +331,7 @@ const program = Effect.gen(function* () {
 	// Wait for exit
 	const exitCode = yield* handle.exitCode;
 	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-		yield* Effect.fail(new Error(`lint failed: exit ${exitCode}`));
+		return yield* Effect.fail(new LintFailed({ exitCode }));
 	}
 }).pipe(Effect.scoped); // <-- spawn requires Scope
 ```
@@ -310,7 +343,7 @@ const program = Effect.gen(function* () {
 | `pid`             | `ProcessId`                                    | Process identifier (branded number)                                        |
 | `exitCode`        | `Effect<ExitCode, PlatformError>`              | Waits for exit, returns exit code                                          |
 | `isRunning`       | `Effect<boolean, PlatformError>`               | Check if still running                                                     |
-| `kill(options?)`  | `Effect<void, PlatformError>`                  | Kill with signal; pass `{ forceKillAfter: '3 seconds' }` to ensure cleanup |
+| `kill(options?)`  | `Effect<void, PlatformError>`                  | Kill with signal; `forceKillAfter` bounds graceful waiting before escalation |
 | `stdin`           | `Sink<void, Uint8Array, never, PlatformError>` | Write to process stdin                                                     |
 | `stdout`          | `Stream<Uint8Array, PlatformError>`            | Read process stdout                                                        |
 | `stderr`          | `Stream<Uint8Array, PlatformError>`            | Read process stderr                                                        |
@@ -320,9 +353,10 @@ const program = Effect.gen(function* () {
 
 ## Piping Commands
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -371,12 +405,18 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
 ```
 
-Or provide just the spawner:
+Or compose the spawner with its FileSystem and Path dependencies:
 
 ```typescript
-import { NodeChildProcessSpawner } from '@effect/platform-node';
+import { NodeChildProcessSpawner, NodeFileSystem, NodePath } from '@effect/platform-node';
+import { Effect, Layer } from 'effect';
+import { ChildProcessSpawner } from 'effect/process';
 
-const program = myEffect.pipe(Effect.provide(NodeChildProcessSpawner.layer));
+declare const myEffect: Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner>;
+const SpawnerLayer = NodeChildProcessSpawner.layer.pipe(
+	Layer.provide(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer))
+);
+const program = myEffect.pipe(Effect.provide(SpawnerLayer));
 ```
 
 ## Complete Example: DevTools Service
@@ -392,7 +432,8 @@ import {
 	Stream,
 	String
 } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Arr from 'effect/Array';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 class DevToolsError extends Schema.TaggedError<DevToolsError>()(
 	'DevToolsError',
@@ -442,7 +483,7 @@ class DevTools extends Context.Service<
 					.pipe(
 						Effect.mapError((cause) => new DevToolsError({ cause }))
 					);
-				return files.filter((file) => file.endsWith('.ts'));
+				return Arr.filter(files, String.endsWith('.ts'));
 			});
 
 			const recentCommitSubjects = spawner
@@ -463,7 +504,7 @@ class DevTools extends Context.Service<
 			const runLintFix = Effect.gen(function* () {
 				const handle = yield* spawner
 					.spawn(
-						ChildProcess.make('bun', ['lint'], {
+						ChildProcess.make('bun', ['lint', '--fix'], {
 							env: { FORCE_COLOR: '1' },
 							extendEnv: true,
 							stdin: 'ignore'
@@ -484,11 +525,9 @@ class DevTools extends Context.Service<
 					Effect.mapError((cause) => new DevToolsError({ cause }))
 				);
 				if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-					return yield* new DevToolsError({
-						cause: new Error(
-							`bun lint failed with exit code ${exitCode}`
-						)
-					});
+					return yield* Effect.fail(new DevToolsError({
+						cause: { command: 'bun lint --fix', exitCode }
+					}));
 				}
 			}).pipe(Effect.scoped);
 
@@ -499,7 +538,9 @@ class DevTools extends Context.Service<
 				runLintFix
 			});
 		})
-	).pipe(Layer.provide(NodeServices.layer));
+	);
+
+	static readonly defaultLayer = DevTools.layer.pipe(Layer.provide(NodeServices.layer));
 }
 ```
 
@@ -516,14 +557,14 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped);
 ```
 
-### DON'T: Use `spawner.spawn` without scoping
+### DON'T: Run a scoped program without providing its Scope
 
 ```typescript
-// Process handle leaks — no scope to manage cleanup
+// This definition is valid and retains Scope in its requirements.
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const handle = yield* spawner.spawn(ChildProcess.make`my-server`);
-	// ❌ no Effect.scoped — process may leak
+	// The caller must own/provide Scope before running this program.
 });
 ```
 
@@ -571,22 +612,15 @@ class MyService extends Context.Service<
 >()('MyService') {}
 ```
 
-### DO: Check `ExitCode` with the branded constructor
+### DO: Check the exit status explicitly
 
 ```typescript
 if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-	yield* Effect.fail(new Error(`command failed: ${exitCode}`));
+	return yield* Effect.fail(new CommandFailed({ exitCode }));
 }
 ```
 
-### DON'T: Compare exit codes as raw numbers
-
-```typescript
-// ❌ ExitCode is a branded type — direct number comparison may not work as expected
-if (exitCode !== 0) {
-	/* ... */
-}
-```
+`ExitCode` is a branded **number**, not a boxed runtime value. Both `exitCode !== 0` and comparison with `ChildProcessSpawner.ExitCode(0)` work. The constructor is useful when supplying an ExitCode to a typed API; the brand does not change numeric comparison semantics.
 
 ### DO: Use `handle.all` for interleaved stdout+stderr
 
@@ -610,9 +644,10 @@ yield* Stream.merge(handle.stdout, handle.all).pipe(Stream.runCollect);
 
 Child process operations fail with `PlatformError`:
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -621,7 +656,9 @@ const program = Effect.gen(function* () {
 		.string(ChildProcess.make`non-existent-command`)
 		.pipe(
 			Effect.catchTag('PlatformError', (error) =>
-				Effect.succeed(`fallback: ${error.message}`)
+				error.reason._tag === 'NotFound'
+					? Effect.succeed('Optional command is unavailable')
+					: Effect.fail(error)
 			)
 		);
 });
@@ -637,6 +674,7 @@ Keep process kill, timeout, and output-drain logic inside the process adapter th
 
 Use `Effect.callback` to convert an `AbortSignal` (or any event-driven API) into an Effect. The cleanup Effect removes the listener, and the already-aborted edge case is handled first:
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
 
@@ -651,16 +689,25 @@ const fromAbortSignal = (signal: AbortSignal) =>
 
 ### Abort / Timeout Multiplexing
 
-Combine `Effect.raceAll` with discriminated result types to handle exit, abort, and timeout in a single expression:
+Combine `Effect.raceAll` with discriminated result types to handle successful exit, abort, and timeout in a single expression. `raceAll` waits for the first success, so turn exit observation into an `Exit` value to preserve a failed exit-code read rather than hiding it behind the timeout:
 
+<!-- typecheck -->
 ```typescript
-import { Effect } from 'effect';
-
-const exit =
-	yield*
-	Effect.raceAll([
+import { Duration, Effect } from 'effect';
+import { ChildProcessSpawner } from 'effect/process';
+
+declare const fromAbortSignal: (signal: AbortSignal) => Effect.Effect<void>;
+
+// Call within the scope that owns the handle and its output reader.
+const awaitOutcome = Effect.fn('Process.awaitOutcome')(function* (
+	handle: ChildProcessSpawner.ChildProcessHandle,
+	signal: AbortSignal,
+	timeout: Duration.Input
+) {
+	const exit = yield* Effect.raceAll([
 		handle.exitCode.pipe(
-			Effect.map((code) => ({ kind: 'exit' as const, code }))
+			Effect.exit,
+			Effect.map((result) => ({ kind: 'exit' as const, result }))
 		),
 		fromAbortSignal(signal).pipe(
 			Effect.map(() => ({ kind: 'abort' as const }))
@@ -669,11 +716,15 @@ const exit =
 			Effect.map(() => ({ kind: 'timeout' as const }))
 		)
 	]);
-if (exit.kind !== 'exit') {
-	yield* handle.kill({ forceKillAfter: '3 seconds' });
-}
+	if (exit.kind !== 'exit') {
+		yield* handle.kill({ forceKillAfter: '3 seconds' });
+	}
+	return exit;
+});
 ```
 
+Handle `exit.result` with `Exit.match` when `kind === 'exit'`; it includes observation failures. This race only chooses the control outcome: drain/join any output reader separately within the owning scope before returning captured output.
+
 ## Related Skills
 
 - **effect-platform-abstraction**: FileSystem, Path, and other platform services