@agentworkforce/cli 0.18.0 → 0.19.0

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { constants, homedir, tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { HARNESS_VALUES, materializeSkills, PERSONA_TAGS, PERSONA_TIERS, listBuiltInPersonas, personaCatalog, resolveSidecar, routingProfiles, useSelection } from '@agentworkforce/workload-router';
-import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
+import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient, useRunnableSelection } from '@agentworkforce/harness-kit';
 import { createMount, readAgentDotfiles } from '@relayfile/local-mount';
 import ora from 'ora';
 import { startLaunchMetadataRecording } from './launch-metadata.js';
@@ -332,28 +332,45 @@ function subprocessExitCode(res) {
  * the buffered output is dumped after spinner.fail so the user sees what
  * actually broke. stdin is ignored — the install commands don't prompt.
  *
+ * Uses async `spawn` (not `spawnSync`) because ora's frame redraw runs on a
+ * setInterval — `spawnSync` blocks the event loop for the duration of the
+ * install, freezing the spinner on its first frame.
+ *
  * The spinner text stays "Installing skills…" while running; the longer
  * `label` (which includes target paths and skill ids) is shown on
  * success/failure so the verbose detail is still discoverable in logs.
  */
-function runInstallWithSpinner(command, label, cwd) {
+async function runInstallWithSpinner(command, label, cwd) {
     const [bin, ...args] = command;
     if (!bin)
         return { code: 0, output: '' };
     const spinner = ora({ text: 'Installing skills…', stream: process.stderr }).start();
-    const res = spawnSync(bin, args, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        shell: false,
-        encoding: 'utf8',
-        // Default is 1 MiB; verbose `npx prpm install` / `npx skills add` runs
-        // can blow past it, which would have spawnSync kill the child with
-        // ENOBUFS and report a spurious failure. 100 MiB is well past anything
-        // these installers print in practice.
-        maxBuffer: 100 * 1024 * 1024,
-        ...(cwd ? { cwd } : {})
+    // Async spawn (not spawnSync) so ora's frame timer can fire during the
+    // install — spawnSync blocks the event loop and freezes the spinner on
+    // its first frame.
+    const { code, output } = await new Promise((resolve) => {
+        const child = spawn(bin, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
+            ...(cwd ? { cwd } : {})
+        });
+        let buffered = '';
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            buffered += chunk;
+        });
+        child.stderr?.on('data', (chunk) => {
+            buffered += chunk;
+        });
+        child.on('error', (err) => {
+            resolve({ code: 1, output: `${buffered}${err.message}\n` });
+        });
+        child.on('close', (status, signal) => {
+            const exit = typeof status === 'number' ? status : signal ? signalExitCode(signal) : 1;
+            resolve({ code: exit, output: buffered });
+        });
     });
-    const output = `${res.stdout ?? ''}${res.stderr ?? ''}`;
-    const code = subprocessExitCode(res);
     if (code === 0) {
         spinner.succeed(label);
     }
@@ -364,13 +381,13 @@ function runInstallWithSpinner(command, label, cwd) {
     }
     return { code, output };
 }
-function runInstall(command, label, cwd) {
+async function runInstall(command, label, cwd) {
     const [bin] = command;
     if (!bin)
         return;
     // runInstallWithSpinner already prints the failure line via spinner.fail;
     // the previous extra "${label} failed … Aborting." write would duplicate it.
-    const { code } = runInstallWithSpinner(command, label, cwd);
+    const { code } = await runInstallWithSpinner(command, label, cwd);
     if (code !== 0)
         process.exit(code);
 }
@@ -392,11 +409,11 @@ class InstallCommandError extends Error {
  * Used inside the mount branch's onBeforeLaunch step so mount teardown runs
  * before the error surfaces.
  */
-function runInstallOrThrow(command, label, cwd) {
+async function runInstallOrThrow(command, label, cwd) {
     const [bin] = command;
     if (!bin)
         return;
-    const { code } = runInstallWithSpinner(command, label, cwd);
+    const { code } = await runInstallWithSpinner(command, label, cwd);
     if (code !== 0) {
         throw new InstallCommandError(label, code);
     }
@@ -949,7 +966,7 @@ async function runInteractive(selection, options) {
     // `onBeforeLaunch` below instead of pre-running here.
     const deferInstallToMount = useClean && runtime.harness !== 'claude' && install.commandString !== ':';
     if (install.commandString !== ':' && !deferInstallToMount) {
-        runInstall(install.command, installLabel);
+        await runInstall(install.command, installLabel);
     }
     const spec = buildInteractiveSpec({
         harness: runtime.harness,
@@ -1039,32 +1056,61 @@ async function runInteractive(selection, options) {
             mount: effectiveSelection.mount,
             configFilePaths: spec.configFiles.map((file) => file.path)
         });
-        process.stderr.write(`• sandbox mount → ${mountDir}\n`);
+        // Setup spinner covers createMount + git-config + (optional) in-mount
+        // install + config-file writes + autosync start, so the multi-second
+        // pause before the harness child appears is visibly live. createMount
+        // is async in @relayfile/local-mount ≥0.7.0, which yields between
+        // directory entries — so this spinner actually animates instead of
+        // freezing on its first frame.
+        let setupSpinner = ora({
+            text: `Setting up sandbox mount → ${mountDir}…`,
+            stream: process.stderr
+        }).start();
         // Inline mount lifecycle (formerly delegated to launchOnMount) so we can
         // surface a spinner the moment the child exits — not just when the user
         // presses Ctrl-C. The sync-back walks both trees and can take several
         // seconds on a large repo; without an indicator, exiting the persona via
         // /exit looked like a hang.
         //
-        // SIGINT semantics:
-        //   • While the child is running: Ctrl-C reaches the harness directly via
-        //     the controlling TTY's foreground process group (the child is
-        //     spawned with `stdio: 'inherit'` and inherits the parent's pgid). We
-        //     register a no-op handler here purely to suppress Node's default
-        //     exit-on-SIGINT — forwarding via child.kill('SIGINT') would deliver
-        //     a *second* SIGINT and break harnesses that escalate on repeated
-        //     interrupts (e.g. claude treats 1st = cancel, 2nd = quit).
-        //   • While syncing: 1st press aborts the shutdownSignal (relayfile then
-        //     skips autosync's draining reconcile and returns the partial count
-        //     from the final syncBack). 2nd press hard-exits and rms the session
-        //     dir so no mount is left behind.
+        // SIGINT semantics — three phases:
+        //   • Pre-launch (setup): tear down the setup spinner, rm the session
+        //     dir, and exit(130). We must handle this ourselves because
+        //     registering any 'SIGINT' listener suppresses Node's default
+        //     exit-on-SIGINT, and createMount is now async (relayfile 0.7+) so
+        //     the handler actually fires during mount setup.
+        //   • Child running: Ctrl-C reaches the harness directly via the
+        //     controlling TTY's foreground process group (the child is spawned
+        //     with `stdio: 'inherit'` and inherits the parent's pgid). We
+        //     no-op purely to suppress Node's default exit — forwarding via
+        //     child.kill('SIGINT') would deliver a *second* SIGINT and break
+        //     harnesses that escalate on repeated interrupts (e.g. claude
+        //     treats 1st = cancel, 2nd = quit).
+        //   • Syncing (post-child): 1st press aborts the shutdownSignal
+        //     (relayfile then skips autosync's draining reconcile and returns
+        //     the partial count from the final syncBack). 2nd press hard-exits
+        //     and rms the session dir so no mount is left behind.
         const shutdownController = new AbortController();
         let syncSpinner;
         let isSyncing = false;
+        let childSpawned = false;
         let abortPresses = 0;
         const sigintHandler = () => {
-            if (!isSyncing)
-                return;
+            if (!isSyncing) {
+                if (childSpawned)
+                    return;
+                // Pre-launch teardown.
+                if (setupSpinner) {
+                    setupSpinner.fail('Sandbox mount setup interrupted (Ctrl-C)');
+                    setupSpinner = undefined;
+                }
+                try {
+                    rmSync(sessionRoot, { recursive: true, force: true });
+                }
+                catch {
+                    /* swallow — we're exiting anyway */
+                }
+                process.exit(130);
+            }
             abortPresses += 1;
             if (abortPresses === 1) {
                 if (syncSpinner) {
@@ -1090,27 +1136,35 @@ async function runInteractive(selection, options) {
             process.exit(130);
         };
         process.on('SIGINT', sigintHandler);
-        const handle = createMount(process.cwd(), mountDir, {
-            ignoredPatterns: [...ignoredPatterns],
-            readonlyPatterns: [...readonlyPatterns],
-            excludeDirs: [],
-            agentName: personaId,
-            // Pull `.git` into the mount so git commands work inside the sandbox.
-            // relayfile treats this as one-way project→mount: host-side `.git`
-            // changes flow in, mount-side commits/refs stay sandboxed and are
-            // discarded on cleanup. The agent must `git push` to persist work.
-            includeGit: true
-        });
+        let handle;
         let autoSync;
         let exitCode = 0;
         try {
+            // createMount inside the try so its initial-mirror failures fall into
+            // the catch path and clean up the setup spinner.
+            handle = await createMount(process.cwd(), mountDir, {
+                ignoredPatterns: [...ignoredPatterns],
+                readonlyPatterns: [...readonlyPatterns],
+                excludeDirs: [],
+                agentName: personaId,
+                // Pull `.git` into the mount so git commands work inside the
+                // sandbox. relayfile treats this as one-way project→mount: host-side
+                // `.git` changes flow in, mount-side commits/refs stay sandboxed and
+                // are discarded on cleanup. The agent must `git push` to persist
+                // work.
+                includeGit: true
+            });
             // Run before install / configFile writes so the freshly written files
             // (e.g. `.opencode/`, `opencode.json`) aren't yet present when we run
             // `git ls-files` to pick skip-worktree candidates — we don't need them
             // flagged in the index, just hidden via the `.git/info/exclude` block.
             configureGitForMount(handle.mountDir, ignoredPatterns);
             if (deferInstallToMount) {
-                runInstallOrThrow(install.command, installLabel, handle.mountDir);
+                // Hand the line off to the install spinner so the two don't fight
+                // for the same stream, then resume the setup spinner afterwards.
+                setupSpinner?.stop();
+                await runInstallOrThrow(install.command, installLabel, handle.mountDir);
+                setupSpinner?.start();
             }
             for (const file of spec.configFiles) {
                 assertSafeRelativePath(file.path);
@@ -1123,11 +1177,30 @@ async function runInteractive(selection, options) {
                 writeFileSync(join(handle.mountDir, resolvedSidecar.mountFile), body, 'utf8');
             }
             launchMetadata = await startLaunchMetadataForLaunch(handle.mountDir);
+            if (options.capture) {
+                options.capture.stampEnrichment = { ...launchMetadata.metadata };
+                options.capture.stampingEnabled = launchMetadata.enabled;
+            }
             autoSync = handle.startAutoSync();
+            // Stop the setup spinner before spawning the child — the child
+            // inherits stdio and would otherwise interleave its output with
+            // spinner frames.
+            setupSpinner?.succeed(`Sandbox mount ready → ${mountDir}`);
+            setupSpinner = undefined;
             const childEnv = resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env;
+            const childCwd = handle.mountDir;
+            if (options.capture) {
+                options.capture.sessionCwd = childCwd;
+                options.capture.harness = runtime.harness;
+                options.capture.startedAt = Date.now();
+            }
+            // Flip the SIGINT phase flag before spawn so a Ctrl-C arriving during
+            // the child's lifetime is treated as "child has the TTY" (no-op),
+            // not as pre-launch teardown.
+            childSpawned = true;
             exitCode = await new Promise((resolve, reject) => {
                 const child = spawn(spec.bin, finalArgs, {
-                    cwd: handle.mountDir,
+                    cwd: childCwd,
                     stdio: 'inherit',
                     env: childEnv
                 });
@@ -1169,6 +1242,10 @@ async function runInteractive(selection, options) {
             return exitCode;
         }
         catch (err) {
+            if (setupSpinner) {
+                setupSpinner.fail('Sandbox mount setup failed');
+                setupSpinner = undefined;
+            }
             if (syncSpinner) {
                 syncSpinner.fail('Sync did not complete');
                 syncSpinner = undefined;
@@ -1190,6 +1267,10 @@ async function runInteractive(selection, options) {
             return 1;
         }
         finally {
+            if (setupSpinner) {
+                setupSpinner.stop();
+                setupSpinner = undefined;
+            }
             if (syncSpinner) {
                 syncSpinner.stop();
                 syncSpinner = undefined;
@@ -1204,7 +1285,7 @@ async function runInteractive(selection, options) {
                     /* ignore — we're tearing down anyway */
                 }
             }
-            handle.cleanup();
+            handle?.cleanup();
             await launchMetadata?.stop();
             process.removeListener('SIGINT', sigintHandler);
             // When the install ran inside the mount, its cleanup paths are
@@ -1220,6 +1301,13 @@ async function runInteractive(selection, options) {
         }
     }
     const launchMetadata = await startLaunchMetadataForLaunch();
+    if (options.capture) {
+        options.capture.sessionCwd = process.cwd();
+        options.capture.harness = runtime.harness;
+        options.capture.startedAt = Date.now();
+        options.capture.stampEnrichment = { ...launchMetadata.metadata };
+        options.capture.stampingEnabled = launchMetadata.enabled;
+    }
     return new Promise((resolve) => {
         let settled = false;
         const finish = (code) => {
@@ -2042,14 +2130,825 @@ async function runAgentSelector(selector, flags, inputValues) {
         const code = runDryRun(selection);
         process.exit(code);
     }
+    const capture = {};
     const code = await runInteractive(selection, {
         installInRepo: flags.installInRepo,
         noLaunchMetadata: flags.noLaunchMetadata,
         personaSpec: target.spec,
-        personaSource: target.source
+        personaSource: target.source,
+        capture
+    });
+    // Post-session learnings prompt: only for local personas (built-in
+    // catalog and pack personas are read-only here), and only when stdin
+    // is a TTY so we can read y/N. Improver failures never affect the
+    // user-facing exit code — the original session's exit is what matters.
+    await maybeOfferLearningsImprover({
+        target,
+        capture,
+        flags
     });
     process.exit(code);
 }
+/**
+ * Decide whether to offer post-session auto-improvement, run the improver,
+ * walk the proposals interactively, and apply accepted patches. Silently
+ * skips the prompt when the persona is built-in or stdin is not a TTY.
+ *
+ * Failures (improver crash, malformed proposals JSON, unwriteable persona
+ * file) are surfaced as warnings on stderr; they never throw or change
+ * the original session's exit code. The user already saw their session
+ * complete — a flaky meta-step shouldn't mask that.
+ */
+async function maybeOfferLearningsImprover(ctx) {
+    if (ctx.target.kind !== 'local')
+        return;
+    if (ctx.target.source === 'library')
+        return;
+    const personaFilePath = local.paths.get(ctx.target.spec.id);
+    if (!personaFilePath) {
+        // No on-disk path means we can't apply patches even if the user agrees.
+        // Skip silently — local-personas would have warned at load time.
+        return;
+    }
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        return;
+    const personaId = ctx.target.spec.id;
+    const wantsImprover = promptYesNoSync(`\nAuto-improve "${personaId}" from this session? [y/N] `);
+    if (!wantsImprover)
+        return;
+    let transcriptPath = '';
+    try {
+        if (ctx.capture.stampingEnabled && ctx.capture.stampEnrichment) {
+            transcriptPath =
+                (await findSessionTranscriptViaStamps({
+                    harness: ctx.capture.harness,
+                    sessionCwd: ctx.capture.sessionCwd,
+                    enrichment: ctx.capture.stampEnrichment,
+                    startedAt: ctx.capture.startedAt
+                })) ?? '';
+        }
+        if (!transcriptPath) {
+            transcriptPath =
+                findSessionTranscriptPath({
+                    harness: ctx.capture.harness,
+                    sessionCwd: ctx.capture.sessionCwd,
+                    startedAt: ctx.capture.startedAt
+                }) ?? '';
+        }
+    }
+    catch (err) {
+        process.stderr.write(`warning: could not locate session transcript: ${err.message}\n`);
+    }
+    if (!transcriptPath) {
+        process.stderr.write(`note: session transcript not found for harness "${ctx.capture.harness ?? '?'}" — proceeding from persona file alone.\n`);
+    }
+    let proposals;
+    const proposalsTempPath = join(tmpdir(), `agentworkforce-proposals-${randomBytes(6).toString('hex')}.json`);
+    const spinner = ora({
+        text: 'Extracting learnings via persona-improver…',
+        stream: process.stderr
+    }).start();
+    try {
+        proposals = await runPersonaImprover({
+            personaFilePath,
+            transcriptPath,
+            proposalsOutputPath: proposalsTempPath
+        });
+        spinner.succeed(proposals.proposals.length === 0
+            ? 'persona-improver: no improvements to propose.'
+            : `persona-improver: found ${proposals.proposals.length} proposed improvement${proposals.proposals.length === 1 ? '' : 's'}.`);
+    }
+    catch (err) {
+        spinner.fail(`persona-improver failed: ${err.message}`);
+        return;
+    }
+    finally {
+        try {
+            rmSync(proposalsTempPath, { force: true });
+        }
+        catch {
+            /* swallow — temp file in $TMPDIR is harmless */
+        }
+    }
+    if (!proposals || proposals.proposals.length === 0)
+        return;
+    const accepted = walkProposalsInteractive(proposals);
+    if (accepted.length === 0) {
+        process.stderr.write('No improvements applied.\n');
+        return;
+    }
+    try {
+        applyAcceptedPatches(personaFilePath, accepted);
+        process.stderr.write(`✓ Applied ${accepted.length} improvement${accepted.length === 1 ? '' : 's'} to ${personaFilePath}\n`);
+    }
+    catch (err) {
+        process.stderr.write(`warning: failed to write updated persona to ${personaFilePath}: ${err.message}\n`);
+    }
+}
+/**
+ * Allowlist of dot-paths the improver may rewrite via `op: "set"`. Mirrors
+ * the patch grammar advertised in the persona's AGENTS.md — anything else
+ * is a defense-in-depth reject (the persona's anti-goals already say "no
+ * changes to id/intent/harness/model/permissions", but we don't trust the
+ * model alone for a flow that mutates the user's persona file in place).
+ */
+const ALLOWED_SET_PATHS = [
+    'description',
+    'agentsMdContent',
+    'claudeMdContent',
+    'tags',
+    'tiers.best.systemPrompt',
+    'tiers.best-value.systemPrompt',
+    'tiers.minimum.systemPrompt'
+];
+/**
+ * Allowlist of dot-paths the improver may rewrite via `op: "append"`.
+ * Currently just `skills` — the only array the AGENTS.md grammar exposes
+ * for append-style mutation.
+ */
+const ALLOWED_APPEND_PATHS = ['skills'];
+/**
+ * Reserved JSON-object keys that must never appear as a path segment —
+ * setting them would either pollute the prototype chain (`__proto__`,
+ * `constructor`, `prototype`) for the running process or rewrite a
+ * built-in property that downstream code relies on. Belt-and-braces
+ * alongside the path allowlist; even an `inputs.<NAME>` segment can't
+ * smuggle one of these in.
+ */
+const FORBIDDEN_PATH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+function assertSafePathSegments(path, context) {
+    const segments = path.split('.').filter((s) => s.length > 0);
+    if (segments.length === 0) {
+        throw new Error(`${context}: path is empty`);
+    }
+    for (const seg of segments) {
+        if (FORBIDDEN_PATH_SEGMENTS.has(seg)) {
+            throw new Error(`${context}: path "${path}" contains forbidden segment "${seg}"`);
+        }
+    }
+    return segments;
+}
+/**
+ * Validate one improver patch against the path/op allowlist + the
+ * prototype-segment guard. Throws a descriptive error rejected at parse
+ * time so the CLI never offers a disallowed proposal to the user.
+ *
+ * Allowed set paths: see ALLOWED_SET_PATHS, plus any `inputs.<NAME>`
+ * (NAME must be env-style, matching the persona-input naming rule).
+ * Allowed append paths: see ALLOWED_APPEND_PATHS.
+ */
+function assertAllowedImproverPatch(patch, context) {
+    assertSafePathSegments(patch.path, context);
+    if (patch.op === 'set') {
+        if (ALLOWED_SET_PATHS.includes(patch.path))
+            return;
+        if (patch.path.startsWith('inputs.')) {
+            const after = patch.path.slice('inputs.'.length);
+            if (!/^[A-Z_][A-Z0-9_]*$/.test(after)) {
+                throw new Error(`${context}: inputs path "${patch.path}" must use an env-style NAME (got "${after}")`);
+            }
+            return;
+        }
+        throw new Error(`${context}: set path "${patch.path}" is not in the allowlist`);
+    }
+    if (patch.op === 'append') {
+        if (!ALLOWED_APPEND_PATHS.includes(patch.path)) {
+            throw new Error(`${context}: append path "${patch.path}" is not in the allowlist`);
+        }
+        return;
+    }
+    throw new Error(`${context}: unknown patch op "${patch.op}"`);
+}
+/**
+ * Locate the just-ended session's transcript via the burn-stamp ledger.
+ * Authoritative when stamping is wired: `launch-metadata.ts` writes a
+ * pending stamp (with our `personaVersion` enrichment hash) before spawn
+ * and runs `ingest` on a 1s tick + once at stop, so by the time we get
+ * here the ledger already has a row whose `selector.sessionId` is the
+ * harness's own session id. We filter by `persona` + `personaVersion`
+ * (unique per persona spec hash) and `ts` near `startedAt` to avoid
+ * picking up a sibling launch of the same persona, then resolve the
+ * sessionId to a transcript file path per harness.
+ *
+ * Returns undefined when:
+ *   - the SDK call fails
+ *   - no row matches (ingest hasn't reconciled yet, or stamping is off)
+ *   - the resolved sessionId can't be located on disk
+ * Caller falls back to `findSessionTranscriptPath` (cwd-content match).
+ */
+async function findSessionTranscriptViaStamps(input) {
+    if (!input.harness || !input.sessionCwd)
+        return undefined;
+    const persona = input.enrichment.persona;
+    const personaVersion = input.enrichment.personaVersion;
+    if (!persona || !personaVersion)
+        return undefined;
+    let sdk;
+    try {
+        sdk = await import('@relayburn/sdk');
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof sdk.exportStamps !== 'function')
+        return undefined;
+    let rows;
+    try {
+        rows = await sdk.exportStamps();
+    }
+    catch {
+        return undefined;
+    }
+    const startedAt = input.startedAt ?? 0;
+    const spawnerPid = input.enrichment.spawnerPid;
+    // Tight window around our session: stamps written before our spawn
+    // (minus tolerance for clock skew) or after the prompt fires (plus
+    // tolerance for ingest latency) can't be ours. The upper bound matters
+    // when a sibling launch of the same persona starts AFTER ours but
+    // before we get here — without it, max-ts wins picks the wrong row.
+    const LOWER_TOLERANCE_MS = 5000;
+    const UPPER_TOLERANCE_MS = 1000;
+    const lowerMs = startedAt - LOWER_TOLERANCE_MS;
+    const upperMs = Date.now() + UPPER_TOLERANCE_MS;
+    let bestSessionId;
+    // Prefer the stamp closest to our spawn time (smallest |ts - startedAt|),
+    // not the most recent. Same-persona concurrent launches can both fall
+    // inside the window; the one launched at our PID/time is the right one.
+    let bestDelta = Number.POSITIVE_INFINITY;
+    let pidMatched = false;
+    for (const row of rows) {
+        if (!row || typeof row !== 'object')
+            continue;
+        const r = row;
+        const sessionId = r.selector?.sessionId;
+        const enrichment = r.enrichment;
+        const ts = r.ts;
+        if (typeof sessionId !== 'string' || !enrichment || typeof ts !== 'string')
+            continue;
+        if (enrichment.persona !== persona)
+            continue;
+        if (enrichment.personaVersion !== personaVersion)
+            continue;
+        const tsMs = Date.parse(ts);
+        if (!Number.isFinite(tsMs))
+            continue;
+        if (tsMs < lowerMs || tsMs > upperMs)
+            continue;
+        // spawnerPid is the strongest discriminator — folded into enrichment
+        // by `buildLaunchMetadata` so it survives stamp ingest. When present
+        // on both sides, treat a mismatch as a hard reject and a match as
+        // sticky: once we've seen a pid-matched row, ignore unmatched ones
+        // even if they're closer in time.
+        const rowPid = enrichment.spawnerPid;
+        if (spawnerPid && typeof rowPid === 'string') {
+            if (rowPid !== spawnerPid)
+                continue;
+            if (!pidMatched) {
+                pidMatched = true;
+                bestDelta = Number.POSITIVE_INFINITY;
+                bestSessionId = undefined;
+            }
+        }
+        else if (pidMatched) {
+            // We already locked onto pid-matched candidates — skip non-pid rows.
+            continue;
+        }
+        const delta = Math.abs(tsMs - startedAt);
+        if (delta >= bestDelta)
+            continue;
+        bestDelta = delta;
+        bestSessionId = sessionId;
+    }
+    if (!bestSessionId)
+        return undefined;
+    return resolveTranscriptForSessionId(input.harness, input.sessionCwd, bestSessionId);
+}
+/**
+ * Map a harness session id to its on-disk transcript file. The directory
+ * is harness-conventional, but the filename pattern varies:
+ *   • claude    → `<sessionId>.jsonl` directly under the cwd-encoded subdir
+ *   • codex     → `rollout-<ts>-<sessionId>.jsonl` under a date-grouped subdir
+ *   • opencode  → file or filename containing the sessionId under `<projectHash>/`
+ *
+ * For codex/opencode we scan once and match by filename substring (cheap;
+ * the substring is a UUID-ish so collisions don't happen in practice).
+ */
+function resolveTranscriptForSessionId(harness, sessionCwd, sessionId) {
+    const home = homedir();
+    if (harness === 'claude') {
+        const encoded = sessionCwd.replace(/[\\/]+/g, '-');
+        const candidate = join(home, '.claude', 'projects', encoded, `${sessionId}.jsonl`);
+        return existsSync(candidate) ? candidate : undefined;
+    }
+    if (harness === 'codex') {
+        return findFileByNameSubstring(join(home, '.codex', 'sessions'), sessionId, ['.jsonl']);
+    }
+    if (harness === 'opencode') {
+        return findFileByNameSubstring(join(home, '.local', 'share', 'opencode', 'storage', 'session'), sessionId, ['.json']);
+    }
+    return undefined;
+}
+function findFileByNameSubstring(dir, needle, extensions) {
+    const wantsExt = (name) => extensions.some((ext) => name.endsWith(ext));
+    const visit = (cur, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            return undefined;
+        }
+        for (const entry of entries) {
+            const full = join(cur, entry.name);
+            if (entry.isDirectory()) {
+                if (depth < 3) {
+                    const found = visit(full, depth + 1);
+                    if (found)
+                        return found;
+                }
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!wantsExt(entry.name))
+                continue;
+            if (entry.name.includes(needle))
+                return full;
+        }
+        return undefined;
+    };
+    return visit(dir, 0);
+}
+/**
+ * Fallback locator when the burn-stamp ledger is unavailable or the
+ * just-ended session hasn't reconciled yet. Walks the harness's
+ * transcript dir and verifies each candidate's embedded cwd matches the
+ * captured session cwd. Every harness embeds the session cwd:
+ *   • claude    → `~/.claude/projects/<cwd-encoded>/<sessionId>.jsonl` —
+ *                 each entry carries `"cwd"`. The dir-name encoding
+ *                 replaces `/` with `-` and is itself a strong filter.
+ *   • codex     → `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` — first
+ *                 line is a `session_meta` event with `payload.cwd`.
+ *   • opencode  → `~/.local/share/opencode/storage/session/<projectHash>/<sessionId>.json`
+ *                 — top-level `directory` field on the session object.
+ *
+ * For each harness we walk the candidate dir, filter to files with
+ * mtime ≥ sessionStart, and confirm the embedded cwd matches the captured
+ * session cwd. Among matches we pick the most recently mtime'd. The cwd
+ * confirmation makes this robust to concurrent harness sessions — the
+ * caveat that previously applied to codex/opencode (most-recent-mtime
+ * could pick a sibling) goes away when we read the file's own cwd.
+ *
+ * Returns undefined when nothing matches; callers handle gracefully (the
+ * persona-improver accepts an empty transcript path).
+ */
+function findSessionTranscriptPath(input) {
+    if (!input.harness || !input.sessionCwd)
+        return undefined;
+    const startedAt = input.startedAt ?? 0;
+    const cwd = input.sessionCwd;
+    const home = homedir();
+    if (input.harness === 'claude') {
+        const encoded = cwd.replace(/[\\/]+/g, '-');
+        const projectDir = join(home, '.claude', 'projects', encoded);
+        // Within the cwd-encoded dir, all candidates already share the cwd —
+        // mtime is enough. We still verify the first-line `cwd` so a stale
+        // dir-name match can't smuggle in a wrong file.
+        return findFreshestMatchingTranscript({
+            dir: projectDir,
+            recursive: false,
+            extensions: ['.jsonl'],
+            sinceMs: startedAt,
+            sessionCwd: cwd,
+            readCwd: readCwdFromClaudeJsonl
+        });
+    }
+    if (input.harness === 'codex') {
+        return findFreshestMatchingTranscript({
+            dir: join(home, '.codex', 'sessions'),
+            recursive: true,
+            extensions: ['.jsonl'],
+            sinceMs: startedAt,
+            sessionCwd: cwd,
+            readCwd: readCwdFromCodexJsonl
+        });
+    }
+    if (input.harness === 'opencode') {
+        return findFreshestMatchingTranscript({
+            dir: join(home, '.local', 'share', 'opencode', 'storage', 'session'),
+            recursive: true,
+            extensions: ['.json'],
+            sinceMs: startedAt,
+            sessionCwd: cwd,
+            readCwd: readCwdFromOpencodeSession
+        });
+    }
+    return undefined;
+}
+/**
+ * Walk a candidate directory and pick the most recently modified file
+ * whose embedded cwd matches `sessionCwd`. Capped at depth 3 in
+ * recursive mode — codex/opencode group by date or project hash, never
+ * deeper. mtime gate eliminates files written before the session and
+ * keeps the scan cheap on large session stores.
+ */
+function findFreshestMatchingTranscript(opts) {
+    const wantsExt = (name) => opts.extensions.some((ext) => name.endsWith(ext));
+    let bestPath;
+    let bestMtime = -1;
+    const visit = (cur, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = join(cur, entry.name);
+            if (entry.isDirectory()) {
+                if (opts.recursive && depth < 3)
+                    visit(full, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!wantsExt(entry.name))
+                continue;
+            let s;
+            try {
+                s = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            const mtime = s.mtimeMs;
+            if (mtime < opts.sinceMs)
+                continue;
+            if (mtime <= bestMtime)
+                continue;
+            const cwd = opts.readCwd(full);
+            if (cwd !== opts.sessionCwd)
+                continue;
+            bestMtime = mtime;
+            bestPath = full;
+        }
+    };
+    visit(opts.dir, 0);
+    return bestPath;
+}
+/**
+ * Read up to `maxBytes` from `path` and report whether the file was
+ * larger. Callers that need to JSON.parse the whole file (opencode's
+ * single-object session record) gate on `truncated === false`; callers
+ * that scan line-by-line (claude/codex JSONL) ignore it.
+ */
+function readTranscriptHeader(path, maxBytes = 65536) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const buf = Buffer.alloc(maxBytes);
+        const n = readSync(fd, buf, 0, maxBytes, 0);
+        return {
+            text: buf.subarray(0, n).toString('utf8'),
+            truncated: n >= maxBytes
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* swallow — fd already invalid */
+            }
+        }
+    }
+}
+/** Claude JSONL: `cwd` appears on most entries; the first line that has it wins. */
+function readCwdFromClaudeJsonl(path) {
+    const header = readTranscriptHeader(path);
+    if (!header)
+        return undefined;
+    for (const line of header.text.split('\n')) {
+        if (!line.includes('"cwd"'))
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.cwd === 'string')
+                return obj.cwd;
+        }
+        catch {
+            // partial last line — skip
+        }
+    }
+    return undefined;
+}
+/** Codex JSONL: line 1 is `session_meta` with `payload.cwd`. */
+function readCwdFromCodexJsonl(path) {
+    const header = readTranscriptHeader(path);
+    if (!header)
+        return undefined;
+    const firstNewline = header.text.indexOf('\n');
+    const firstLine = firstNewline === -1 ? header.text : header.text.slice(0, firstNewline);
+    try {
+        const obj = JSON.parse(firstLine);
+        const cwd = obj.payload?.cwd;
+        return typeof cwd === 'string' ? cwd : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Opencode session JSON: top-level `directory` field. Opencode writes
+ * the whole session as a single JSON object, so a truncated read can't
+ * be parsed — the closing brace is missing. Re-read the full file when
+ * `truncated` flips, since real opencode session records are typically
+ * a few hundred bytes (summary, directory, ids) but we don't want to
+ * silently miss a larger one.
+ */
+function readCwdFromOpencodeSession(path) {
+    const header = readTranscriptHeader(path);
+    if (!header)
+        return undefined;
+    let body = header.text;
+    if (header.truncated) {
+        try {
+            body = readFileSync(path, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    try {
+        const obj = JSON.parse(body);
+        return typeof obj.directory === 'string' ? obj.directory : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Run the persona-improver in headless one-shot mode against the given
+ * persona + transcript. Returns the parsed proposals file on success.
+ *
+ * Throws on: missing improver in catalog, harness binary not on PATH,
+ * non-zero harness exit, or unparseable proposals JSON. Caller is expected
+ * to surface the message and skip the apply step.
+ */
+async function runPersonaImprover(args) {
+    const improverSpec = personaCatalog['persona-improvement'];
+    if (!improverSpec) {
+        throw new Error('built-in persona "persona-improver" is not registered in the catalog');
+    }
+    const tier = 'best-value';
+    const selection = buildSelection(improverSpec, tier, 'repo');
+    const ctx = useRunnableSelection(selection);
+    const taskLines = [
+        'Improve this local persona from one finished session. The CLI will read your proposals JSON and walk the user through accept/deny.',
+        `PERSONA_FILE_PATH=${args.personaFilePath}`,
+        `SESSION_TRANSCRIPT_PATH=${args.transcriptPath}`,
+        `PROPOSALS_OUTPUT_PATH=${args.proposalsOutputPath}`
+    ];
+    const result = await ctx.sendMessage(taskLines.join('\n'), {
+        inputs: {
+            PERSONA_FILE_PATH: args.personaFilePath,
+            SESSION_TRANSCRIPT_PATH: args.transcriptPath,
+            PROPOSALS_OUTPUT_PATH: args.proposalsOutputPath
+        },
+        timeoutSeconds: selection.runtime.harnessSettings.timeoutSeconds
+    });
+    if (result.status !== 'completed' || (result.exitCode !== null && result.exitCode !== 0)) {
+        throw new Error(`improver exited with status=${result.status}, code=${result.exitCode ?? 'null'}.${result.stderr ? ` stderr: ${result.stderr.slice(0, 400)}` : ''}`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(args.proposalsOutputPath, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`improver did not write proposals file at ${args.proposalsOutputPath}: ${err.message}`);
+    }
+    return parseProposals(raw);
+}
+export function parseProposals(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`proposals file is not valid JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('proposals file must be a JSON object');
+    }
+    const obj = parsed;
+    const proposalsArr = Array.isArray(obj.proposals) ? obj.proposals : [];
+    const proposals = [];
+    for (const [idx, item] of proposalsArr.entries()) {
+        if (!item || typeof item !== 'object') {
+            throw new Error(`proposals[${idx}] must be an object`);
+        }
+        const p = item;
+        if (typeof p.id !== 'string' || !p.id.trim()) {
+            throw new Error(`proposals[${idx}].id must be a non-empty string`);
+        }
+        if (typeof p.summary !== 'string' || !p.summary.trim()) {
+            throw new Error(`proposals[${idx}].summary must be a non-empty string`);
+        }
+        if (typeof p.rationale !== 'string') {
+            throw new Error(`proposals[${idx}].rationale must be a string`);
+        }
+        if (!Array.isArray(p.patches) || p.patches.length === 0) {
+            throw new Error(`proposals[${idx}].patches must be a non-empty array`);
+        }
+        const patches = [];
+        for (const [pidx, rawPatch] of p.patches.entries()) {
+            if (!rawPatch || typeof rawPatch !== 'object') {
+                throw new Error(`proposals[${idx}].patches[${pidx}] must be an object`);
+            }
+            const rp = rawPatch;
+            if (typeof rp.path !== 'string' || !rp.path.trim()) {
+                throw new Error(`proposals[${idx}].patches[${pidx}].path must be a non-empty string`);
+            }
+            if (rp.op !== 'set' && rp.op !== 'append') {
+                throw new Error(`proposals[${idx}].patches[${pidx}].op must be "set" or "append"`);
+            }
+            const patch = { path: rp.path, op: rp.op, value: rp.value };
+            assertAllowedImproverPatch(patch, `proposals[${idx}].patches[${pidx}]`);
+            patches.push(patch);
+        }
+        proposals.push({
+            id: p.id,
+            summary: p.summary,
+            rationale: p.rationale,
+            patches
+        });
+    }
+    return {
+        personaId: typeof obj.personaId === 'string' ? obj.personaId : '',
+        personaFilePath: typeof obj.personaFilePath === 'string' ? obj.personaFilePath : '',
+        transcriptPath: typeof obj.transcriptPath === 'string' ? obj.transcriptPath : '',
+        proposals
+    };
+}
+/**
+ * Walk improver proposals one-by-one over the TTY. Returns only the
+ * accepted proposals; the caller applies the patches. Supports:
+ *   y / n — accept or skip the current proposal
+ *   a     — accept this and all remaining proposals
+ *   q     — quit without accepting any further proposals (already-accepted ones stay)
+ *
+ * On a non-TTY we shouldn't have reached this point (caller checks),
+ * but if we do, return an empty list so nothing is auto-applied.
+ */
+function walkProposalsInteractive(file) {
+    if (!process.stdin.isTTY)
+        return [];
+    const accepted = [];
+    const total = file.proposals.length;
+    let acceptAll = false;
+    for (let i = 0; i < total; i++) {
+        const proposal = file.proposals[i];
+        process.stderr.write(`\n[${i + 1}/${total}] ${proposal.summary}\n`);
+        if (proposal.rationale) {
+            process.stderr.write(`  why: ${proposal.rationale}\n`);
+        }
+        for (const patch of proposal.patches) {
+            const preview = formatPatchPreview(patch);
+            process.stderr.write(`  ${preview}\n`);
+        }
+        if (acceptAll) {
+            accepted.push(proposal);
+            process.stderr.write('  → accepted (accept-all)\n');
+            continue;
+        }
+        // 'n' is first so empty Enter defaults to skip (matches the
+        // [y/N] default-no convention used by promptYesNoSync at the
+        // session-end "auto-improve?" prompt). If the user hammers Enter
+        // through a stack of proposals they get a no-op outcome, not an
+        // unintended file mutation.
+        const choice = readSingleCharChoice('  accept? [y/N/a/q] ', ['n', 'y', 'a', 'q']);
+        if (choice === 'y') {
+            accepted.push(proposal);
+        }
+        else if (choice === 'a') {
+            accepted.push(proposal);
+            acceptAll = true;
+        }
+        else if (choice === 'q') {
+            process.stderr.write('  → quit; no further proposals will be reviewed.\n');
+            break;
+        }
+        // 'n' (and bare Enter) falls through with no accept.
+    }
+    return accepted;
+}
+/**
+ * Render a one-line patch preview. Truncates long string values so a
+ * multi-paragraph systemPrompt rewrite doesn't dominate the screen.
+ */
+function formatPatchPreview(patch) {
+    const op = patch.op === 'append' ? '+= ' : '= ';
+    const valueStr = formatPatchValue(patch.value);
+    return `${patch.path} ${op}${valueStr}`;
+}
+function formatPatchValue(value) {
+    if (typeof value === 'string') {
+        const condensed = value.replace(/\s+/g, ' ').trim();
+        return condensed.length > 100 ? `"${condensed.slice(0, 97)}..."` : `"${condensed}"`;
+    }
+    try {
+        const json = JSON.stringify(value);
+        if (json === undefined)
+            return '<undefined>';
+        return json.length > 120 ? `${json.slice(0, 117)}...` : json;
+    }
+    catch {
+        return '<unserializable>';
+    }
+}
+/**
+ * Read a single-character choice from stdin synchronously, looping on
+ * invalid input. Empty Enter (no character) returns the first option in
+ * `valid` — callers should put the safe / default-no answer first.
+ *
+ * Test seam: callers can inject `read` so the prompt is exercisable
+ * without a real TTY (mirrors `promptYesNoSync`).
+ */
+export function readSingleCharChoice(prompt, valid, opts = {}) {
+    const write = opts.write ?? ((chunk) => {
+        process.stderr.write(chunk);
+    });
+    for (;;) {
+        write(prompt);
+        const line = opts.read ? opts.read() : readLineFromStdinSync();
+        const trimmed = (line ?? '').trim().toLowerCase();
+        if (trimmed.length === 0)
+            return valid[0];
+        const ch = trimmed[0];
+        if (valid.includes(ch))
+            return ch;
+        write(`  invalid choice; expected one of: ${valid.join(', ')}\n`);
+    }
+}
+/**
+ * Apply accepted patches to the persona JSON on disk. Reads, mutates the
+ * parsed object, writes back with two-space indent + trailing newline
+ * (matches existing /personas style). Throws on unwriteable file or
+ * unsupported patch op/path resolution.
+ */
+export function applyAcceptedPatches(personaFilePath, accepted) {
+    const raw = readFileSync(personaFilePath, 'utf8');
+    const json = JSON.parse(raw);
+    for (const proposal of accepted) {
+        for (const patch of proposal.patches) {
+            applyPatchInPlace(json, patch);
+        }
+    }
+    writeFileSync(personaFilePath, JSON.stringify(json, null, 2) + '\n', 'utf8');
+}
+function applyPatchInPlace(root, patch) {
+    // Re-run the allowlist + prototype-segment guard at apply time, not
+    // just at parse time. Belt-and-braces: a patch list constructed by a
+    // future caller that bypasses parseProposals can't smuggle a
+    // disallowed path past this point either.
+    assertAllowedImproverPatch(patch, `applyPatchInPlace`);
+    const segments = patch.path.split('.').filter((s) => s.length > 0);
+    let cursor = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        const next = cursor[seg];
+        if (next === undefined || next === null) {
+            const created = {};
+            cursor[seg] = created;
+            cursor = created;
+            continue;
+        }
+        if (typeof next !== 'object' || Array.isArray(next)) {
+            throw new Error(`patch path "${patch.path}": "${seg}" is not an object`);
+        }
+        cursor = next;
+    }
+    const finalSeg = segments[segments.length - 1];
+    if (patch.op === 'append') {
+        const existing = cursor[finalSeg];
+        if (existing === undefined) {
+            cursor[finalSeg] = [patch.value];
+            return;
+        }
+        if (!Array.isArray(existing)) {
+            throw new Error(`patch path "${patch.path}": cannot append to non-array`);
+        }
+        existing.push(patch.value);
+        return;
+    }
+    // op === 'set'
+    cursor[finalSeg] = patch.value;
+}
 /**
  * Enumerate persona candidates for the picker. Local overrides win over the
  * built-in catalog when ids collide; the picker only needs the projection