@cat-factory/executor-harness 1.48.1 → 1.50.2

package/README.md

@@ -73,6 +73,8 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/bootstrap.ts` | The `/bootstrap` handler (clone-or-empty → adapt → reinit + force-push).                                |
 | `src/blueprint.ts` | The `/blueprint` handler (decompose → render `blueprints/` → commit on branch).                         |
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
+| `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`) — talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
+| `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 
 ## Runner lifecycle knobs
@@ -85,6 +87,8 @@ runner):
 | `PORT`                | `8080`          | HTTP port the harness listens on.                           |
 | `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
 | `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
+| `HARNESS_TRANSCRIPT_TTL_MS` | `259200000` (3d) | How long lifted subscription-CLI session transcripts are kept before the retention sweep prunes them. |
+| `HARNESS_TRANSCRIPT_ROOT`   | `<tmpdir>/cf-agent-transcripts` | Where retained session transcripts are moved to (one dir per run). Meaningful only on a reused (warm-pool) container; a per-run container is torn down with the job. The TTL sweep deletes only dirs it created (each carries a `.cf-retained` marker), so pointing this at a shared directory never touches unrelated content — though a dedicated dir is still recommended. An override on a different filesystem than the config home falls back to copy-then-remove. |
 
 ## Build / test
 

package/dist/agent-runner.js

@@ -4,6 +4,7 @@ import { homedir, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
+import { retainSessionTranscripts } from './transcript-retention.js';
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -38,7 +39,8 @@ function attributeCumulativeUsage(calls, usage) {
  * system-prompt flag — the caller prepends the composed system prompt to it so
  * the role + best-practice context is not lost.
  */
-function streamCli(command, args, prompt, opts, env, secrets, onEvent) {
+function streamCli(cli, prompt, opts, env, secrets, onEvent) {
+    const { command, args } = cli;
     return new Promise((resolve, reject) => {
         if (opts.signal?.aborted) {
             reject(new Error(`${command} aborted before start`));
@@ -270,22 +272,25 @@ export async function runClaudeCode(opts) {
                 : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
         };
     try {
-        const { stderrTail } = await streamCli('claude', [
-            '-p',
-            '--output-format',
-            'stream-json',
-            '--verbose',
-            // The per-run container IS the sandbox, and the run is fully headless (no one
-            // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
-            // would auto-accept file edits but still gate Bash, which in `-p` mode is then
-            // denied, leaving the agent unable to run builds/tests/git to verify its work.
-            '--permission-mode',
-            'bypassPermissions',
-            '--model',
-            opts.model,
-            '--append-system-prompt',
-            opts.systemPrompt,
-        ], opts.userPrompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        const { stderrTail } = await streamCli({
+            command: 'claude',
+            args: [
+                '-p',
+                '--output-format',
+                'stream-json',
+                '--verbose',
+                // The per-run container IS the sandbox, and the run is fully headless (no one
+                // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
+                // would auto-accept file edits but still gate Bash, which in `-p` mode is then
+                // denied, leaving the agent unable to run builds/tests/git to verify its work.
+                '--permission-mode',
+                'bypassPermissions',
+                '--model',
+                opts.model,
+                '--append-system-prompt',
+                opts.systemPrompt,
+            ],
+        }, opts.userPrompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         attributeCumulativeUsage(calls, usage);
         return {
             summary,
@@ -296,9 +301,17 @@ export async function runClaudeCode(opts) {
         };
     }
     finally {
-        // Never leave the config dir (and any cached credential) on disk past the run.
-        if (configHome)
+        if (configHome) {
+            // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
+            // home is deleted — the credential lives at the home root, never in `projects/`, so this
+            // keeps the debugging artifact without leaking the token. Best-effort; never throws.
+            await retainSessionTranscripts(configHome, ['projects'], {
+                label: 'claude-code',
+                ...(opts.log ? { log: opts.log } : {}),
+            });
+            // Never leave the config dir (and any cached credential) on disk past the run.
             await rm(configHome, { recursive: true, force: true }).catch(() => { });
+        }
     }
 }
 /** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
@@ -463,17 +476,20 @@ export async function runCodex(opts) {
         }
     };
     try {
-        const { stderrTail } = await streamCli('codex', [
-            'exec',
-            '--json',
-            '--skip-git-repo-check',
-            // The per-run container IS the sandbox; let Codex write files and reach the
-            // vendor unrestricted, with no approval prompts (the run is headless).
-            '--dangerously-bypass-approvals-and-sandbox',
-            '--model',
-            opts.model,
-            '-',
-        ], prompt, opts, codexHome ? { CODEX_HOME: codexHome } : {}, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        const { stderrTail } = await streamCli({
+            command: 'codex',
+            args: [
+                'exec',
+                '--json',
+                '--skip-git-repo-check',
+                // The per-run container IS the sandbox; let Codex write files and reach the
+                // vendor unrestricted, with no approval prompts (the run is headless).
+                '--dangerously-bypass-approvals-and-sandbox',
+                '--model',
+                opts.model,
+                '-',
+            ],
+        }, prompt, opts, codexHome ? { CODEX_HOME: codexHome } : {}, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
         // single call from the cumulative total + final text so the run is still observable.
         if (calls.length === 0 && (usage || summary)) {
@@ -498,9 +514,17 @@ export async function runCodex(opts) {
         };
     }
     finally {
-        // Never leave the decrypted credential on disk past the run.
-        if (codexHome)
+        if (codexHome) {
+            // Lift the CLI session transcripts (`sessions/`) out for short-lived retention BEFORE the
+            // home is deleted — the credential (`auth.json`) lives at the home root, never in
+            // `sessions/`, so this keeps the debugging artifact without leaking it. Best-effort.
+            await retainSessionTranscripts(codexHome, ['sessions'], {
+                label: 'codex',
+                ...(opts.log ? { log: opts.log } : {}),
+            });
+            // Never leave the decrypted credential on disk past the run.
             await rm(codexHome, { recursive: true, force: true }).catch(() => { });
+        }
     }
 }
 /**

package/dist/pi-workspace.js

@@ -146,6 +146,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             signal: opts.signal,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
+            ...(opts.log ? { log: opts.log } : {}),
         });
     }
     if (!spec.proxyBaseUrl || !spec.sessionToken) {

package/dist/transcript-retention.js

@@ -0,0 +1,139 @@
+import { cp, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+// Session-transcript retention for the subscription harnesses (Claude Code / Codex).
+//
+// Both runners create an ISOLATED, per-run config home so the leased OAuth credential never
+// lands in the cloned checkout, then delete that home in `finally`. The CLIs also write their
+// per-turn session transcripts INSIDE that home (`$CLAUDE_CONFIG_DIR/projects/…` for Claude
+// Code, `$CODEX_HOME/sessions/…` for Codex), so deleting the home also erases the exact
+// per-call detail needed to debug a finished run.
+//
+// This module lifts ONLY the transcript subtree out of the home BEFORE it is deleted, into a
+// retention root, and prunes retained transcripts on a short TTL. The credential lives at the
+// home ROOT (`.claude.json` / `auth.json`), never inside `projects/` / `sessions/`, so moving
+// just those subdirs keeps the debugging artifact while the existing `rm(home)` still removes
+// the credential — the credential-safety property is preserved.
+//
+// It is meaningful only where the container filesystem outlives the job (the reused local
+// warm-pool container, whose next run's sweep honours the TTL); on a per-run cloud container
+// torn down with the job it is a harmless no-op. Best-effort throughout: a retention failure
+// must NEVER fail an otherwise-successful run.
+/** Default retention window: 3 days. Overridable via `HARNESS_TRANSCRIPT_TTL_MS`. */
+const DEFAULT_TTL_MS = 3 * 24 * 60 * 60 * 1000;
+/**
+ * A marker file dropped into every retention dir THIS module creates. The pruner deletes ONLY
+ * dirs carrying it, so pointing `HARNESS_TRANSCRIPT_ROOT` at a shared (non-dedicated) directory
+ * can never `rm -rf` unrelated sibling content — we only ever sweep our own retained transcripts.
+ */
+export const RETENTION_MARKER = '.cf-retained';
+/** The retention root (one dir per retained home underneath it). Overridable for operators. */
+function retentionRoot() {
+    const override = process.env.HARNESS_TRANSCRIPT_ROOT?.trim();
+    return override && override.length > 0 ? override : join(tmpdir(), 'cf-agent-transcripts');
+}
+/** The retention TTL in ms, from the env override when it's a positive finite number. */
+function ttlMs() {
+    const raw = Number(process.env.HARNESS_TRANSCRIPT_TTL_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TTL_MS;
+}
+/**
+ * Move the named transcript `subdirs` out of the credential-bearing config `home` into the
+ * retention root (so the caller's subsequent `rm(home)` can't take them), then prune retained
+ * transcripts older than the TTL. Both steps are best-effort: any failure is swallowed (logged
+ * at debug) so this can never fail an otherwise-successful run. Returns the destination dir when
+ * something was retained (for logging/tests), else `undefined`.
+ */
+export async function retainSessionTranscripts(home, subdirs, options = {}) {
+    const { label, log } = options;
+    const root = retentionRoot();
+    // A filesystem-safe, sortable per-home dir name: an ISO stamp (colons/dots → dashes) + the
+    // home's basename (already unique — `mkdtemp` seeded).
+    const dest = join(root, `${new Date().toISOString().replace(/[:.]/g, '-')}-${basename(home)}`);
+    let moved = 0;
+    try {
+        for (const sub of subdirs) {
+            const from = join(home, sub);
+            try {
+                await stat(from);
+            }
+            catch {
+                continue; // the CLI never wrote this subdir this run — nothing to retain
+            }
+            if (moved === 0)
+                await ensureRetentionDir(dest);
+            await moveDir(from, join(dest, sub));
+            moved += 1;
+        }
+        if (moved > 0)
+            log?.info('retained session transcripts', { label, dest, subdirs: moved });
+    }
+    catch (err) {
+        log?.debug('failed to retain session transcripts', {
+            label,
+            err: err instanceof Error ? err.message : String(err),
+        });
+    }
+    // Prune regardless of whether this run retained anything — a run that moved nothing still gets
+    // to sweep the backlog left by earlier runs on a reused container.
+    await pruneRetentionRoot(root, ttlMs(), log);
+    return moved > 0 ? dest : undefined;
+}
+/** Create a retention dir and stamp it with the ownership marker (see {@link RETENTION_MARKER}). */
+async function ensureRetentionDir(dest) {
+    await mkdir(dest, { recursive: true });
+    await writeFile(join(dest, RETENTION_MARKER), '');
+}
+/**
+ * Move `from` → `to`, preferring a cheap same-filesystem `rename`. When the retention root is on
+ * a DIFFERENT device than the config home (an operator override of `HARNESS_TRANSCRIPT_ROOT`),
+ * `rename` fails with `EXDEV` — fall back to a recursive copy + remove so the transcript is still
+ * lifted out before the caller deletes the home, rather than being silently lost.
+ */
+async function moveDir(from, to) {
+    try {
+        await rename(from, to);
+    }
+    catch (err) {
+        if (err?.code !== 'EXDEV')
+            throw err;
+        await cp(from, to, { recursive: true });
+        await rm(from, { recursive: true, force: true });
+    }
+}
+/**
+ * Delete retained-transcript dirs whose mtime is older than `maxAgeMs`. Only dirs carrying the
+ * retention marker are candidates — foreign content under a shared retention root is never
+ * touched. Best-effort per entry (a concurrent sweep or a vanished dir must not abort the loop).
+ */
+async function pruneRetentionRoot(root, maxAgeMs, log) {
+    const cutoff = Date.now() - maxAgeMs;
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return; // the root doesn't exist yet (nothing ever retained) — nothing to prune
+    }
+    for (const name of entries) {
+        const path = join(root, name);
+        try {
+            const info = await stat(path);
+            if (!info.isDirectory() || info.mtimeMs >= cutoff)
+                continue;
+            // Ownership gate: only sweep dirs WE created (they carry the marker). This makes a
+            // shared/non-dedicated `HARNESS_TRANSCRIPT_ROOT` safe — unrelated dirs are left alone.
+            try {
+                await stat(join(path, RETENTION_MARKER));
+            }
+            catch {
+                continue; // not one of ours — never delete it
+            }
+            await rm(path, { recursive: true, force: true });
+            log?.debug('pruned expired session transcripts', { path });
+        }
+        catch {
+            // best-effort per entry — a concurrent sweep or a vanished dir must not abort the loop
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.48.1",
+  "version": "1.50.2",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.137.2",
-    "@cat-factory/spend": "0.12.52"
+    "@cat-factory/server": "0.138.11",
+    "@cat-factory/spend": "0.12.63"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -2,9 +2,11 @@ import { spawn } from 'node:child_process'
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { homedir, tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
+import type { Logger } from './logger.js'
 import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
+import { retainSessionTranscripts } from './transcript-retention.js'
 
 // The alternate (subscription) harness runners. The Pi harness reaches models
 // through the LLM proxy with a model-locked session token; the Claude Code and
@@ -70,6 +72,11 @@ export interface SubscriptionRunOptions {
   onActivity?: () => void
   /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
   onProgress?: (progress: TodoProgress) => void
+  /**
+   * The per-job child logger (jobId/repo/branch correlation). Threaded so the retained
+   * session-transcript path is logged for the run when the isolated config home is torn down.
+   */
+  log?: Logger
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -111,14 +118,14 @@ function attributeCumulativeUsage(
  * the role + best-practice context is not lost.
  */
 function streamCli(
-  command: string,
-  args: string[],
+  cli: { command: string; args: string[] },
   prompt: string,
   opts: SubscriptionRunOptions,
   env: Record<string, string>,
   secrets: string[],
   onEvent: (event: Record<string, unknown>) => void,
 ): Promise<{ stderrTail: string }> {
+  const { command, args } = cli
   return new Promise((resolve, reject) => {
     if (opts.signal?.aborted) {
       reject(new Error(`${command} aborted before start`))
@@ -367,23 +374,25 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
 
   try {
     const { stderrTail } = await streamCli(
-      'claude',
-      [
-        '-p',
-        '--output-format',
-        'stream-json',
-        '--verbose',
-        // The per-run container IS the sandbox, and the run is fully headless (no one
-        // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
-        // would auto-accept file edits but still gate Bash, which in `-p` mode is then
-        // denied, leaving the agent unable to run builds/tests/git to verify its work.
-        '--permission-mode',
-        'bypassPermissions',
-        '--model',
-        opts.model,
-        '--append-system-prompt',
-        opts.systemPrompt,
-      ],
+      {
+        command: 'claude',
+        args: [
+          '-p',
+          '--output-format',
+          'stream-json',
+          '--verbose',
+          // The per-run container IS the sandbox, and the run is fully headless (no one
+          // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
+          // would auto-accept file edits but still gate Bash, which in `-p` mode is then
+          // denied, leaving the agent unable to run builds/tests/git to verify its work.
+          '--permission-mode',
+          'bypassPermissions',
+          '--model',
+          opts.model,
+          '--append-system-prompt',
+          opts.systemPrompt,
+        ],
+      },
       opts.userPrompt,
       opts,
       env,
@@ -400,8 +409,17 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       ...(calls.length ? { callMetrics: calls } : {}),
     }
   } finally {
-    // Never leave the config dir (and any cached credential) on disk past the run.
-    if (configHome) await rm(configHome, { recursive: true, force: true }).catch(() => {})
+    if (configHome) {
+      // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
+      // home is deleted — the credential lives at the home root, never in `projects/`, so this
+      // keeps the debugging artifact without leaking the token. Best-effort; never throws.
+      await retainSessionTranscripts(configHome, ['projects'], {
+        label: 'claude-code',
+        ...(opts.log ? { log: opts.log } : {}),
+      })
+      // Never leave the config dir (and any cached credential) on disk past the run.
+      await rm(configHome, { recursive: true, force: true }).catch(() => {})
+    }
   }
 }
 
@@ -578,18 +596,20 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
 
   try {
     const { stderrTail } = await streamCli(
-      'codex',
-      [
-        'exec',
-        '--json',
-        '--skip-git-repo-check',
-        // The per-run container IS the sandbox; let Codex write files and reach the
-        // vendor unrestricted, with no approval prompts (the run is headless).
-        '--dangerously-bypass-approvals-and-sandbox',
-        '--model',
-        opts.model,
-        '-',
-      ],
+      {
+        command: 'codex',
+        args: [
+          'exec',
+          '--json',
+          '--skip-git-repo-check',
+          // The per-run container IS the sandbox; let Codex write files and reach the
+          // vendor unrestricted, with no approval prompts (the run is headless).
+          '--dangerously-bypass-approvals-and-sandbox',
+          '--model',
+          opts.model,
+          '-',
+        ],
+      },
       prompt,
       opts,
       codexHome ? { CODEX_HOME: codexHome } : {},
@@ -620,8 +640,17 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
       ...(calls.length ? { callMetrics: calls } : {}),
     }
   } finally {
-    // Never leave the decrypted credential on disk past the run.
-    if (codexHome) await rm(codexHome, { recursive: true, force: true }).catch(() => {})
+    if (codexHome) {
+      // Lift the CLI session transcripts (`sessions/`) out for short-lived retention BEFORE the
+      // home is deleted — the credential (`auth.json`) lives at the home root, never in
+      // `sessions/`, so this keeps the debugging artifact without leaking it. Best-effort.
+      await retainSessionTranscripts(codexHome, ['sessions'], {
+        label: 'codex',
+        ...(opts.log ? { log: opts.log } : {}),
+      })
+      // Never leave the decrypted credential on disk past the run.
+      await rm(codexHome, { recursive: true, force: true }).catch(() => {})
+    }
   }
 }
 

package/src/pi-workspace.ts

@@ -270,6 +270,7 @@ export async function runAgentInWorkspace(
       signal: opts.signal,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
+      ...(opts.log ? { log: opts.log } : {}),
     })
   }
   if (!spec.proxyBaseUrl || !spec.sessionToken) {

package/src/transcript-retention.ts

@@ -0,0 +1,150 @@
+import { cp, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import type { Logger } from './logger.js'
+
+// Session-transcript retention for the subscription harnesses (Claude Code / Codex).
+//
+// Both runners create an ISOLATED, per-run config home so the leased OAuth credential never
+// lands in the cloned checkout, then delete that home in `finally`. The CLIs also write their
+// per-turn session transcripts INSIDE that home (`$CLAUDE_CONFIG_DIR/projects/…` for Claude
+// Code, `$CODEX_HOME/sessions/…` for Codex), so deleting the home also erases the exact
+// per-call detail needed to debug a finished run.
+//
+// This module lifts ONLY the transcript subtree out of the home BEFORE it is deleted, into a
+// retention root, and prunes retained transcripts on a short TTL. The credential lives at the
+// home ROOT (`.claude.json` / `auth.json`), never inside `projects/` / `sessions/`, so moving
+// just those subdirs keeps the debugging artifact while the existing `rm(home)` still removes
+// the credential — the credential-safety property is preserved.
+//
+// It is meaningful only where the container filesystem outlives the job (the reused local
+// warm-pool container, whose next run's sweep honours the TTL); on a per-run cloud container
+// torn down with the job it is a harmless no-op. Best-effort throughout: a retention failure
+// must NEVER fail an otherwise-successful run.
+
+/** Default retention window: 3 days. Overridable via `HARNESS_TRANSCRIPT_TTL_MS`. */
+const DEFAULT_TTL_MS = 3 * 24 * 60 * 60 * 1000
+
+/**
+ * A marker file dropped into every retention dir THIS module creates. The pruner deletes ONLY
+ * dirs carrying it, so pointing `HARNESS_TRANSCRIPT_ROOT` at a shared (non-dedicated) directory
+ * can never `rm -rf` unrelated sibling content — we only ever sweep our own retained transcripts.
+ */
+export const RETENTION_MARKER = '.cf-retained'
+
+/** The retention root (one dir per retained home underneath it). Overridable for operators. */
+function retentionRoot(): string {
+  const override = process.env.HARNESS_TRANSCRIPT_ROOT?.trim()
+  return override && override.length > 0 ? override : join(tmpdir(), 'cf-agent-transcripts')
+}
+
+/** The retention TTL in ms, from the env override when it's a positive finite number. */
+function ttlMs(): number {
+  const raw = Number(process.env.HARNESS_TRANSCRIPT_TTL_MS)
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TTL_MS
+}
+
+export interface RetainOptions {
+  /** A short label for the run/harness, folded into the retention log line. */
+  label?: string
+  /** The per-job child logger, so the retained path is logged with the run's correlation fields. */
+  log?: Logger
+}
+
+/**
+ * Move the named transcript `subdirs` out of the credential-bearing config `home` into the
+ * retention root (so the caller's subsequent `rm(home)` can't take them), then prune retained
+ * transcripts older than the TTL. Both steps are best-effort: any failure is swallowed (logged
+ * at debug) so this can never fail an otherwise-successful run. Returns the destination dir when
+ * something was retained (for logging/tests), else `undefined`.
+ */
+export async function retainSessionTranscripts(
+  home: string,
+  subdirs: string[],
+  options: RetainOptions = {},
+): Promise<string | undefined> {
+  const { label, log } = options
+  const root = retentionRoot()
+  // A filesystem-safe, sortable per-home dir name: an ISO stamp (colons/dots → dashes) + the
+  // home's basename (already unique — `mkdtemp` seeded).
+  const dest = join(root, `${new Date().toISOString().replace(/[:.]/g, '-')}-${basename(home)}`)
+  let moved = 0
+  try {
+    for (const sub of subdirs) {
+      const from = join(home, sub)
+      try {
+        await stat(from)
+      } catch {
+        continue // the CLI never wrote this subdir this run — nothing to retain
+      }
+      if (moved === 0) await ensureRetentionDir(dest)
+      await moveDir(from, join(dest, sub))
+      moved += 1
+    }
+    if (moved > 0) log?.info('retained session transcripts', { label, dest, subdirs: moved })
+  } catch (err) {
+    log?.debug('failed to retain session transcripts', {
+      label,
+      err: err instanceof Error ? err.message : String(err),
+    })
+  }
+  // Prune regardless of whether this run retained anything — a run that moved nothing still gets
+  // to sweep the backlog left by earlier runs on a reused container.
+  await pruneRetentionRoot(root, ttlMs(), log)
+  return moved > 0 ? dest : undefined
+}
+
+/** Create a retention dir and stamp it with the ownership marker (see {@link RETENTION_MARKER}). */
+async function ensureRetentionDir(dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true })
+  await writeFile(join(dest, RETENTION_MARKER), '')
+}
+
+/**
+ * Move `from` → `to`, preferring a cheap same-filesystem `rename`. When the retention root is on
+ * a DIFFERENT device than the config home (an operator override of `HARNESS_TRANSCRIPT_ROOT`),
+ * `rename` fails with `EXDEV` — fall back to a recursive copy + remove so the transcript is still
+ * lifted out before the caller deletes the home, rather than being silently lost.
+ */
+async function moveDir(from: string, to: string): Promise<void> {
+  try {
+    await rename(from, to)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code !== 'EXDEV') throw err
+    await cp(from, to, { recursive: true })
+    await rm(from, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Delete retained-transcript dirs whose mtime is older than `maxAgeMs`. Only dirs carrying the
+ * retention marker are candidates — foreign content under a shared retention root is never
+ * touched. Best-effort per entry (a concurrent sweep or a vanished dir must not abort the loop).
+ */
+async function pruneRetentionRoot(root: string, maxAgeMs: number, log?: Logger): Promise<void> {
+  const cutoff = Date.now() - maxAgeMs
+  let entries: string[]
+  try {
+    entries = await readdir(root)
+  } catch {
+    return // the root doesn't exist yet (nothing ever retained) — nothing to prune
+  }
+  for (const name of entries) {
+    const path = join(root, name)
+    try {
+      const info = await stat(path)
+      if (!info.isDirectory() || info.mtimeMs >= cutoff) continue
+      // Ownership gate: only sweep dirs WE created (they carry the marker). This makes a
+      // shared/non-dedicated `HARNESS_TRANSCRIPT_ROOT` safe — unrelated dirs are left alone.
+      try {
+        await stat(join(path, RETENTION_MARKER))
+      } catch {
+        continue // not one of ours — never delete it
+      }
+      await rm(path, { recursive: true, force: true })
+      log?.debug('pruned expired session transcripts', { path })
+    } catch {
+      // best-effort per entry — a concurrent sweep or a vanished dir must not abort the loop
+    }
+  }
+}