fix(effect): withTempDirectory reproduces the try/finally rm contract exactly

A scope finalizer cannot fail typed, so a cleanup error (EACCES, EBUSY)
surfaced as the PlatformError wrapper after orDie, and when the operation
had failed too Cause.squash preferred the operation's failure where the
former throwing finally reported the cleanup error. withTempDirectory is
a bracket: makeTempDirectory, Effect.exit(use), rm({ recursive, force })
on the typed error channel, then the operation's exit; uninterruptible
around the cleanup. Tests cover both cleanup-failure orders over
FileSystem.layerNoop and cleanup on interruption.

Author: ScriptedAlchemy

docs/effect-conventions.md

@@ -237,13 +237,16 @@ contract).
   modules. `fromFileUrl` fails with `BadArgument`; `Effect.orDie` it when the
   URL is built from `import.meta.url`.
 - Temporary directories whose lifetime ends with the enclosing operation:
-  a scoped temp directory inside `Effect.scoped`, replacing `mkdtemp` +
-  `try`/`finally` `rm`. In `agent-bundle` use `scopedTempDirectory` from
-  `src/effect/platform.ts`, not `fs.makeTempDirectoryScoped` directly: the
-  rc.112 finalizer removes without `force`, so an operation that deletes its
-  own staging directory would die with ENOENT at scope close, where the old
-  `rm(dir, { recursive: true, force: true })` succeeded. Tests may use
-  `makeTempDirectoryScoped` (nothing removes the fixture underneath them).
+  in `agent-bundle`, `withTempDirectory(options, use)` from
+  `src/effect/platform.ts`, the bracket that reproduces `mkdtemp` +
+  `try`/`finally` `rm(dir, { recursive: true, force: true })` exactly —
+  `force`, cleanup failure as a typed `PlatformError` that wins over the
+  operation's failure, cleanup on interruption. Not
+  `fs.makeTempDirectoryScoped` in library code: the rc.112 finalizer removes
+  without `force` and `orDie`s, so an operation that deleted its own staging
+  directory would fail an already successful call, and a real cleanup error
+  would surface as the `PlatformError` wrapper (scope finalizers cannot fail
+  typed). Tests may use `makeTempDirectoryScoped` for fixtures.
   **Not** when ownership of the directory is
   transferred to a longer-lived object (the MCP session plugin-data dir in
   `dev/mcp-session/mcp-session-service.ts`): a scoped temp is removed when
@@ -307,16 +310,16 @@ provides `NodeServices.layer` once. Measured on rc.112 (bundled by Rslib,
 the bundle.
 
 `packages/agent-bundle/src/effect/platform.ts` owns the framework's platform
-layer: `platformLayer` (= `NodeServices.layer`), `scopedTempDirectory`,
+layer: `platformLayer` (= `NodeServices.layer`), `withTempDirectory`,
 `unwrapPlatformError`, and `runWithPlatform`, which provides the layer and unwraps `PlatformError`
 before handing off to `boundary.ts`'s `runPromise`. It is the only module
 that imports `effect/PlatformError`: `boundary.ts` is bundled into every
 emitted hook wrapper, and the error class would drag `Data.TaggedError` into
 each one (measured: +12 kB per hook). Phase-1 callers are the throwaway
 artifact in `api.ts` (`listMcp` / `invokeMcp` / `runMcp` / `listHooks` /
 `simulateHook` without `artifact`) and the Codex validator's
-schema-generation directory, both `scopedTempDirectory` (the `force: true`
-finalizer) inside `Effect.scoped`. Emitted artifacts, hook wrappers, and compiler hot paths
+schema-generation directory, both through `withTempDirectory`. Emitted
+artifacts, hook wrappers, and compiler hot paths
 never import this module; the dev server picks it up in phase 2 through
 `makeScopedEffectRuntime(platformLayer)`.
 

packages/agent-bundle/src/api.ts

@@ -166,7 +166,7 @@ import {
 // Imported after the service modules on purpose: the position of
 // `effect/lift.ts` in the module graph fixes its position in the emitted
 // hook bundles, and this order keeps those bundles byte-identical.
-import { runWithPlatform, scopedTempDirectory } from './effect/platform.ts';
+import { runWithPlatform, withTempDirectory } from './effect/platform.ts';
 import { liftPromise } from './effect/lift.ts';
 
 export {
@@ -575,25 +575,24 @@ const temporaryArtifact = async <Result>(
 ): Promise<Result> => {
   if (options.artifact !== undefined) return operation(resolve(options.artifact));
 
-  // The staging directory lives exactly as long as the scope: created next
-  // to the project (same filesystem as a real `artifact/`), removed when the
-  // build or the operation settles, success or failure.
-  return runWithPlatform(Effect.scoped(Effect.gen(function* () {
-    const artifact = yield* scopedTempDirectory({
-      directory: resolve(options.root),
-      prefix: '.agent-bundle-artifact-',
-    });
-    yield* liftPromise(() => build({
-      configPath: options.configPath,
-      logger: options.logger,
-      mode: options.mode,
-      output: artifact,
-      registry: options.registry,
-      root: options.root,
-      targets: options.targets,
-    }));
-    return yield* liftPromise(() => operation(artifact));
-  })));
+  // The staging directory lives exactly as long as the operation: created
+  // next to the project (same filesystem as a real `artifact/`), removed
+  // when the build or the operation settles, success, failure or interrupt.
+  return runWithPlatform(withTempDirectory(
+    { directory: resolve(options.root), prefix: '.agent-bundle-artifact-' },
+    (artifact) => Effect.gen(function* () {
+      yield* liftPromise(() => build({
+        configPath: options.configPath,
+        logger: options.logger,
+        mode: options.mode,
+        output: artifact,
+        registry: options.registry,
+        root: options.root,
+        targets: options.targets,
+      }));
+      return yield* liftPromise(() => operation(artifact));
+    }),
+  ));
 };
 
 type HostValidatedTarget = 'claude' | 'codex' | 'cursor' | 'plugin' | 'portable';

packages/agent-bundle/src/effect/platform.ts

@@ -1,5 +1,5 @@
 import * as NodeServices from '@effect/platform-node/NodeServices';
-import { Effect, FileSystem, type Layer, type Scope } from 'effect';
+import { Effect, FileSystem, type Layer } from 'effect';
 import { PlatformError } from 'effect/PlatformError';
 
 import { runPromise, type RunPromiseOptions } from './boundary.ts';
@@ -37,25 +37,35 @@ export const unwrapPlatformError = <E>(error: E): Exclude<E, PlatformError> | Er
     : (error as Exclude<E, PlatformError>);
 
 /**
- * A temporary directory that lives exactly as long as the enclosing scope,
- * with the `rm(dir, { recursive: true, force: true })` finalizer the
- * `try`/`finally` sites had before they moved onto Effect. rc.112's own
- * `makeTempDirectoryScoped` finalizes without `force`, so an operation that
- * removes (or renames away) its own staging directory would die with ENOENT
- * at scope close and reject a call that had already succeeded. A finalizer
- * failure other than "already gone" is still a defect, as the `finally`
- * throw was.
+ * `const dir = await mkdtemp(...); try { return await use(dir) } finally
+ * { await rm(dir, { recursive: true, force: true }) }` as an Effect, with
+ * the same contract the two `try`/`finally` sites had before they moved
+ * onto Effect:
+ *
+ * - `force: true` — an operation that removed (or renamed away) its own
+ *   staging directory does not fail the call;
+ * - the cleanup failure is a typed `PlatformError` on the error channel
+ *   (unwrapped to its Node cause by `runWithPlatform`), and when both the
+ *   operation and the cleanup fail the cleanup error wins, as a throwing
+ *   `finally` did;
+ * - cleanup runs on interruption as well, uninterruptibly.
+ *
+ * Not `fs.makeTempDirectoryScoped`: in rc.112 its finalizer removes without
+ * `force` and `orDie`s, so a missing directory would reject an already
+ * successful call, and an `EACCES` would surface as the `PlatformError`
+ * wrapper (scope finalizers cannot fail typed).
  */
-export const scopedTempDirectory = (
-  options?: { readonly directory?: string; readonly prefix?: string },
-): Effect.Effect<string, PlatformError, FileSystem.FileSystem | Scope.Scope> =>
-  Effect.gen(function* () {
+export const withTempDirectory = <A, E, R>(
+  options: { readonly directory?: string; readonly prefix?: string } | undefined,
+  use: (directory: string) => Effect.Effect<A, E, R>,
+): Effect.Effect<A, E | PlatformError, R | FileSystem.FileSystem> =>
+  Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
-    return yield* Effect.acquireRelease(
-      fs.makeTempDirectory(options),
-      (directory) => Effect.orDie(fs.remove(directory, { force: true, recursive: true })),
-    );
-  });
+    const directory = yield* fs.makeTempDirectory(options);
+    const exit = yield* Effect.exit(restore(use(directory)));
+    yield* fs.remove(directory, { force: true, recursive: true });
+    return yield* exit;
+  }));
 
 /**
  * Run a platform-dependent Effect program at a Promise edge. Same failure

packages/agent-bundle/src/host-contracts/codex-plugin-validation.ts

@@ -26,7 +26,7 @@ import {
 // Imported last on purpose: see the matching note in `src/api.ts` — the
 // position of `effect/lift.ts` in the module graph keeps the emitted hook
 // bundles byte-identical.
-import { runWithPlatform, scopedTempDirectory } from '../effect/platform.ts';
+import { runWithPlatform, withTempDirectory } from '../effect/platform.ts';
 import { liftPromise } from '../effect/lift.ts';
 
 const maximumOutputBytes = 1024 * 1024;
@@ -261,10 +261,10 @@ const schemaVerbUnavailable = (output: string): boolean =>
   /(?:unrecognized|unknown|invalid) (?:subcommand|command)|no such (?:subcommand|command)/iu.test(output);
 
 /**
- * Runs the live schema generator into a scoped temp directory and compares
+ * Runs the live schema generator into a temporary directory and compares
  * its output with the pinned revision. Every generator failure is reported
  * as a diagnostic (AB6033 / AB6031), never thrown; the directory is removed
- * when the scope closes, whichever way the program settles.
+ * whichever way the program settles.
  */
 const schemaGenerationDiagnostics = (
   options: Readonly<{
@@ -275,67 +275,69 @@ const schemaGenerationDiagnostics = (
     readonly target: string;
     readonly version: string | undefined;
   }>,
-): Effect.Effect<readonly Diagnostic[], PlatformError, FileSystem.FileSystem> => Effect.scoped(Effect.gen(function* () {
-  const outputDirectory = yield* scopedTempDirectory({ prefix: 'agent-bundle-codex-schema-' });
-  const started = yield* liftPromise(() => options.run(Object.freeze({
-    args: Object.freeze(['app-server', 'generate-json-schema', '--out', outputDirectory]),
-    cwd: options.cwd,
-    executable: options.executable,
-  }))).pipe(Effect.option);
-  if (Option.isNone(started)) {
-    return freezeDiagnostics([diagnostic(
-      'AB6033',
-      'Codex CLI schema generation could not be started.',
-      'error',
-      options.target,
-      'Verify the Codex CLI starts and supports app-server schema generation, then rerun artifact validation.',
-    )]);
-  }
-  const result: CodexPluginCommandResult = started.value;
+): Effect.Effect<readonly Diagnostic[], PlatformError, FileSystem.FileSystem> => withTempDirectory(
+  { prefix: 'agent-bundle-codex-schema-' },
+  (outputDirectory) => Effect.gen(function* () {
+    const started = yield* liftPromise(() => options.run(Object.freeze({
+      args: Object.freeze(['app-server', 'generate-json-schema', '--out', outputDirectory]),
+      cwd: options.cwd,
+      executable: options.executable,
+    }))).pipe(Effect.option);
+    if (Option.isNone(started)) {
+      return freezeDiagnostics([diagnostic(
+        'AB6033',
+        'Codex CLI schema generation could not be started.',
+        'error',
+        options.target,
+        'Verify the Codex CLI starts and supports app-server schema generation, then rerun artifact validation.',
+      )]);
+    }
+    const result: CodexPluginCommandResult = started.value;
 
-  if (result.termination !== undefined) {
-    return freezeDiagnostics([diagnostic(
-      'AB6033',
-      commandFailureMessage('schema generation', result),
-      'error',
-      options.target,
-      'Rerun Codex schema generation within the configured time and output bounds.',
-    )]);
-  }
-  if (result.exitCode !== 0) {
-    const output = `${result.stdout}\n${result.stderr}`;
-    if (schemaVerbUnavailable(output)) {
+    if (result.termination !== undefined) {
       return freezeDiagnostics([diagnostic(
-        'AB6031',
-        `The Codex ${options.version ?? 'unknown'} app-server generate-json-schema verb is unavailable; ` +
-          `live schema drift could not be checked against pinned Codex ${pinnedRevision}.`,
-        'info',
+        'AB6033',
+        commandFailureMessage('schema generation', result),
+        'error',
         options.target,
-        'Use a Codex release that publishes app-server schema generation, or retain validation against the vendored pinned schemas.',
+        'Rerun Codex schema generation within the configured time and output bounds.',
       )]);
     }
-    return freezeDiagnostics([diagnostic(
+    if (result.exitCode !== 0) {
+      const output = `${result.stdout}\n${result.stderr}`;
+      if (schemaVerbUnavailable(output)) {
+        return freezeDiagnostics([diagnostic(
+          'AB6031',
+          `The Codex ${options.version ?? 'unknown'} app-server generate-json-schema verb is unavailable; ` +
+            `live schema drift could not be checked against pinned Codex ${pinnedRevision}.`,
+          'info',
+          options.target,
+          'Use a Codex release that publishes app-server schema generation, or retain validation against the vendored pinned schemas.',
+        )]);
+      }
+      return freezeDiagnostics([diagnostic(
+        'AB6033',
+        commandFailureMessage('schema generation', result),
+        'error',
+        options.target,
+        'Run `codex app-server generate-json-schema --out <dir>` successfully, then rerun artifact validation.',
+      )]);
+    }
+
+    return yield* liftPromise(() => compareGeneratedSchemas(
+      outputDirectory,
+      options.version,
+      options.strict,
+      options.target,
+    )).pipe(Effect.catch(() => Effect.succeed(freezeDiagnostics([diagnostic(
       'AB6033',
-      commandFailureMessage('schema generation', result),
+      'Codex CLI generated schema output could not be inspected.',
       'error',
       options.target,
-      'Run `codex app-server generate-json-schema --out <dir>` successfully, then rerun artifact validation.',
-    )]);
-  }
-
-  return yield* liftPromise(() => compareGeneratedSchemas(
-    outputDirectory,
-    options.version,
-    options.strict,
-    options.target,
-  )).pipe(Effect.catch(() => Effect.succeed(freezeDiagnostics([diagnostic(
-    'AB6033',
-    'Codex CLI generated schema output could not be inspected.',
-    'error',
-    options.target,
-    'Ensure the generated schema directory is readable, then rerun artifact validation.',
-  )]))));
-}));
+      'Ensure the generated schema directory is readable, then rerun artifact validation.',
+    )]))));
+  }),
+);
 
 export const validateCodexPlugin = async (
   options: ValidateCodexPluginOptions,