fix(bg): clean up old completed session artifacts

src/cli/bg.ts

@@ -1043,6 +1043,7 @@ export async function attachHandler(
 
 export async function killHandler(
   args: string[] | string | undefined,
+  options: { retentionSettingsReady?: boolean } = {},
 ): Promise<void> {
   const target = normalizeArgs(args)[0]
   if (!target) fail('Usage: openclaude kill <id-or-name>')
@@ -1054,6 +1055,19 @@ export async function killHandler(
       `Failed to kill background session ${session.id}: ${errorMessage(error)}`,
     )
   })
+  if (options.retentionSettingsReady !== false) {
+    try {
+      const { runBackgroundSessionRetention } = await import(
+        '../utils/cleanup.js'
+      )
+      await runBackgroundSessionRetention({
+        trigger: 'explicit-kill',
+        sessionId: killed.id,
+      })
+    } catch {
+      // A retention failure must not replace the successful kill outcome.
+    }
+  }
   console.log(`Killed background session ${killed.id}.`)
 }
 

src/cli/bgFinalizer.fixture.ts

@@ -1,14 +1,43 @@
 import { writeFile } from 'node:fs/promises'
 import { handleBgFlag } from './bg.js'
-import { prepareBackgroundSessionFinalizer } from './bgFinalizer.js'
+import * as backgroundFinalizer from './bgFinalizer.js'
 import { noteBackgroundSessionTerminationSignal } from '../utils/backgroundSessionTermination.js'
 
 const invocation = process.argv.slice(2)
-if (invocation[0] === 'launcher') {
-  await handleBgFlag(['--bg', invocation[1] ?? 'success'])
+const cleanupWorkerEnv = 'OPENCLAUDE_INTERNAL_BACKGROUND_CLEANUP_WORKER'
+if (process.env[cleanupWorkerEnv] === '1') {
+  const runCleanupWorker = (
+    backgroundFinalizer as typeof backgroundFinalizer & {
+      runBackgroundSessionCleanupWorker?: () => Promise<void>
+    }
+  ).runBackgroundSessionCleanupWorker
+  if (!runCleanupWorker) {
+    throw new Error('background cleanup worker is unavailable')
+  }
+  await runCleanupWorker()
+} else if (invocation[0] === 'launcher') {
+  const name = invocation[2]
+  const originalLog = console.log
+  if (
+    process.env.OPENCLAUDE_BG_FINALIZER_FIXTURE_OUTPUT === 'omit-logs'
+  ) {
+    console.log = (...args: unknown[]) => {
+      if (String(args[0]).startsWith('Logs:')) return
+      originalLog(...args)
+    }
+  }
+  try {
+    await handleBgFlag([
+      '--bg',
+      ...(name ? ['--name', name] : []),
+      invocation[1] ?? 'success',
+    ])
+  } finally {
+    console.log = originalLog
+  }
 } else {
   const mode = invocation.at(-1)
-  await prepareBackgroundSessionFinalizer()
+  await backgroundFinalizer.prepareBackgroundSessionFinalizer()
 
   if (mode === 'throw') {
     throw new Error('intentional background finalizer fixture failure')
@@ -29,7 +58,45 @@ if (invocation[0] === 'launcher') {
     })
   }
   const readyPath = process.env.OPENCLAUDE_BG_FINALIZER_FIXTURE_READY
-  if (readyPath) await writeFile(readyPath, 'ready')
+  if (mode === 'handled-throw') {
+    const releasePath = process.env.OPENCLAUDE_BG_FINALIZER_FIXTURE_RELEASE
+    if (!readyPath || !releasePath) {
+      throw new Error('handled-throw fixture routing is missing')
+    }
+    process.once('uncaughtException', async () => {
+      await writeFile(readyPath, 'ready')
+      const deadline = Date.now() + 5_000
+      while (!(await Bun.file(releasePath).exists())) {
+        if (Date.now() >= deadline) {
+          process.exit(24)
+        }
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      process.exit(23)
+    })
+    queueMicrotask(() => {
+      throw new Error('intentional handled fixture failure')
+    })
+  } else if (
+    readyPath &&
+    process.env.OPENCLAUDE_BG_FINALIZER_FIXTURE_SKIP_READY !== '1'
+  ) {
+    await writeFile(readyPath, 'ready')
+  }
+  if (mode === 'controlled' || mode === 'controlled-exit') {
+    const releasePath = process.env.OPENCLAUDE_BG_FINALIZER_FIXTURE_RELEASE
+    if (!releasePath) {
+      throw new Error('controlled fixture release path is missing')
+    }
+    const deadline = Date.now() + 5_000
+    while (!(await Bun.file(releasePath).exists())) {
+      if (Date.now() >= deadline) {
+        throw new Error('controlled fixture release timed out')
+      }
+      await new Promise(resolve => setTimeout(resolve, 10))
+    }
+    if (mode === 'controlled-exit') process.exit(0)
+  }
   if (mode === 'wait' || mode === 'sigint' || mode === 'sigterm') {
     setInterval(() => {}, 1_000)
   }