orizu 0.5.48 → 0.5.49

package/src/index.ts

@@ -100,7 +100,6 @@ import {
   getTaskReport,
   updateTaskStatus,
 } from './task-commands.js'
-import { cleanupAll, throwWithCleanup } from './cleanup.js'
 import {
   extractFlagValue,
   verifyGepaRunnerDirsFromArgs,
@@ -177,7 +176,6 @@ import { inspectExistingWorkspaceTeam, getWorkspaceRoot } from './workspace.js'
 import { writeLastErrorRecord, extractLastErrorCode } from './last-error-record.js'
 import type { CliLengthStats, CliLengthMeasurementUnavailableReason } from './prompt-length-wire.js'
 import type { RunnerInstructionSet } from './runner-instruction-set-contract.js'
-import type { GepaVerifiedArgs } from './runner-dir-verify.js'
 import type { ReportCommentsCliContext } from './report-comments-cli.js'
 
 
@@ -1293,101 +1291,94 @@ const GEPA_RUNNER_MATERIALIZATION_PAIRS = [
   { versionFlag: '--scorer-runner-version-id', dirFlag: '--scorer-runner-dir' },
 ] as const
 
-async function materializeMissingGepaRunnerDirs(args: string[]): Promise<{
-  args: string[]
-  cleanup: () => void
-}> {
-  const rewritten = [...args]
-  const cleanups: Array<() => void> = []
-  const cleanup = () => cleanupAll(
-    cleanups,
-    'Failed to clean materialized runner directories'
-  )
-
-  try {
-    for (const pair of GEPA_RUNNER_MATERIALIZATION_PAIRS) {
-      const runnerVersionId = extractFlagValue(rewritten, pair.versionFlag)
-      const runnerDir = extractFlagValue(rewritten, pair.dirFlag)
-      if (!runnerVersionId || runnerDir) continue
-
-      const materialized = await materializeRunnerVersion(runnerVersionId)
-      cleanups.push(materialized.cleanup)
-      rewritten.push(pair.dirFlag, materialized.runnerDir)
-    }
-  } catch (error) {
-    throwWithCleanup(
-      error,
-      cleanups,
-      'Runner materialization failed and cleanup also failed'
-    )
-  }
-
-  return { args: rewritten, cleanup }
-}
-
 async function runGepaOptimization() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const baseUrl = getBaseUrl()
   const runGepa = getGepaPythonCommand(cliArgs.slice(2), process.env)
   const python = runGepa.python
-  let forwardedArgs = runGepa.args
-  // ALI-1159 (ADR-007): GEPA executes ad-hoc local runner dirs while
-  // attributing records to registered runner version ids — verify the bytes
-  // ARE those versions before the optimizer spawns. Scans the forwarded argv
-  // itself (both argparse flag forms), fail-closed on half-populated pairs,
-  // and REWRITES the dir flags to verified snapshots (the exact hashed bytes)
-  // so a post-hash mutation of the original dirs cannot change what runs.
-  const materialized = await materializeMissingGepaRunnerDirs(forwardedArgs)
-  let verified: GepaVerifiedArgs | undefined
+  // ORI-2429: one Effect scope owns every runner copy this run writes to the
+  // temp folder; it removes them on success, failure and stop signals.
+  const { Effect } = await import('effect')
+  const { downloadedRunner, heldUntilClose, RemovalLedger, runStoppable } = await import('./runner-folders.js')
+  const ledger = new RemovalLedger()
+  // Which step failed decides the message when a removal also failed, as before.
+  let phase: 'materialize' | 'launch' = 'materialize'
   let selectedEngine = 'official'
+  let failure: { error: unknown } | undefined
   try {
-    verified = await verifyGepaRunnerDirsFromArgs(materialized.args)
-    forwardedArgs = verified.args
-    // Uniform resolution (ALI-1090): honors ORIZU_TOKEN / ORIZU_TOKEN_FILE before
-    // credentials.json so hosted sandboxes can run optimizations. Read at spawn
-    // time — AFTER the verification awaits above, so a hosted token-file
-    // rotation crossing the hash + lookup round-trips cannot hand the child a
-    // stale bearer.
-    const token = resolveAuthTokenForBaseUrl(baseUrl)
-    if (!forwardedArgs.includes('--project')) {
-      forwardedArgs = ['--project', project, ...forwardedArgs]
-    }
-    const dispatch = applyHostedInstructionSetProfileOverride(dispatchGepaEngine(forwardedArgs, project, {
-      ...process.env,
-      ORIZU_API_URL: baseUrl,
-      ORIZU_TOKEN: token,
-      ORIZU_PROJECT: project,
-      ORIZU_VERIFIED_RUNNER_DIRS: JSON.stringify(verified.verifiedDirs),
-      PYTHONPATH: getGepaPythonPathEntries(process.env.PYTHONPATH).join(delimiter),
-      PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
+    await runStoppable(stop => Effect.gen(function* () {
+      // Download registered runner versions passed without a local folder; the
+      // verification below then checks those bytes like any local folder.
+      const materializedArgs = [...runGepa.args]
+      for (const pair of GEPA_RUNNER_MATERIALIZATION_PAIRS) {
+        const runnerVersionId = extractFlagValue(materializedArgs, pair.versionFlag)
+        const runnerDir = extractFlagValue(materializedArgs, pair.dirFlag)
+        if (!runnerVersionId || runnerDir) continue
+        const materialized = yield* downloadedRunner(runnerVersionId, ledger, false)
+        materializedArgs.push(pair.dirFlag, materialized.runnerDir)
+      }
+      phase = 'launch'
+      // ALI-1159 (ADR-007): GEPA executes ad-hoc local runner dirs while
+      // attributing records to registered runner version ids — verify the bytes
+      // ARE those versions before the optimizer spawns. Scans the forwarded argv
+      // itself (both argparse flag forms), fail-closed on half-populated pairs,
+      // and REWRITES the dir flags to verified snapshots (the exact hashed bytes)
+      // so a post-hash mutation of the original dirs cannot change what runs.
+      const verified = yield* heldUntilClose(ledger, 'snapshots', () => verifyGepaRunnerDirsFromArgs(materializedArgs))
+      let forwardedArgs = verified.args
+      // Uniform resolution (ALI-1090): honors ORIZU_TOKEN / ORIZU_TOKEN_FILE before
+      // credentials.json so hosted sandboxes can run optimizations. Read at spawn
+      // time — AFTER the verification awaits above, so a hosted token-file
+      // rotation crossing the hash + lookup round-trips cannot hand the child a
+      // stale bearer.
+      const token = resolveAuthTokenForBaseUrl(baseUrl)
+      if (!forwardedArgs.includes('--project')) {
+        forwardedArgs = ['--project', project, ...forwardedArgs]
+      }
+      const dispatch = applyHostedInstructionSetProfileOverride(dispatchGepaEngine(forwardedArgs, project, {
+        ...process.env,
+        ORIZU_API_URL: baseUrl,
+        ORIZU_TOKEN: token,
+        ORIZU_PROJECT: project,
+        ORIZU_VERIFIED_RUNNER_DIRS: JSON.stringify(verified.verifiedDirs),
+        PYTHONPATH: getGepaPythonPathEntries(process.env.PYTHONPATH).join(delimiter),
+        PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
+      }))
+      const instructionSetProfileVersionId = yield* Effect.tryPromise({
+        try: () => resolveGepaSeedFromEnvironment(dispatch.environment, project, 'production'),
+        catch: error => error,
+      })
+      if (instructionSetProfileVersionId) dispatch.environment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID = instructionSetProfileVersionId
+      selectedEngine = dispatch.engine
+      const launch = prepareSkilledProposerLaunch(python, dispatch.engine, dispatch.environment)
+      // While the optimizer runs, the launcher owns stop signals (ORI-2402) and
+      // closes this scope just before the CLI ends by the signal. Taken in the
+      // same step as the launch, so no stop can fall between the two.
+      const result = yield* Effect.tryPromise({
+        try: () => (stop.launcherOwnsStop(), spawnSkilledProposerChild(
+          launch.python, ['-m', dispatch.module, ...dispatch.args], dispatch.engine, launch.environment,
+          undefined, undefined, { beforeSignalExit: stop.beforeSignalExit },
+        )),
+        catch: error => error,
+      }).pipe(Effect.ensuring(Effect.sync(stop.launcherDone)))
+      if (result.error) {
+        return yield* Effect.fail(new Error(`${selectedEngine} GEPA engine failed: ${result.error.message}`, { cause: result.error }))
+      }
+      if (result.status !== 0) {
+        return yield* Effect.fail(new Error(`${selectedEngine} GEPA engine failed with exit code ${result.status}`))
+      }
     }))
-    const instructionSetProfileVersionId = await resolveGepaSeedFromEnvironment(dispatch.environment, project, 'production')
-    if (instructionSetProfileVersionId) dispatch.environment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID = instructionSetProfileVersionId
-    selectedEngine = dispatch.engine
-    const launch = prepareSkilledProposerLaunch(python, dispatch.engine, dispatch.environment)
-    const result = await spawnSkilledProposerChild(
-      launch.python, ['-m', dispatch.module, ...dispatch.args], dispatch.engine, launch.environment,
-    )
-    if (result.error) {
-      throw new Error(`${selectedEngine} GEPA engine failed: ${result.error.message}`, { cause: result.error })
-    }
-    if (result.status !== 0) {
-      throw new Error(`${selectedEngine} GEPA engine failed with exit code ${result.status}`)
-    }
   } catch (error) {
-    throwWithCleanup(
-      error,
-      [
-        ...(verified ? [verified.cleanup] : []),
-        materialized.cleanup,
-      ],
-      'GEPA launch failed and runner cleanup also failed'
-    )
+    failure = { error }
   }
-  cleanupAll(
-    [verified.cleanup, materialized.cleanup],
-    'Failed to clean GEPA runner directories'
-  )
+  // The scope has closed here; a removal failure decides the message, as before.
+  if (ledger.has()) {
+    if (!failure) throw new AggregateError(ledger.errors(), 'Failed to clean GEPA runner directories')
+    throw new AggregateError([failure.error, ...ledger.errors()], phase === 'materialize'
+      ? 'Runner materialization failed and cleanup also failed'
+      : 'GEPA launch failed and runner cleanup also failed')
+  }
+  if (failure) throw failure.error
   if (hasJsonFlag()) {
     printJson({ status: 'completed', exitCode: 0 })
   }
@@ -2256,6 +2247,7 @@ function isCliEntrypoint(): boolean {
 if (isCliEntrypoint()) {
   const rawArgs = process.argv.slice(2)
   withPassiveUpdateNotice(rawArgs, getCliVersion, printError, args =>
+    // ORI-2429: the process-boundary adapter stays a Promise (ADR-038 guide); the record write is Effect-owned and never replaces this error.
     main(args).catch(async error => {
       const message = error instanceof Error ? error.message : 'Unknown error'
       // The reporter email is unknown on the failure path, so the record masks every address.

package/src/runner-folders.ts

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Cause, Effect, Exit, Fiber, Scope } from 'effect'
+
+import { ARTIFACT_MAX_BYTES } from './artifact-pull.js'
+import { authedFetch } from './http.js'
+import { unzipRunnerArchive } from './runner-version-materialization.js'
+
+// ORI-2429: Effect owns the lifetime of the runner copies the CLI writes to
+// the temp folder (downloaded runner versions and verified snapshots). They
+// hold the customer's runner code, so the scope removes them however the run
+// ends: success, failure or a stop signal. Loaded with a dynamic import, so
+// commands that never copy a runner do not load Effect.
+
+export type RemovalGroup = 'downloads' | 'snapshots' | 'other'
+
+/** Removal failures seen while a scope closes; Effect finalizers cannot fail. */
+export class RemovalLedger {
+  readonly failures: { group: RemovalGroup; error: unknown }[] = []
+  has(group?: RemovalGroup): boolean {
+    return this.failures.some(failure => !group || failure.group === group)
+  }
+  errors(): unknown[] {
+    return this.failures.map(failure => failure.error)
+  }
+}
+
+/** Remove with `remove` when the surrounding scope closes, recording a failure. */
+export function removeOnClose(ledger: RemovalLedger, group: RemovalGroup, remove: () => void) {
+  return Effect.addFinalizer(() => Effect.sync(() => {
+    try { remove() } catch (error) { ledger.failures.push({ group, error }) }
+  }))
+}
+
+function request(path: string, signal: AbortSignal) {
+  return Effect.tryPromise({
+    try: requestSignal => authedFetch(path, { signal: AbortSignal.any([requestSignal, signal]) }),
+    catch: error => error,
+  })
+}
+
+function text(response: Response) {
+  return Effect.tryPromise({ try: () => response.text(), catch: error => error })
+}
+
+/**
+ * Download a registered runner version into a private temp folder that the
+ * caller's scope removes. A stop mid-download aborts the transfer and still
+ * removes the folder. Messages match the previous Promise implementation.
+ */
+export function downloadedRunner(runnerVersionId: string, ledger: RemovalLedger, verifyRegisteredDigest = true) {
+  return Effect.gen(function* () {
+    // Aborting on close also ends a body still streaming when a stop arrives.
+    const controller = yield* Effect.acquireRelease(
+      Effect.sync(() => new AbortController()),
+      controller => Effect.sync(() => controller.abort()),
+    )
+    let contentSha256: string | undefined
+    if (verifyRegisteredDigest) {
+      const detailResponse = yield* request(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}`, controller.signal)
+      if (!detailResponse.ok) return yield* Effect.fail(new Error(`Failed to resolve runner version: ${yield* text(detailResponse)}`))
+      const detail = (yield* Effect.tryPromise({ try: () => detailResponse.json(), catch: error => error })) as Record<string, unknown>
+      if (detail.runnerVersionId !== runnerVersionId || detail.status !== 'sealed'
+        || typeof detail.contentSha256 !== 'string' || !/^[0-9a-f]{64}$/u.test(detail.contentSha256)) {
+        return yield* Effect.fail(new Error('Runner version detail is invalid'))
+      }
+      contentSha256 = detail.contentSha256
+    }
+    const response = yield* request(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}/download`, controller.signal)
+    if (!response.ok) return yield* Effect.fail(new Error(`Failed to download runner version: ${yield* text(response)}`))
+    // The previous implementation removed the folder as soon as this runner
+    // failed, naming the runner when that removal failed too. Keep both.
+    let removed = false
+    let tempDir = ''
+    const remove = () => { if (!removed) { removed = true; rmSync(tempDir, { recursive: true, force: true }) } }
+    // Created and registered for removal in one uninterruptible step.
+    yield* Effect.acquireRelease(
+      Effect.sync(() => { tempDir = mkdtempSync(join(tmpdir(), 'orizu-runner-version-')) }),
+      () => Effect.sync(() => {
+        try { remove() } catch (error) { ledger.failures.push({ group: 'downloads', error }) }
+      }),
+    )
+    return yield* Effect.gen(function* () {
+      const zipBytes = new Uint8Array(yield* Effect.tryPromise({ try: () => response.arrayBuffer(), catch: error => error }))
+      if (zipBytes.byteLength > ARTIFACT_MAX_BYTES) return yield* Effect.fail(new Error(`Runner artifact exceeds ${ARTIFACT_MAX_BYTES} bytes`))
+      if (contentSha256 && createHash('sha256').update(zipBytes).digest('hex') !== contentSha256) {
+        return yield* Effect.fail(new Error('Runner artifact digest mismatch'))
+      }
+      const zipPath = join(tempDir, 'runner.zip'), runnerDir = join(tempDir, 'runner')
+      yield* Effect.try({ try: () => { writeFileSync(zipPath, zipBytes); unzipRunnerArchive(zipPath, runnerDir) }, catch: error => error })
+      return { runnerDir, remove }
+    }).pipe(Effect.catch(error => Effect.suspend(() => {
+      try { remove() } catch (cleanupError) {
+        return Effect.fail(new AggregateError([error, cleanupError], `Runner ${runnerVersionId} materialization failed and cleanup also failed`))
+      }
+      return Effect.fail(error)
+    })))
+  })
+}
+
+/** A Promise-returning resource (acquired whole) whose cleanup the scope runs. */
+export function heldUntilClose<A extends { cleanup: () => void }>(ledger: RemovalLedger, group: RemovalGroup, acquire: () => Promise<A>) {
+  // Acquiring stays uninterruptible: a stop waits for it to finish, so a
+  // half-created snapshot is never orphaned; the scope then removes it.
+  return Effect.acquireRelease(
+    Effect.tryPromise({ try: acquire, catch: error => error }),
+    resource => Effect.sync(() => {
+      try { resource.cleanup() } catch (error) { ledger.failures.push({ group, error }) }
+    }),
+  )
+}
+
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'] as const
+// Matches the launcher's stop cap (ORI-2402): a stop never waits longer.
+const STOP_CLEANUP_WAIT_MS = 15_000
+
+export interface StopControl {
+  /** Hand stop signals to the optimizer launcher; pass this as its beforeSignalExit. */
+  readonly beforeSignalExit: () => Promise<void> | void
+  readonly launcherOwnsStop: () => void
+  readonly launcherDone: () => void
+}
+
+/**
+ * Run `program` in a scope that removes the runner copies however it ends.
+ * Before the optimizer starts, a stop signal interrupts the program (the scope
+ * closes as it unwinds) and the CLI then ends by that signal. While the
+ * launcher runs the optimizer, the launcher owns the signal and calls
+ * `beforeSignalExit`, which closes the scope synchronously: the removal then
+ * finishes even when the optimizer used up the whole stop cap.
+ */
+export async function runStoppable<A>(program: (stop: StopControl) => Effect.Effect<A, unknown, Scope.Scope>): Promise<A> {
+  const { scope, close } = openScope()
+  let launcherOwned = false
+  let stopping = false
+  // eslint-disable-next-line prefer-const -- assigned after the handlers that read it
+  let fiber: Fiber.Fiber<A, unknown>
+  const interrupt = () => Effect.runPromise(Fiber.interrupt(fiber))
+  const removeHandlers = () => { for (const entry of handlers) process.off(entry.signal, entry.handle) }
+  const handlers = STOP_SIGNALS.map(signal => ({
+    signal,
+    handle: () => {
+      if (launcherOwned || stopping) return
+      stopping = true
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const expired = new Promise<void>(resolve => { timer = setTimeout(resolve, STOP_CLEANUP_WAIT_MS) })
+      void Promise.race([interrupt(), expired]).finally(() => {
+        clearTimeout(timer)
+        removeHandlers()
+        process.kill(process.pid, signal)
+      })
+    },
+  }))
+  const control: StopControl = {
+    beforeSignalExit: () => {
+      stopping = true
+      // The launcher re-sends the signal next; none of ours may catch it.
+      removeHandlers()
+      close()
+    },
+    launcherOwnsStop: () => { launcherOwned = true },
+    launcherDone: () => { launcherOwned = false },
+  }
+  for (const entry of handlers) process.on(entry.signal, entry.handle)
+  fiber = Effect.runFork(Scope.provide(scope)(program(control)).pipe(Effect.ensuring(Effect.sync(close))))
+  try {
+    const exit = await Effect.runPromise(Effect.exit(Fiber.join(fiber)))
+    // A stop ends the process by its signal; nothing more to report here.
+    if (stopping) return await new Promise<never>(() => {})
+    if (Exit.isSuccess(exit)) return exit.value
+    throw Cause.squash(exit.cause)
+  } finally {
+    removeHandlers()
+  }
+}
+
+/**
+ * For a workflow that stays a Promise (hosted optimization): a scope that a
+ * stop signal closes before the CLI ends by that signal. Before the optimizer
+ * starts our handlers do it; while the launcher runs it, the launcher calls
+ * `stop.beforeSignalExit`. Closing aborts an in-flight download and removes
+ * every registered file, folder and server; the finalizers are synchronous.
+ */
+export function stopClosesScope() {
+  const { scope, close } = openScope()
+  let launcherOwned = false
+  let stopping = false
+  const removeHandlers = () => { for (const entry of handlers) process.off(entry.signal, entry.handle) }
+  const handlers = STOP_SIGNALS.map(signal => ({
+    signal,
+    handle: () => {
+      if (launcherOwned || stopping) return
+      stopping = true
+      close()
+      removeHandlers()
+      process.kill(process.pid, signal)
+    },
+  }))
+  // Installed by the caller inside its try, so a setup throw cannot leave them behind.
+  const listen = () => { for (const entry of handlers) process.on(entry.signal, entry.handle) }
+  const stop: StopControl = {
+    beforeSignalExit: () => { stopping = true; removeHandlers(); close() },
+    launcherOwnsStop: () => { launcherOwned = true },
+    launcherDone: () => { launcherOwned = false },
+  }
+  return { scope, close, stop, listen, removeHandlers }
+}
+
+/** Open a scope for an adapter that must hand back a synchronous cleanup. */
+export function openScope() {
+  const scope = Scope.makeUnsafe()
+  let closed = false
+  return {
+    scope,
+    close: () => {
+      if (closed) return
+      closed = true
+      Effect.runSync(Scope.close(scope, Exit.void))
+    },
+  }
+}

package/src/runner-version-materialization.ts

@@ -1,13 +1,6 @@
-import { createHash } from 'node:crypto'
 import { spawnSync } from 'node:child_process'
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { ARTIFACT_MAX_BYTES } from './artifact-pull.js'
-import { cleanupAll, throwWithCleanup } from './cleanup.js'
-import { authedFetch } from './http.js'
 import { sanitizeTerminalText } from './json-response.js'
-function unzip(zipPath: string, runnerDir: string): void {
+export function unzipRunnerArchive(zipPath: string, runnerDir: string): void {
   const listing = spawnSync('unzip', ['-Z1', zipPath], { encoding: 'utf8' })
   if (listing.error) throw listing.error
   if (listing.status !== 0) throw new Error(`unzip listing failed: ${sanitizeTerminalText(listing.stderr || listing.stdout || '')}`)
@@ -24,33 +17,27 @@ function unzip(zipPath: string, runnerDir: string): void {
 export async function materializeRunnerVersion(runnerVersionId: string, verifyRegisteredDigest = true): Promise<{
   runnerDir: string; cleanup: () => void
 }> {
-  let contentSha256: string | undefined
-  if (verifyRegisteredDigest) {
-    const detailResponse = await authedFetch(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}`)
-    if (!detailResponse.ok) throw new Error(`Failed to resolve runner version: ${await detailResponse.text()}`)
-    const detail = await detailResponse.json() as Record<string, unknown>
-    if (detail.runnerVersionId !== runnerVersionId || detail.status !== 'sealed'
-      || typeof detail.contentSha256 !== 'string' || !/^[0-9a-f]{64}$/u.test(detail.contentSha256)) {
-      throw new Error('Runner version detail is invalid')
-    }
-    contentSha256 = detail.contentSha256
-  }
-  const response = await authedFetch(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}/download`)
-  if (!response.ok) throw new Error(`Failed to download runner version: ${await response.text()}`)
-  const tempDir = mkdtempSync(join(tmpdir(), 'orizu-runner-version-'))
-  const cleanup = () => rmSync(tempDir, { recursive: true, force: true })
+  // ORI-2429: the download runs on Effect (runner-folders.ts); this adapter
+  // keeps the { runnerDir, cleanup } shape for the existing Promise callers.
+  const { downloadedRunner, openScope, RemovalLedger } = await import('./runner-folders.js')
+  const { Effect, Scope } = await import('effect')
+  const ledger = new RemovalLedger()
+  const { scope, close } = openScope()
   try {
-    const zipBytes = new Uint8Array(await response.arrayBuffer())
-    if (zipBytes.byteLength > ARTIFACT_MAX_BYTES) throw new Error(`Runner artifact exceeds ${ARTIFACT_MAX_BYTES} bytes`)
-    if (contentSha256 && createHash('sha256').update(zipBytes).digest('hex') !== contentSha256) throw new Error('Runner artifact digest mismatch')
-    const zipPath = join(tempDir, 'runner.zip'), runnerDir = join(tempDir, 'runner')
-    writeFileSync(zipPath, zipBytes)
-    unzip(zipPath, runnerDir)
-    return { runnerDir, cleanup }
+    const { runnerDir } = await Effect.runPromise(
+      downloadedRunner(runnerVersionId, ledger, verifyRegisteredDigest).pipe(Effect.provideService(Scope.Scope, scope))
+    )
+    return {
+      runnerDir,
+      cleanup: () => {
+        close()
+        const [failure] = ledger.errors()
+        if (failure !== undefined) throw failure
+      },
+    }
   } catch (error) {
-    throwWithCleanup(error, [cleanup], `Runner ${runnerVersionId} materialization failed and cleanup also failed`)
+    // downloadedRunner already removed this runner's folder on its own failure.
+    close()
+    throw error
   }
 }
-export function cleanupMaterializedRunners(cleanups: Array<() => void>): void {
-  cleanupAll(cleanups, 'Failed to clean materialized runner directories')
-}

package/src/skilled-proposer-launch.ts

@@ -54,6 +54,29 @@ const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'] as const
 // status write); past this it is killed so nothing is left running (ORI-2402).
 const CHILD_STOP_WAIT_MS = 15_000
 
+export interface SkilledProposerStopOptions {
+  /**
+   * Runs once the optimizer has exited after a stop signal, just before the
+   * CLI ends by that signal (ORI-2429: the caller removes its runner copies).
+   * It gets whatever is left of CHILD_STOP_WAIT_MS since the signal; a hook
+   * still running then is abandoned so the stop cannot hang. A synchronous
+   * hook always runs to the end, even with no time left.
+   */
+  beforeSignalExit?: () => Promise<void> | void
+}
+
+// Wait for `hook` at most until `deadline`; its failure never blocks the exit.
+async function runBeforeSignalExit(hook: SkilledProposerStopOptions['beforeSignalExit'], deadline: number): Promise<void> {
+  if (!hook) return
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const expired = new Promise<void>(resolve => { timer = setTimeout(resolve, Math.max(0, deadline - Date.now())) })
+  try {
+    await Promise.race([Promise.resolve().then(hook).catch(() => {}), expired])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 /**
  * Run the optimizer, passing a stop signal on to it. On a stop signal the CLI
  * waits until the optimizer exits (capped at CHILD_STOP_WAIT_MS, then kills
@@ -63,11 +86,13 @@ export async function spawnSkilledProposerChild(
   command: string, args: string[], engine: GepaEngine, environment: NodeJS.ProcessEnv,
   onSpawn?: () => Promise<void>,
   output?: SkilledProposerChildOutput,
+  stopOptions: SkilledProposerStopOptions = {},
 ) {
   const childEnvironment = { ...environment }
   let child: ReturnType<typeof spawn> | PipedChild | undefined
   let cleanup = () => {}
   let stopSignal: NodeJS.Signals | undefined
+  let stopDeadline = 0
   // On the terminal path the optimizer leads its own process group, so a stop
   // also reaches its runners, which may run in worker threads it can't stop.
   let childGroup: number | undefined
@@ -79,10 +104,16 @@ export async function spawnSkilledProposerChild(
   }
   let giveUp: ReturnType<typeof setTimeout> | undefined
   const removeHandlers = () => { for (const entry of handlers) process.off(entry.signal, entry.handle) }
-  const endBySignal = (signal: NodeJS.Signals): Promise<never> => {
+  let ending = false
+  const endBySignal = async (signal: NodeJS.Signals): Promise<never> => {
+    if (ending) return new Promise<never>(() => {})
+    ending = true
     if (giveUp) clearTimeout(giveUp)
-    removeHandlers()
     cleanup()
+    // Our handlers stay installed during the caller's cleanup, so a second
+    // Ctrl-C then is absorbed instead of ending the CLI by default mid-cleanup.
+    await runBeforeSignalExit(stopOptions.beforeSignalExit, stopDeadline)
+    removeHandlers()
     // With our handlers gone, the signal's default action ends the process.
     process.kill(process.pid, signal)
     return new Promise<never>(() => {})
@@ -90,6 +121,7 @@ export async function spawnSkilledProposerChild(
   const handlers = STOP_SIGNALS.map(signal => ({
     signal,
     handle: () => {
+      if (!stopDeadline) stopDeadline = Date.now() + CHILD_STOP_WAIT_MS
       if (!child) { void endBySignal(signal); return }
       forward(signal)
       if (stopSignal) return
@@ -104,6 +136,8 @@ export async function spawnSkilledProposerChild(
   try {
     cleanup = materializeConfigPayload(engine, childEnvironment) ?? cleanup
     await new Promise<void>(resolve => setImmediate(resolve))
+    // A stop before the optimizer starts ends the CLI (endBySignal); never start it then.
+    if (stopDeadline) return await new Promise<never>(() => {})
     let result: { status: number | null, error?: Error }
     if (output) {
       result = await runPipedChild(
@@ -112,7 +146,11 @@ export async function spawnSkilledProposerChild(
         childEnvironment,
         async () => { await onSpawn?.() },
         output,
-        spawnedChild => { child = spawnedChild }
+        spawnedChild => {
+          child = spawnedChild
+          // Stopped while the output sinks were prepared: the CLI is ending.
+          if (stopDeadline && !stopSignal) spawnedChild.kill('SIGKILL')
+        }
       )
     } else {
       // stdin is not passed on: a process outside the terminal's foreground