From 39ae62851bce3e4f15df5a9ec5d0f8071aad821f Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Sun, 12 Jul 2026 21:47:23 -0400
Subject: [PATCH 1/5] feat(cli): warm fast path spawns the harness in ~20ms;
 10x faster cold launches

agent <persona> launches now keep the session's sandbox mount warm and
record a digest-validated launch plan. The next launch of the same
selector validates the plan with a handful of stats (~20ms including
node boot), claims the warm mount by atomic rename, and spawns the
harness immediately; the heavy CLI module loads afterward, reattaches
the mount with the previous session's autosync state, and reconciles
while the harness boots. Any change to the persona, source dirs,
skills, dotfiles, or pinned env falls back to the full path
(AGENTWORKFORCE_NO_FAST=1 disables).

Cold launches populate mounts from git ls-files (local-mount
population: 'auto'), start autosync from population-seeded state, skip
the npm cache when mirroring skills, and lazy-load cloud subcommand
handlers. In the relay repo: 26s -> 2.5s cold, ~20ms warm; teardown
11s -> <1s.

Requires @relayfile/local-mount ^0.11.0 (release upstream first).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CHANGELOG.md                         |   25 +
 packages/cli/package.json            |    2 +-
 packages/cli/src/cli-impl.ts         | 5326 ++++++++++++++++++++++++++
 packages/cli/src/cli.test.ts         |    2 +-
 packages/cli/src/cli.ts              | 4751 +----------------------
 packages/cli/src/fast-launch.test.ts |  169 +
 packages/cli/src/fast-launch.ts      |  313 ++
 7 files changed, 5854 insertions(+), 4734 deletions(-)
 create mode 100644 packages/cli/src/cli-impl.ts
 create mode 100644 packages/cli/src/fast-launch.test.ts
 create mode 100644 packages/cli/src/fast-launch.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f69958ae..f7e09704 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,3 +7,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+### Added
+
+- `@agentworkforce/cli`: warm fast path for `agent <persona>`. Repeat
+  launches of the same persona in the same repo reuse the previous session's
+  sandbox mount plus a digest-validated launch plan, spawning the harness in
+  tens of milliseconds; the mount reconciles with the repo in the background
+  while the harness boots. Any change to the persona, its source dirs,
+  skills, dotfiles, or relevant environment falls back to the full launch.
+  Disable with `AGENTWORKFORCE_NO_FAST=1`. Launch-phase timings are printable
+  with `AGENTWORKFORCE_PERF=1`.
+
+### Changed
+
+- `@agentworkforce/cli`: cold launches are an order of magnitude faster.
+  Sandbox mounts populate from `git ls-files` (`@relayfile/local-mount`
+  `population: 'auto'`), so gitignored trees never get mirrored or rescanned;
+  autosync starts from population-seeded state instead of re-reading every
+  file pair; the skill-cache mirror no longer copies the install-time npm
+  cache into the mount; and cloud subcommand handlers load lazily off the
+  launch path. In the relay repo, launch-to-harness went from ~26s to ~2.5s
+  cold and ~20ms warm, and session teardown from ~11s to under 1s.
+- `@agentworkforce/cli`: requires `@relayfile/local-mount` ^0.11.0
+  (git-list population, `attachMount`, exported autosync state, and the
+  external-teardown safety guard).
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 3c2fe06c..bf73b6a1 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -16,7 +16,7 @@
     "@agentworkforce/runtime": "workspace:*",
     "@agentworkforce/workload-router": "workspace:*",
     "@relayburn/sdk": "^2.5.2",
-    "@relayfile/local-mount": "^0.7.24",
+    "@relayfile/local-mount": "^0.11.0",
     "ora": "^9.4.0"
   },
   "repository": {
diff --git a/packages/cli/src/cli-impl.ts b/packages/cli/src/cli-impl.ts
new file mode 100644
index 00000000..24650c1e
--- /dev/null
+++ b/packages/cli/src/cli-impl.ts
@@ -0,0 +1,5326 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import {
+  appendFileSync,
+  closeSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  type Dirent
+} 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 {
+  buildCleanupArtifacts,
+  buildInstallArtifacts,
+  buildInteractiveSpec,
+  buildNonInteractiveSpec,
+  buildUpstreamRecordsFromCacheDir,
+  computeSkillCacheFingerprint,
+  detectHarnesses,
+  detectSkillUpstreamDrift,
+  formatDropWarnings,
+  HARNESS_VALUES,
+  isSkillCacheValid,
+  isUpstreamCheckDue,
+  materializeSkills,
+  MissingPersonaInputError,
+  parseCheckInterval,
+  PERSONA_TAGS,
+  readSkillCacheMarker,
+  renderPersonaInputs,
+  resolveAiMemory,
+  resolveMcpServersLenient,
+  resolvePersonaInputs,
+  resolveSidecar,
+  resolveSkillCacheDir,
+  resolveStringMapLenient,
+  updateSkillCacheMarkerUpstream,
+  writeSkillCacheMarker,
+  type Harness,
+  type HarnessAvailability,
+  type InteractiveSpec,
+  type NonInteractiveSpec,
+  type PersonaMount,
+  type AiHistMcpConfig,
+  type PersonaSelection,
+  type PersonaSpec,
+  type PersonaTag,
+  type RelayMcpConfig,
+  type SidecarMdMode,
+  type SkillMaterializationPlan
+} from '@agentworkforce/persona-kit';
+import {
+  claudeMcpConfigHasRelayOverride,
+  codexExistingArgs,
+  injectClaudeAgentRelayMcpConfig,
+  injectCodexSubcommandArgs,
+  resolveAgentRelayBrokerMcpArgs,
+  resolveRelayMcpFromEnv as resolveRelayMcpFromEnvShared
+} from '@agentworkforce/runtime';
+import {
+  listBuiltInPersonas,
+  personaCatalog,
+  routingProfiles
+} from '@agentworkforce/workload-router';
+import {
+  attachMount,
+  createMount,
+  readAgentDotfiles,
+  type AutoSyncHandle,
+  type FileState,
+  type MountHandle
+} from '@relayfile/local-mount';
+import {
+  deleteLaunchPlan,
+  statDigestOf,
+  warmMountDir,
+  writeLaunchPlan,
+  type FastLaunch,
+  type LaunchPlan,
+  type StatDigest,
+  LAUNCH_PLAN_SCHEMA_VERSION
+} from './fast-launch.js';
+import ora, { type Ora } from 'ora';
+// Cloud-facing subcommand handlers (deploy/invoke/runs/destroy/integrations/
+// deployments) are imported lazily at dispatch: their module graphs pull in
+// @agent-relay/cloud and friends, which costs hundreds of milliseconds that
+// the hot `agent <persona>` launch path must not pay.
+import {
+  startLaunchMetadataRecording,
+  type LaunchMetadataRun
+} from './launch-metadata.js';
+import { createLogger } from './logger.js';
+import {
+  buildPersonaSourceDirectories,
+  defaultCwdPersonaDir,
+  formatPersonaSourceLabel,
+  loadLocalPersonas,
+  loadPersonaSourceConfig,
+  normalizePersonaDir,
+  savePersonaSourceConfig,
+  type PersonaSource
+} from './local-personas.js';
+import { installPersonas, type PersonaInstallResult } from './persona-install.js';
+import { runPersonaCompileCommand } from './persona-compile.js';
+import { pickPersona, type PickCandidate, type PickResult } from './persona-picker.js';
+import { recordRecent, loadRecents, runPersonaPickerTui, type TuiCandidate } from './persona-tui.js';
+import { runTrigger } from './trigger-command.js';
+
+const launchMetadataLog = createLogger('launch-metadata');
+
+/**
+ * Launch-phase timing marks, enabled with AGENTWORKFORCE_PERF=1. Each line is
+ * `[perf] +<ms since process start> <label>` on stderr — cheap enough to keep
+ * in the launch path permanently, and the only way to see where a slow
+ * `agentworkforce agent <persona>` spends its time in the field.
+ */
+const PERF_ENABLED = process.env.AGENTWORKFORCE_PERF === '1';
+export function perfMark(label: string): void {
+  if (!PERF_ENABLED) return;
+  process.stderr.write(`[perf] +${performance.now().toFixed(1)}ms ${label}\n`);
+}
+
+const USAGE = `Usage: agentworkforce <command> [args...]
+
+Run with no arguments inside a TTY to open an interactive persona picker —
+the top 3 most recently used personas are shown first, and typing fuzzy-
+searches across persona names and descriptions. Each row's SOURCE column
+is one of: built-in (bundled), cwd (./.agentworkforce/workforce/personas),
+personal (~/.agentworkforce/workforce/personas), or dir:N (configured).
+
+Commands:
+  create [flags]     Opens persona-maker for creating a new
+                      persona, with target path passed as persona inputs.
+                      Flags:
+                        --save-in-directory=<target>
+                                            Storage target: cwd, user, dir:n,
+                                            library, or an explicit path.
+                                            Default: cwd
+                                            (<cwd>/.agentworkforce/workforce/personas);
+                                            the directory is created if missing.
+                                            Override via this flag, or pin a
+                                            different default with --save-default.
+                        --save-default      Persist --save-in-directory as
+                                            defaultCreateTarget in
+                                            ~/.agentworkforce/workforce/config.json.
+                        --install-in-repo   Same behavior as agent.
+                        --no-launch-metadata
+                                            Same behavior as agent.
+  agent [flags] <persona>
+                      Run a persona. Drops into an interactive harness session.
+
+                      Flags:
+                        --install-in-repo   Disengage the sandbox mount and
+                                            install skills into the repo's
+                                            harness-conventional directory
+                                            (.claude/skills, .opencode/skills,
+                                            .agents/skills, .grok/skills, etc.).
+                                            By default, interactive harness
+                                            sessions run inside a
+                                            @relayfile/local-mount sandbox so
+                                            npx prpm install / npx skills add
+                                            writes never touch the real repo
+                                            and CLAUDE.md / .claude / .mcp.json
+                                            (or AGENTS.md / skill roots for
+                                            non-claude harnesses) are hidden
+                                            from the session.
+                        --no-launch-metadata
+                                            Disable launch metadata recording.
+                                            Also disabled by
+                                            AGENTWORKFORCE_LAUNCH_METADATA=0.
+                        --no-skill-cache    Bypass the persistent skill-install
+                                            cache (under
+                                            ~/.agentworkforce/workforce/cache/plugins/)
+                                            and install fresh into a per-session
+                                            dir. Also disabled by
+                                            AGENTWORKFORCE_NO_SKILL_CACHE=1.
+                        --refresh-skills    Force a fresh install of the skill
+                                            cache entry for this persona,
+                                            overwriting any existing cache dir.
+                        --check-upstream    Force an upstream drift check this
+                                            launch (prpm version / GitHub blob
+                                            SHA) regardless of the TTL. A drifted
+                                            skill triggers a reinstall.
+                        --no-check-upstream Skip the upstream drift check this
+                                            launch regardless of the TTL.
+                                            Interval is otherwise 24h, tunable
+                                            via
+                                            AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL
+                                            (e.g. 24h, 30m, 0=always,
+                                            never=disable).
+
+                      Repeat launches of the same persona in the same repo
+                      take a warm fast path: the previous session's sandbox
+                      mount is kept (under
+                      ~/.agentworkforce/workforce/cache/warm-mounts/) along
+                      with a validated launch plan, so the harness spawns in
+                      tens of milliseconds and the mount reconciles with the
+                      repo in the background while the harness boots. Any
+                      change to the persona, its sources, skills, dotfiles,
+                      or relevant environment falls back to the full launch.
+                      Disable with AGENTWORKFORCE_NO_FAST=1.
+                        --dry-run           Validate the persona without
+                                            spawning the harness or burning
+                                            tier-model tokens. Three checks:
+                                            (1) sidecar — claudeMd / agentsMd
+                                            filename refs are readable;
+                                            (2) harness spec — permissions /
+                                            mcpServers / harness-settings
+                                            shape is accepted by the harness
+                                            translator; (3) skills — each
+                                            \`skills[].source\` is run through
+                                            its real installer (npx skills
+                                            add / npx prpm install) inside a
+                                            fresh temp dir, with per-skill
+                                            pass/fail reporting. Use this in
+                                            the persona-author loop to catch
+                                            hallucinated skill names and
+                                            malformed config before a persona
+                                            ships. Temp dir is removed on
+                                            success, kept on failure for
+                                            inspection.
+  list [flags]        List available personas from the cascade (cwd →
+                      configured persona dirs → library). Flags:
+                        --deployments                 list deployed cloud agents
+                        --json                        emit JSON instead of a table
+                        --filter-harness <harness>    only show this harness
+                                                      (${HARNESS_VALUES.join(' | ')})
+                        --filter-tag <tag>            only show personas carrying this tag
+                                                      (free-form; common built-in tags: ${PERSONA_TAGS.join(' | ')})
+                        --no-display-description      hide the DESCRIPTION column
+  show <persona>      Print the fully-resolved spec for a single persona,
+                      including which cascade layer defined it (cwd, user,
+                      dir:<n>, library). Flags:
+                        --json        emit the resolved PersonaSpec as JSON
+  persona compile <path/to/persona.ts>
+                      Compile a typed persona.ts authoring file to sibling
+                      persona.json after validating it with persona-kit.
+  install [flags] <pkg|path>
+                      Copy persona JSON files from an npm package or local
+                      package directory into
+                      <cwd>/.agentworkforce/workforce/personas/. Flags:
+                        --persona <id>  install only the matching persona id;
+                                        repeat to install multiple
+                        --overwrite     replace existing target files
+  sources list [--json]
+                      List persona source directories in cascade order.
+  sources add <dir> [--position <n>]
+                      Add a configurable persona source directory. Position is
+                      1-based among configurable dirs after the fixed cwd dir.
+  sources remove <dir|n>
+                      Remove a configurable persona source directory by path or
+                      1-based configurable position.
+  integrations [provider] [--all] [--json]
+                      Discover workspace integrations, connection status, and
+                      known trigger events.
+  trigger <agent-name-or-id> [flags]
+                      Manually fire an active deployed persona for testing.
+                      The selector accepts agent id, compact agent id,
+                      deployed name, persona slug, or persona id. Flags:
+                        --workspace <name>  Workforce workspace; defaults to
+                                            the active workspace
+                        --cloud-url <url>   Override the cloud base URL
+                        --json              Emit JSON
+                        --no-prompt         Fail instead of prompting for login
+  harness check       Probe which harnesses (${HARNESS_VALUES.join(', ')}) are
+                      installed and runnable on this machine.
+  pick "<task>"       Pick the best-fit persona for a free-text task description
+                      using a cheap LLM call (Claude Haiku via the local
+                      \`claude\` CLI). Prints the matched persona id to stdout
+                      on success. On low confidence, prompts (TTY) to launch
+                      persona-maker with the task as input, or exits non-zero
+                      (non-TTY) with a hint.
+                      Exit codes: 0 match, 2 no match, 3 picker unavailable.
+  deploy <persona-path> [flags]
+                      Deploy a persona as a managed agent. <persona-path> may
+                      be prebuilt persona.json or authored persona.ts/js.
+                      Modes:
+                        --mode dev          run the persona locally (default if
+                                            no Daytona/workspace creds resolve)
+                        --mode sandbox      run inside a Daytona sandbox
+                                            (default when creds resolve)
+                        --mode cloud        POST persona + bundle to the
+                                            workforce cloud workspace
+                      Flags:
+                        --workspace <name>  pick a non-default workspace
+                        --no-connect        skip integration-connect prompts
+                                            (fail if any integration is missing)
+                        --byo-sandbox       force BYO Daytona auth
+                        --detach            background the runner instead of
+                                            streaming logs in the foreground
+                        --bundle-out <dir>  emit the bundle to <dir> and exit
+                                            without launching
+                        --dry-run           validate the persona; no side effects
+                        --cloud-url <url>   override the workforce cloud URL
+                        --input KEY=value   override a declared persona input
+                                            (repeat for multiple)
+  invoke <persona-path> --fixture <file> [flags]
+                      Simulate an invocation: run the persona's handler
+                      against fixture event envelope(s) with every external
+                      side effect recorded, NOT executed. Emits a
+                      Cloud-compatible run record (origin "local_dry_run")
+                      to stdout. Distinct from \`deploy --dry-run\`, which
+                      validates without invoking the handler.
+                      Flags:
+                        --fixture <file>    JSON envelope, JSON array, or
+                                            NDJSON of raw gateway envelopes
+                        --output <file>     write the run record to a file
+                        --input KEY=value   override a declared persona input
+                        --seed PATH=file    seed the simulated filesystem
+                        --workspace <id>    workspace id for the simulated ctx
+                        --scaffold <type>   emit a fixture skeleton for an
+                                            event type instead of running
+                                            (no persona needed)
+  runs export <runId> [flags]
+                      Export the gateway envelope cloud delivered to a run
+                      as a replayable invoke fixture. Flags:
+                        --agent <selector>  agentId/deployedName owning the
+                                            run (otherwise all are checked)
+                        --fixture <file>    write the fixture to a file
+  deployments list    List deployed cloud agents in the active workspace.
+  deployments logs    Show structured logs for a deployed cloud agent.
+  destroy <persona-or-agent-id> [flags]
+                      Tear down a deployed agent: cancel all schedules and
+                      mark the agent as destroyed in the workspace. Accepts
+                      either a persona JSON path (resolved to an agent id
+                      via the workspace's agents index) or a literal agent
+                      UUID.
+                      Flags:
+                        --workspace <id>    pick a non-default workspace
+                        --cloud-url <url>   override the workforce cloud URL
+                        --no-prompt         fail instead of opening the
+                                            browser login flow
+                      Exit codes: 0 destroyed, 2 not found / already
+                      destroyed, 1 any other error.
+  login               Connect this machine to a workforce workspace using
+                      browser OAuth and store a workspace token.
+  logout              Clear browser OAuth auth and the stored workspace token.
+
+Options:
+  -h, --help          Show this help text.
+  -v, --version       Print the agentworkforce version.
+
+Local personas cascade: <cwd>/.agentworkforce/workforce/personas/*.json → configured persona dirs → repo library.
+Each layer only needs to specify fields it overrides; everything else inherits
+from the next lower layer. "extends" explicitly names a base; omit it and the
+loader implicitly inherits from the same-id persona below. By default the only
+configured persona dir is ~/.agentworkforce/workforce/personas.
+
+Examples:
+  agentworkforce create
+  agentworkforce create --save-in-directory=user
+  agentworkforce install @agentworkforce/personas-core --persona code-reviewer
+  agentworkforce agent code-reviewer
+  agentworkforce agent my-reviewer
+  agentworkforce list
+  agentworkforce show code-reviewer
+  agentworkforce install @agentrelay/personas --persona relay-orchestrator
+  agentworkforce install ./local-personas --overwrite
+  agentworkforce sources list
+  agentworkforce sources add ../my-personas --position 1
+  agentworkforce integrations --all
+  agentworkforce harness check
+  agentworkforce pick "review this PR for security issues"
+  agentworkforce agent "$(agentworkforce pick "fix the flaky test in foo.test.ts")"
+  agentworkforce deploy ./personas/weekly-digest.json --mode cloud
+  agentworkforce deploy ./personas/weekly-digest.json --mode sandbox --input TOPIC="Deploy v1"
+  agentworkforce destroy ./personas/weekly-digest.json
+  agentworkforce destroy 11111111-2222-4333-8444-555555555555
+  agentworkforce login
+`;
+
+function die(msg: string, withUsage = true): never {
+  process.stderr.write(`${msg}\n`);
+  if (withUsage) process.stderr.write(`\n${USAGE}`);
+  process.exit(1);
+}
+
+function readPackageVersion(): string {
+  const pkg = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+  ) as { version?: unknown };
+  if (typeof pkg.version !== 'string' || !pkg.version) {
+    throw new Error('Could not read @agentworkforce/cli package version.');
+  }
+  return pkg.version;
+}
+
+export const CLI_VERSION = readPackageVersion();
+export const CREATE_SELECTOR = 'persona-maker';
+
+const CREATE_INPUT_TARGET_DIR = 'TARGET_DIR';
+const CREATE_INPUT_CREATE_MODE = 'CREATE_MODE';
+
+const local = loadLocalPersonas();
+for (const warning of local.warnings) {
+  process.stderr.write(`warning: ${warning}\n`);
+}
+
+type ResolvedTarget =
+  | { kind: 'repo'; source: 'library'; spec: PersonaSpec }
+  | { kind: 'local'; source: PersonaSource; spec: PersonaSpec };
+
+interface KnownPersonaRow {
+  name: string;
+  description: string;
+}
+
+function collectKnownPersonas(): KnownPersonaRow[] {
+  const byName = new Map<string, KnownPersonaRow>();
+  for (const spec of local.byId.values()) {
+    byName.set(spec.id, {
+      name: spec.id,
+      description: spec.description
+    });
+  }
+  for (const spec of listBuiltInPersonas()) {
+    if (byName.has(spec.id)) continue;
+    byName.set(spec.id, {
+      name: spec.id,
+      description: spec.description
+    });
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function formatNameDescriptionTable(rows: readonly KnownPersonaRow[]): string {
+  const headers: KnownPersonaRow = {
+    name: 'NAME',
+    description: 'DESCRIPTION'
+  };
+  const rendered = rows.map((r) => ({
+    name: r.name,
+    description: r.description.replace(/\s+/g, ' ').trim()
+  }));
+  const nameWidth = Math.max(
+    headers.name.length,
+    ...rendered.map((r) => r.name.length)
+  );
+  const termWidth =
+    process.stderr.isTTY && typeof process.stderr.columns === 'number'
+      ? process.stderr.columns
+      : 120;
+  const descBudget = Math.max(
+    headers.description.length,
+    Math.max(32, termWidth - nameWidth - 3)
+  );
+  const truncate = (text: string) =>
+    text.length <= descBudget
+      ? text
+      : `${text.slice(0, Math.max(1, descBudget - 3)).trimEnd()}...`;
+  const line = (row: KnownPersonaRow) =>
+    `${row.name.padEnd(nameWidth)} | ${truncate(row.description)}`.trimEnd();
+  return [line(headers), ...rendered.map(line)].join('\n');
+}
+
+function resolveSpec(key: string): ResolvedTarget['spec'] | { error: string } {
+  const localSpec = local.byId.get(key);
+  if (localSpec) return localSpec;
+  const catalogAsIntent = (personaCatalog as Record<string, PersonaSpec | undefined>)[key];
+  if (catalogAsIntent) return catalogAsIntent;
+  const byId = listBuiltInPersonas().find((p) => p.id === key);
+  if (byId) return byId;
+
+  const packHint =
+    'Optional first-party personas are installed from packs, for example:\n' +
+    '  agentworkforce install @agentworkforce/personas-core\n' +
+    '  agentworkforce install @agentrelay/personas';
+  return {
+    error: `Unknown persona "${key}". Known personas:\n${formatNameDescriptionTable(collectKnownPersonas())}\n\n${packHint}`
+  };
+}
+
+function parseSelector(sel: string): ResolvedTarget {
+  // Catch legacy `@<tier>` selectors and point users at the new selector form.
+  // Tiers were removed; a persona's runtime fields now live at the top level.
+  const at = sel.indexOf('@');
+  if (at !== -1) {
+    const suffix = sel.slice(at + 1);
+    die(
+      `@<tier> selectors were removed; tiers are no longer part of the persona shape. ` +
+        `Use 'agentworkforce agent ${sel.slice(0, at)}' instead (drop "@${suffix}").`,
+      false
+    );
+  }
+  const key = sel;
+  if (!key) die('Missing persona name');
+  const result = resolveSpec(key);
+  if ('error' in result) die(result.error, false);
+  const kind = local.byId.has(key) ? 'local' : 'repo';
+  if (kind === 'local') {
+    return { kind, source: local.sources.get(result.id) ?? 'cwd', spec: result };
+  }
+  return { kind, source: 'library', spec: result };
+}
+
+/**
+ * Resolve the `<harness>` placeholder used in persona systemPrompts.
+ * Personas embed `<harness>` inside example install commands (e.g.
+ * `npx prpm install <ref> --as <harness>`) so the docstring stays
+ * harness-agnostic in source. The active harness is known at selection
+ * time, so swap it in here to give the model a concrete command.
+ *
+ * Exported for test coverage. Only `<harness>` is resolved today; other
+ * angle-bracketed tokens in the prompt (e.g. `<ref>`, `<repo-url>`,
+ * `<query>`) are deliberately left as LLM-facing placeholders.
+ */
+export function resolveSystemPromptPlaceholders(prompt: string, harness: Harness): string {
+  return prompt.replaceAll('<harness>', harness);
+}
+
+function buildSelection(spec: PersonaSpec, kind: 'repo' | 'local'): PersonaSelection {
+  // An interactive `agentworkforce agent` run spawns a harness session, which
+  // requires harness/model/systemPrompt. These are optional on the spec only
+  // for handler-style (onEvent) personas, which are deployed — not run
+  // interactively — so reject them here with a pointed error.
+  if (!spec.harness || !spec.model || spec.systemPrompt === undefined) {
+    throw new Error(
+      `persona "${spec.id}" cannot be run interactively: it omits ${[
+        !spec.harness && 'harness',
+        !spec.model && 'model',
+        spec.systemPrompt === undefined && 'systemPrompt'
+      ]
+        .filter(Boolean)
+        .join(', ')}. Handler-style personas (onEvent) are deployed via \`agentworkforce deploy\`, not run with \`agentworkforce agent\`.`
+    );
+  }
+  const systemPrompt = resolveSystemPromptPlaceholders(spec.systemPrompt, spec.harness);
+  const sidecar = resolveSidecar(spec);
+  // Built-in personas: prefer the routing-profile rationale string so the
+  // selection carries the policy-explained "why" rather than a generic label.
+  const rationale =
+    kind === 'local'
+      ? `local-override: ${spec.id}`
+      : (
+          routingProfiles.default.intents as Partial<Record<string, { rationale: string }>>
+        )[spec.intent]?.rationale ?? `cli: ${spec.id}`;
+  return {
+    personaId: spec.id,
+    harness: spec.harness,
+    model: spec.model,
+    systemPrompt,
+    harnessSettings: spec.harnessSettings,
+    skills: spec.skills,
+    rationale,
+    ...(spec.inputs ? { inputs: spec.inputs } : {}),
+    ...(spec.env ? { env: spec.env } : {}),
+    ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
+    ...(spec.permissions ? { permissions: spec.permissions } : {}),
+    ...(spec.mount ? { mount: spec.mount } : {}),
+    ...(spec.memory !== undefined ? { memory: spec.memory } : {}),
+    ...(sidecar.claudeMd ? { claudeMd: sidecar.claudeMd } : {}),
+    ...(sidecar.claudeMdContent ? { claudeMdContent: sidecar.claudeMdContent } : {}),
+    ...(sidecar.claudeMd || sidecar.claudeMdContent
+      ? { claudeMdMode: sidecar.claudeMdMode }
+      : {}),
+    ...(sidecar.agentsMd ? { agentsMd: sidecar.agentsMd } : {}),
+    ...(sidecar.agentsMdContent ? { agentsMdContent: sidecar.agentsMdContent } : {}),
+    ...(sidecar.agentsMd || sidecar.agentsMdContent
+      ? { agentsMdMode: sidecar.agentsMdMode }
+      : {})
+  };
+}
+
+function emitDropWarnings(lines: string[]): void {
+  if (lines.length === 0) return;
+  for (const line of lines) process.stderr.write(`warning: ${line}\n`);
+  process.stderr.write(
+    `        (referenced env vars were not set — proceeding without those values; if the agent relies on them it may need to authenticate interactively, e.g. via OAuth.)\n`
+  );
+}
+
+/**
+ * Detect that we're launching under an Agent Relay broker and, if so, build the
+ * relaycast wiring to inject into the harness's MCP config so the persona can
+ * message the team — the same capability a non-persona broker spawn gets.
+ *
+ * Delegates to the shared `resolveRelayMcpFromEnv` in `@agentworkforce/runtime`.
+ */
+const resolveRelayMcpFromEnv = resolveRelayMcpFromEnvShared;
+
+/**
+ * Build the `ai-hist` MCP config for a session. Only called when the persona
+ * opts into recall via `memory.aiMemory` (off by default). `TRAJECTORY_ROOT`
+ * (env) seeds the "why" read-root; `dbPathOverride` (from `memory.aiMemory.dbPath`)
+ * else `AI_HIST_DB` env seeds the "how" history DB. Anything unset falls back to
+ * the MCP's own discovery defaults.
+ */
+function resolveAiHistConfig(
+  env: NodeJS.ProcessEnv,
+  dbPathOverride?: string
+): AiHistMcpConfig {
+  const trajectoryRoot = env.TRAJECTORY_ROOT?.trim();
+  const dbPath = dbPathOverride?.trim() || env.AI_HIST_DB?.trim();
+  return {
+    ...(trajectoryRoot ? { trajectoryRoot } : {}),
+    ...(dbPath ? { dbPath } : {})
+  };
+}
+
+function signalExitCode(signal: NodeJS.Signals | null): number {
+  if (!signal) return 0;
+  const num = (constants.signals as Record<string, number | undefined>)[signal];
+  return 128 + (num ?? 1);
+}
+
+/**
+ * Derive a meaningful exit code from a `spawnSync` result. `spawnSync`
+ * sets `status` to null and `signal` to the signal name (e.g. `SIGINT`)
+ * when the child was killed before it could set its own exit code, so
+ * a naive `res.status ?? 1` collapses Ctrl-C / SIGTERM onto generic
+ * failure instead of the conventional 128+N.
+ */
+function subprocessExitCode(res: ReturnType<typeof spawnSync>): number {
+  if (res.status !== null) return res.status;
+  if (res.signal) return signalExitCode(res.signal);
+  return 1;
+}
+
+/**
+ * Run a skill-install subprocess behind an ora spinner. stdout and stderr are
+ * captured so a successful install collapses to a single ✓ line; on failure,
+ * 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.
+ */
+async function runInstallWithSpinner(
+  command: readonly string[],
+  label: string,
+  cwd: string | undefined
+): Promise<{ code: number; output: string }> {
+  const [bin, ...args] = command;
+  if (!bin) return { code: 0, output: '' };
+  const spinner = ora({ text: 'Installing skills…', stream: process.stderr }).start();
+  // 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<{ code: number; output: string }>((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: string) => {
+      buffered += chunk;
+    });
+    child.stderr?.on('data', (chunk: string) => {
+      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 });
+    });
+  });
+  if (code === 0) {
+    spinner.succeed(label);
+  } else {
+    spinner.fail(`${label} failed (exit ${code})`);
+    if (output.trim()) process.stderr.write(output.endsWith('\n') ? output : `${output}\n`);
+  }
+  return { code, output };
+}
+
+async function runInstall(command: readonly string[], label: string, cwd?: string): Promise<void> {
+  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 } = await runInstallWithSpinner(command, label, cwd);
+  if (code !== 0) process.exit(code);
+}
+
+/**
+ * Thrown by `runInstallOrThrow` when the install subprocess exits non-zero.
+ * Carries the underlying exit code so the mount-branch catch can surface it
+ * to the user instead of collapsing every failure onto 127.
+ */
+class InstallCommandError extends Error {
+  readonly exitCode: number;
+  constructor(label: string, exitCode: number) {
+    super(`${label} failed (exit ${exitCode})`);
+    this.name = 'InstallCommandError';
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Install variant that throws instead of calling `process.exit` on failure.
+ * Used inside the mount branch's onBeforeLaunch step so mount teardown runs
+ * before the error surfaces.
+ */
+async function runInstallOrThrow(
+  command: readonly string[],
+  label: string,
+  cwd: string
+): Promise<void> {
+  const [bin] = command;
+  if (!bin) return;
+  const { code } = await runInstallWithSpinner(command, label, cwd);
+  if (code !== 0) {
+    throw new InstallCommandError(label, code);
+  }
+}
+
+/**
+ * CLI-side install context shaped like workload-router's `useSelection().install`.
+ * Built directly from persona-kit's pure helpers
+ * ({@link materializeSkills}, {@link buildInstallArtifacts},
+ * {@link buildCleanupArtifacts}) so the spawn flow can keep its own
+ * spinner-driven install/cleanup orchestration without importing
+ * `useSelection` from `@agentworkforce/workload-router`.
+ */
+interface CliInstallContext {
+  plan: SkillMaterializationPlan;
+  command: readonly string[];
+  commandString: string;
+  cleanupCommand: readonly string[];
+  cleanupCommandString: string;
+}
+
+function buildInstallContext(
+  selection: PersonaSelection,
+  options: { installRoot?: string; repoRoot?: string } = {}
+): CliInstallContext {
+  const plan = materializeSkills(selection.skills, selection.harness, {
+    ...(options.installRoot !== undefined ? { installRoot: options.installRoot } : {}),
+    ...(options.repoRoot !== undefined ? { repoRoot: options.repoRoot } : {})
+  });
+  const { installCommand, installCommandString } = buildInstallArtifacts(plan);
+  const { cleanupCommand, cleanupCommandString } = buildCleanupArtifacts(plan);
+  return {
+    plan,
+    command: installCommand,
+    commandString: installCommandString,
+    cleanupCommand,
+    cleanupCommandString
+  };
+}
+
+function runCleanup(command: readonly string[], commandString: string): void {
+  if (commandString === ':') return;
+  const [bin, ...args] = command;
+  if (!bin) return;
+  spawnSync(bin, args, { stdio: 'inherit', shell: false });
+}
+
+/**
+ * Remove the whole per-session directory after the run, including the
+ * enclosing `<homedir>/.agentworkforce/workforce/sessions/<id>/` that the CLI
+ * created. The workload-router cleanup only covers the install subtree
+ * (`<root>/claude/plugin`), so without this step empty parent dirs
+ * would accumulate under `~/.agentworkforce/workforce/sessions/`.
+ *
+ * Uses `fs.rmSync` rather than `spawnSync('rm', …)` so the teardown works
+ * on Windows where `rm` isn't on PATH.
+ */
+function removeSessionRoot(sessionRoot: string | undefined): void {
+  if (!sessionRoot) return;
+  try {
+    rmSync(sessionRoot, { recursive: true, force: true });
+  } catch {
+    /* best-effort — if teardown fails the dir is harmless under ~/.agentworkforce/workforce/sessions */
+  }
+}
+
+/**
+ * Compute the absolute root directory for an interactive claude session.
+ * Layout (under `root`):
+ *
+ *   ~/.agentworkforce/workforce/sessions/<personaId>-<timestamp>-<rand>/
+ *     ├── claude/plugin/     ← skill install target + --plugin-dir
+ *     └── mount/             ← @relayfile/local-mount mount
+ *
+ * The timestamp + random suffix keep concurrent sessions from colliding on
+ * the same dir. Both the skill-install path and the mount path are derived
+ * from the same `root` so a single session ID describes the whole run.
+ */
+function generateSessionRoot(personaId: string): string {
+  const sessionId = `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+  return join(homedir(), '.agentworkforce', 'workforce', 'sessions', `${personaId}-${sessionId}`);
+}
+
+function sessionInstallRoot(sessionRoot: string): string {
+  return join(sessionRoot, 'claude', 'plugin');
+}
+
+function sessionMountDir(sessionRoot: string): string {
+  return join(sessionRoot, 'mount');
+}
+
+/** Default upstream drift-check interval when neither flag nor env overrides. */
+const DEFAULT_SKILL_CACHE_CHECK_INTERVAL_MS = 24 * 3_600_000;
+
+/**
+ * Resolve the env-configured drift-check interval.
+ *
+ * `parseCheckInterval` returns three things we must keep distinct:
+ *   - a number  → an explicit interval (incl. `0` = always)
+ *   - `null`    → the user explicitly disabled checks (`never`/`off`/`false`)
+ *   - `undefined` → unset or unparseable → fall back to the 24h default
+ *
+ * A plain `?? DEFAULT` is wrong here because `??` also coalesces `null`,
+ * silently re-enabling checks the user asked to turn off.
+ */
+export function resolveEnvCheckIntervalMs(): number | null {
+  const parsed = parseCheckInterval(
+    process.env.AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL
+  );
+  return parsed === undefined ? DEFAULT_SKILL_CACHE_CHECK_INTERVAL_MS : parsed;
+}
+
+interface SkillCacheLockHandle {
+  release(): void;
+}
+
+// A lock is considered abandoned if its heartbeat timestamp is older than
+// this — covers a holder that was SIGKILLed without releasing.
+const SKILL_CACHE_LOCK_STALE_MS = 15 * 60_000;
+const SKILL_CACHE_LOCK_HEARTBEAT_MS = 60_000;
+// Upper bound on how long we'll wait for a peer's install before proceeding
+// best-effort (unlocked). A real skill install is seconds; this is generous.
+const SKILL_CACHE_LOCK_WAIT_MS = 10 * 60_000;
+const SKILL_CACHE_LOCK_POLL_MS = 250;
+
+function skillCachePidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM => process exists but we can't signal it (still alive).
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+function skillCacheLockIsStale(lockPath: string): boolean {
+  try {
+    const [pidRaw, tsRaw] = readFileSync(lockPath, 'utf8').split('\n');
+    const ts = Number(tsRaw);
+    if (Number.isFinite(ts) && Date.now() - ts > SKILL_CACHE_LOCK_STALE_MS) {
+      return true;
+    }
+    const pid = Number(pidRaw);
+    if (Number.isInteger(pid) && pid > 0 && !skillCachePidAlive(pid)) {
+      return true;
+    }
+    return false;
+  } catch {
+    // Unreadable (just removed by the holder?) — treat as stale so we retry
+    // the exclusive create rather than spin forever.
+    return true;
+  }
+}
+
+function writeSkillCacheLockFile(lockPath: string, token: string): void {
+  writeFileSync(lockPath, `${process.pid}\n${Date.now()}\n${token}\n`);
+}
+
+function skillCacheLockTokenMatches(lockPath: string, token: string): boolean {
+  try {
+    const [, , foundToken] = readFileSync(lockPath, 'utf8').split('\n');
+    return foundToken === token;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Acquire a per-fingerprint advisory lock so two concurrent
+ * `agentworkforce agent <same-persona>` launches don't both miss the cache
+ * and install into the same dir simultaneously (which can interleave
+ * `prpm install` writes and corrupt the cache).
+ *
+ * The lock is a sibling file `<cacheDir>.lock` (NOT inside the cache dir, so
+ * a `--refresh-skills` wipe of the dir can't delete a live lock). Created
+ * with `wx` (O_EXCL) for atomicity. A held lock is stolen only if its holder
+ * is dead or its heartbeat is stale. If we can't get it within the wait
+ * budget we return null and the caller proceeds unlocked (best-effort —
+ * never hang a launch on locking).
+ */
+export async function acquireSkillCacheLock(
+  skillCacheDir: string
+): Promise<SkillCacheLockHandle | null> {
+  const lockPath = `${skillCacheDir}.lock`;
+  try {
+    mkdirSync(dirname(lockPath), { recursive: true });
+  } catch {
+    return null;
+  }
+  const deadline = Date.now() + SKILL_CACHE_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      const token = randomBytes(16).toString('hex');
+      writeFileSync(lockPath, `${process.pid}\n${Date.now()}\n${token}\n`, {
+        flag: 'wx'
+      });
+      const heartbeat = setInterval(() => {
+        if (!skillCacheLockTokenMatches(lockPath, token)) return;
+        try {
+          writeSkillCacheLockFile(lockPath, token);
+        } catch {
+          /* best-effort heartbeat */
+        }
+      }, SKILL_CACHE_LOCK_HEARTBEAT_MS);
+      heartbeat.unref?.();
+      let released = false;
+      return {
+        release() {
+          if (released) return;
+          released = true;
+          clearInterval(heartbeat);
+          try {
+            if (skillCacheLockTokenMatches(lockPath, token)) {
+              rmSync(lockPath, { force: true });
+            }
+          } catch {
+            /* best-effort — a stale-steal by another proc is harmless */
+          }
+        }
+      };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
+        // Unexpected FS error: don't block the launch on locking.
+        return null;
+      }
+      if (skillCacheLockIsStale(lockPath)) {
+        try {
+          rmSync(lockPath, { force: true });
+        } catch {
+          /* lost the steal race — loop and re-evaluate */
+        }
+        continue;
+      }
+      if (Date.now() >= deadline) return null;
+      await new Promise((r) => setTimeout(r, SKILL_CACHE_LOCK_POLL_MS));
+    }
+  }
+}
+
+/**
+ * Persist the cache marker after a successful install, folding in each
+ * skill's upstream identity (prpm version / github blob SHA) read from the
+ * lockfiles the installers just wrote into `cacheDir`. Sets
+ * `lastUpstreamCheckAt` to now so the first launch within the TTL window
+ * doesn't immediately re-probe what we just resolved.
+ *
+ * Best-effort on the upstream side: a probe failure for a given skill simply
+ * omits its `upstream` record (the next drift pass will try again). The
+ * marker itself is always written — its presence is what makes the cache
+ * dir "valid".
+ */
+async function writeMarkerWithUpstream(
+  cacheDir: string,
+  fingerprint: string,
+  harness: Harness,
+  skills: readonly { id: string; source: string }[]
+): Promise<void> {
+  let upstream: Map<string, { kind: string } | undefined> | undefined;
+  try {
+    upstream = (await buildUpstreamRecordsFromCacheDir(cacheDir, skills)) as Map<
+      string,
+      { kind: string } | undefined
+    >;
+  } catch {
+    upstream = undefined;
+  }
+  writeSkillCacheMarker(cacheDir, {
+    fingerprint,
+    harness,
+    lastUpstreamCheckAt: new Date().toISOString(),
+    skills: skills.map((s) => {
+      const rec = upstream?.get(s.id);
+      return {
+        id: s.id,
+        source: s.source,
+        ...(rec ? { upstream: rec as never } : {})
+      };
+    })
+  });
+}
+
+/**
+ * Mirror the contents of a populated skill cache dir into a target dir
+ * (typically a relayfile mount root). Skips the cache marker file so it
+ * never lands inside the harness's view.
+ *
+ * Used by the mount-harness branch to give non-claude harnesses the same
+ * "install once, reuse forever" behaviour that claude gets for free via
+ * `--plugin-dir <cacheDir>`. The destination is expected to be the mount
+ * root: skill artifacts under `.skills/`, `.opencode/`, `.agents/`, `.grok/skills`,
+ * etc. are
+ * declared as mount-ignored patterns so the mirror does not sync back to the
+ * user's real repo on session exit.
+ */
+function mirrorSkillCacheInto(cacheDir: string, targetDir: string): void {
+  if (!existsSync(cacheDir)) return;
+  for (const entry of readdirSync(cacheDir, { withFileTypes: true })) {
+    if (entry.name === '.aw-skill-cache.json') continue;
+    // npm's download cache exists only so installs into the cache dir don't
+    // re-fetch tarballs; it's dead weight at runtime (tens of MB) and the
+    // mount excludes `.npm-cache` from sync entirely.
+    if (entry.name === '.npm-cache') continue;
+    const from = join(cacheDir, entry.name);
+    const to = join(targetDir, entry.name);
+    cpSync(from, to, {
+      recursive: true,
+      // Don't overwrite a path the mount mirror or persona setup already
+      // created — surfacing the conflict as an error here would be loud and
+      // unactionable; the mount-ignored patterns guarantee any pre-existing
+      // entry under these names came from a prior cache mirror in this same
+      // session, which is fine to leave alone.
+      force: false,
+      errorOnExist: false
+    });
+  }
+}
+
+/**
+ * Remove every `--agent <id>` pair from a harness argv. Used on the non-mount
+ * opencode path where we cannot safely materialize the persona's
+ * opencode.json (it would land in the user's real repo), so we fall back to
+ * launching opencode without a persona-specific agent selection.
+ *
+ * Strips all occurrences rather than just the first — the current producer
+ * (the opencode branch in persona-kit) emits exactly one pair, so both
+ * behaviors are equivalent today, but "remove all" is idempotent and safer if
+ * a future caller ever appends a second `--agent` for any reason. A trailing
+ * `--agent` with no following value is preserved so the malformed argv
+ * surfaces at the harness rather than getting silently swallowed here.
+ */
+export function stripAgentFlag(args: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--agent' && i + 1 < args.length) {
+      i += 1;
+      continue;
+    }
+    out.push(args[i]);
+  }
+  return out;
+}
+
+/**
+ * Validate that a configFile's relative path is safe to resolve under a
+ * sandbox/session directory. Rejects absolute paths and any segment equal to
+ * `..` so a malformed or adversarial persona cannot escape the mount via
+ * `join()` and overwrite files elsewhere. Called at materialization time so
+ * the failure surfaces with a clear path before any disk write happens.
+ */
+export function assertSafeRelativePath(relPath: string): void {
+  if (!relPath) {
+    throw new Error('configFile path must be a non-empty relative path');
+  }
+  if (isAbsolute(relPath)) {
+    throw new Error(
+      `configFile path must be relative; got absolute path ${JSON.stringify(relPath)}`
+    );
+  }
+  const segments = relPath.split(/[\\/]+/);
+  if (segments.some((s) => s === '..')) {
+    throw new Error(
+      `configFile path must not contain ".." segments; got ${JSON.stringify(relPath)}`
+    );
+  }
+}
+
+/** Patterns hidden from an interactive claude session by the sandbox mount.
+ * Applied by `@relayfile/local-mount` with gitignore semantics, so bare names
+ * match at any depth in the project tree (e.g. `.claude` hides both
+ * `./.claude/` and `./packages/foo/.claude/`). */
+export const CLEAN_IGNORED_PATTERNS = [
+  'CLAUDE.md',
+  'CLAUDE.local.md',
+  '.claude',
+  '.mcp.json',
+  // Per-persona AGENTS.md sidecars get materialized into the mount when
+  // running under a non-claude harness; without this the user's real-cwd AGENTS.md
+  // would copy in (masking the persona content) and writes from
+  // onBeforeLaunch would sync back out.
+  'AGENTS.md'
+] as const;
+
+/**
+ * Skill-install artifacts that should never be copied into the mount nor
+ * synced back to the real repo. Applied to non-claude interactive sessions
+ * that rely on the mount to keep `npx skills add` / `npx prpm install`
+ * writes out of the user's project tree. Covers every per-provider output
+ * root that skill.sh / prpm scatter into on install — missing one here
+ * re-introduces repo pollution, so this list is deliberately superset-y.
+ * Claude sessions use `installRoot` for out-of-repo staging instead, so
+ * these patterns don't apply there.
+ */
+export const SKILL_INSTALL_IGNORED_PATTERNS = [
+  // skill.sh universal install root + per-harness symlink farms
+  '.agents',
+  '.claude/skills',
+  '.factory/skills',
+  '.grok/skills',
+  '.kiro/skills',
+  'skills',
+  // prpm `--as <harness>` output roots
+  '.opencode',
+  '.skills',
+  // provider lockfiles written at the repo root
+  'prpm.lock',
+  'skills-lock.json',
+  // Per-persona AGENTS.md sidecars (non-claude harnesses) get materialized
+  // into the mount; hide so the real-cwd AGENTS.md isn't copied in and
+  // the persona-written copy doesn't sync back out.
+  'AGENTS.md'
+] as const;
+
+export interface RelayfileMountPatterns {
+  ignoredPatterns: string[];
+  readonlyPatterns: string[];
+}
+
+export function buildRelayfileMountPatterns(input: {
+  projectDir: string;
+  personaId: string;
+  harness: Harness;
+  mount?: PersonaMount;
+  configFilePaths?: readonly string[];
+}): RelayfileMountPatterns {
+  const dotfiles = readAgentDotfiles(input.projectDir, {
+    agentName: input.personaId
+  });
+  const builtInIgnored =
+    input.harness === 'claude'
+      ? CLEAN_IGNORED_PATTERNS
+      : SKILL_INSTALL_IGNORED_PATTERNS;
+
+  return {
+    ignoredPatterns: [
+      ...dotfiles.ignoredPatterns,
+      ...(input.mount?.ignoredPatterns ?? []),
+      ...builtInIgnored,
+      ...(input.configFilePaths ?? [])
+    ],
+    readonlyPatterns: [
+      ...dotfiles.readonlyPatterns,
+      ...(input.mount?.readonlyPatterns ?? [])
+    ]
+  };
+}
+
+/**
+ * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
+ * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
+ * `opencode.json` written by `onBeforeLaunch`) don't surface under
+ * "Untracked files" in `git status` inside the mount.
+ *
+ * Exported pure helper for unit-testing the formatting separately from the
+ * disk-writing wrapper below.
+ */
+export function buildMountGitExcludeBlock(patterns: readonly string[]): string {
+  const lines = [
+    '',
+    '# agentworkforce: patterns hidden from this sandboxed session.',
+    '# Tracked paths matching these patterns are also marked skip-worktree',
+    '# so `git status` does not report them as deleted.',
+    ...patterns,
+    ''
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Configure the mount's per-session `.git` so paths hidden by the relayfile
+ * mount don't show as deleted/untracked inside the sandbox.
+ *
+ * - Appends `patterns` to `.git/info/exclude` so untracked-and-hidden files
+ *   don't show up under "Untracked files".
+ * - Marks every tracked file matching one of the patterns as skip-worktree
+ *   so `git status` doesn't list it as deleted (the work tree omits it on
+ *   purpose, not by user action).
+ *
+ * Best-effort: if the mount has no `.git` (project isn't a repo, or
+ * `includeGit: false`) or any git command fails, returns silently. The
+ * mount's `.git` is per-session and `noSyncBack` per relayfile 0.6+, so
+ * writes here are sandboxed and never leak to the user's main checkout.
+ */
+export function configureGitForMount(mountDir: string, patterns: readonly string[]): void {
+  if (patterns.length === 0) return;
+  const infoDir = join(mountDir, '.git', 'info');
+  if (!existsSync(infoDir)) return;
+
+  appendFileSync(join(infoDir, 'exclude'), buildMountGitExcludeBlock(patterns));
+
+  // Use git's own gitignore matcher to pick which tracked files to flag,
+  // keeping semantics aligned with relayfile's (gitignore-style, basename-
+  // anywhere) filter. `--cached -i --exclude-from=<file>` (without
+  // `--exclude-standard`) lists only tracked files matched by the supplied
+  // patterns — not the repo's own .gitignore.
+  const tmpExcludes = join(infoDir, '.aw-skip-list');
+  try {
+    writeFileSync(tmpExcludes, patterns.join('\n') + '\n');
+    const ls = spawnSync(
+      'git',
+      ['ls-files', '-z', '--cached', '-i', `--exclude-from=${tmpExcludes}`],
+      { cwd: mountDir }
+    );
+    if (ls.status !== 0) return;
+    const files = ls.stdout.toString('utf8').split('\0').filter(Boolean);
+    if (files.length === 0) return;
+    // Chunk to stay well under typical argv-length limits on huge repos.
+    const CHUNK = 200;
+    for (let i = 0; i < files.length; i += CHUNK) {
+      spawnSync(
+        'git',
+        ['update-index', '--skip-worktree', '--', ...files.slice(i, i + CHUNK)],
+        { cwd: mountDir }
+      );
+    }
+  } finally {
+    try {
+      rmSync(tmpExcludes, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * Persona-supplied sidecar markdown materialized into a sandbox mount.
+ * Pure data carrier — `runInteractive` translates it into the on-disk
+ * write inside `onBeforeLaunch` (mount path) and warns/skips when the
+ * harness has no mount (`--install-in-repo`).
+ */
+export interface ResolvedSidecar {
+  /** Filename inside the mount: `CLAUDE.md` (claude) or `AGENTS.md` (opencode/codex/grok). */
+  mountFile: 'CLAUDE.md' | 'AGENTS.md';
+  /** Persona-author content. Already inlined for built-ins; read from disk for local. */
+  personaContent: string;
+  mode: SidecarMdMode;
+}
+
+/**
+ * Resolve the sidecar for a given selection + harness, returning the
+ * persona-author content the runtime should materialize into the mount.
+ * Returns `{}` when no sidecar applies (no path/content set, or harness
+ * doesn't support sidecar files at all). Read errors surface as a warning
+ * string so the caller can drop the sidecar gracefully rather than
+ * failing the whole session.
+ */
+export function loadSidecarForSelection(
+  selection: PersonaSelection
+): { sidecar?: ResolvedSidecar; warning?: string } {
+  const harness = selection.harness;
+  if (
+    harness !== 'claude' &&
+    harness !== 'opencode' &&
+    harness !== 'codex' &&
+    harness !== 'grok'
+  ) {
+    return {};
+  }
+  if (harness === 'claude') {
+    if (selection.claudeMdContent) {
+      return {
+        sidecar: {
+          mountFile: 'CLAUDE.md',
+          personaContent: selection.claudeMdContent,
+          mode: selection.claudeMdMode ?? 'overwrite'
+        }
+      };
+    }
+    if (selection.claudeMd) {
+      try {
+        const content = readFileSync(selection.claudeMd, 'utf8');
+        return {
+          sidecar: {
+            mountFile: 'CLAUDE.md',
+            personaContent: content,
+            mode: selection.claudeMdMode ?? 'overwrite'
+          }
+        };
+      } catch (err) {
+        return { warning: `claudeMd: could not read ${selection.claudeMd}: ${(err as Error).message}` };
+      }
+    }
+    return {};
+  }
+  // opencode, codex, and grok all read AGENTS.md from cwd. The resolution
+  // rule is identical for these harnesses here.
+  if (selection.agentsMdContent) {
+    return {
+      sidecar: {
+        mountFile: 'AGENTS.md',
+        personaContent: selection.agentsMdContent,
+        mode: selection.agentsMdMode ?? 'overwrite'
+      }
+    };
+  }
+  if (selection.agentsMd) {
+    try {
+      const content = readFileSync(selection.agentsMd, 'utf8');
+      return {
+        sidecar: {
+          mountFile: 'AGENTS.md',
+          personaContent: content,
+          mode: selection.agentsMdMode ?? 'overwrite'
+        }
+      };
+    } catch (err) {
+      return { warning: `agentsMd: could not read ${selection.agentsMd}: ${(err as Error).message}` };
+    }
+  }
+  return {};
+}
+
+/**
+ * Compute the bytes to write into the mount for a sidecar. In `extend`
+ * mode, prepends the user's real-cwd file (if any) joined to the persona
+ * content with `\n\n---\n\n`. Pure — exposed for unit tests.
+ */
+export function buildSidecarBody(
+  sidecar: ResolvedSidecar,
+  realCwdDir: string
+): string {
+  if (sidecar.mode === 'extend') {
+    const realPath = join(realCwdDir, sidecar.mountFile);
+    try {
+      const realContent = readFileSync(realPath, 'utf8');
+      return `${realContent}\n\n---\n\n${sidecar.personaContent}`;
+    } catch (err) {
+      // Only "missing path" errors degrade to overwrite. Real I/O
+      // problems (EACCES, EISDIR, …) propagate so callers see them
+      // instead of silently dropping the user's CLAUDE.md/AGENTS.md.
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') {
+        return sidecar.personaContent;
+      }
+      throw err;
+    }
+  }
+  return sidecar.personaContent;
+}
+
+/**
+ * Decide whether to run the interactive session inside a
+ * `@relayfile/local-mount` sandbox.
+ *
+ * All interactive harnesses default to the mount.
+ * The mount hides CLAUDE.md / .claude / .mcp.json (claude) or the
+ * skill-install patterns + AGENTS.md (codex / opencode / grok) so
+ * persona-supplied sidecars and any per-session writes stay sandboxed and
+ * don't leak into the user's real repo. `--install-in-repo` is the single
+ * opt-out that disengages the mount across all harnesses.
+ *
+ * Pure — no side effects, trivially testable.
+ */
+export function decideCleanMode(
+  harness: Harness,
+  installInRepo = false
+): { useClean: boolean } {
+  if (harness === 'claude' || harness === 'opencode' || harness === 'codex' || harness === 'grok') {
+    return { useClean: !installInRepo };
+  }
+  return { useClean: false };
+}
+
+export function formatSandboxMountReadyMessage(
+  mountDir: string,
+  handle: { initialMountDurationMs?: number; initialFileCount?: number }
+): string {
+  const mountStats =
+    handle.initialMountDurationMs !== undefined && handle.initialFileCount !== undefined
+      ? ` (${handle.initialMountDurationMs}ms, ${handle.initialFileCount} files)`
+      : '';
+  return `Sandbox mount ready${mountStats} → ${mountDir}`;
+}
+
+export function buildSpawnSummary(input: {
+  harness: Harness;
+  model: string;
+  spec: Pick<InteractiveSpec, 'initialPrompt' | 'mcpServers'>;
+  permissions?: PersonaSelection['permissions'];
+  useClean?: boolean;
+}): string[] {
+  const summary: string[] = [`model=${input.model}`];
+  if (input.harness === 'claude') {
+    const servers = Object.keys(input.spec.mcpServers ?? {});
+    summary.push(`mcp-strict=${servers.length ? servers.join(',') : '(none)'}`);
+  }
+  if (input.harness === 'claude') {
+    if (input.permissions?.allow?.length) {
+      summary.push(`allow=${input.permissions.allow.length} rule(s)`);
+    }
+    if (input.permissions?.deny?.length) {
+      summary.push(`deny=${input.permissions.deny.length} rule(s)`);
+    }
+  }
+  if (input.harness === 'claude') {
+    if (input.permissions?.mode) {
+      summary.push(`mode=${input.permissions.mode}`);
+    }
+  }
+  if (input.spec.initialPrompt) summary.push('initial-prompt=<systemPrompt>');
+  if (input.useClean) summary.push('mount=on');
+  return summary;
+}
+
+/**
+ * Persona authoring dry-run. Used by persona authors to verify a persona
+ * actually launches before it ships, without spawning the harness or
+ * running the agent's tier model. Three checks, in order:
+ *
+ *   1. Sidecar resolution — `claudeMd` / `agentsMd` filename references
+ *      that point at unreadable files would brick the launch silently
+ *      today (lenient warning); dry-run promotes them to failures.
+ *   2. Interactive spec build — runs `buildInteractiveSpec` on the
+ *      resolved selection. Catches malformed `permissions` patterns,
+ *      `mcpServers` shape errors, and missing required harness fields.
+ *      Pure / no side effects.
+ *   3. Skill install — runs each `skills[].source` through its real
+ *      installer (`npx skills add` / `npx prpm install`) inside a fresh
+ *      temp dir and reports per-skill pass/fail.
+ *
+ * Temp dir is deleted on success so dry-run leaves no trace; on a skill
+ * failure it is left in place and its path printed so the author can
+ * inspect the installer's output. Checks 1 and 2 run before any temp
+ * dir is created so an early failure doesn't litter `/tmp`.
+ */
+function runDryRun(selection: PersonaSelection): number {
+  const inputResolution = resolvePersonaInputs(
+    selection.inputs,
+    selection.inputValues,
+    process.env
+  );
+  const renderedSystemPrompt = renderPersonaInputs(
+    selection.systemPrompt,
+    inputResolution.values
+  );
+  const renderedClaudeContent =
+    selection.claudeMdContent !== undefined
+      ? renderPersonaInputs(selection.claudeMdContent, inputResolution.values)
+      : undefined;
+  const renderedAgentsContent =
+    selection.agentsMdContent !== undefined
+      ? renderPersonaInputs(selection.agentsMdContent, inputResolution.values)
+      : undefined;
+  const effectiveSelection: PersonaSelection = {
+    ...selection,
+    systemPrompt: renderedSystemPrompt,
+    ...(renderedClaudeContent !== undefined ? { claudeMdContent: renderedClaudeContent } : {}),
+    ...(renderedAgentsContent !== undefined ? { agentsMdContent: renderedAgentsContent } : {})
+  };
+  const { personaId, harness, model, harnessSettings, systemPrompt } = effectiveSelection;
+
+  process.stderr.write(
+    `→ ${personaId} via ${harness} (${model}) [DRY-RUN]\n`
+  );
+
+  // Check 1: sidecar resolution. A loadSidecarForSelection warning means
+  // the persona points `claudeMd` / `agentsMd` at a file we couldn't
+  // read; the launch path degrades to a warning today, which silently
+  // drops the persona's operating spec. In dry-run that's a failure.
+  const sidecarLookup = loadSidecarForSelection(effectiveSelection);
+  if (sidecarLookup.warning) {
+    process.stderr.write(`✗ sidecar: ${sidecarLookup.warning}\n`);
+    return 1;
+  }
+  process.stderr.write(
+    `✓ sidecar: ${sidecarLookup.sidecar ? sidecarLookup.sidecar.mountFile : '(none)'}\n`
+  );
+
+  // Check 2: persona-kit translation. buildInteractiveSpec validates
+  // permissions shape, mcpServers shape, and required runtime fields.
+  // We resolve env + mcp leniently (same as the live launch path) so
+  // the spec call sees the same inputs it would at runtime.
+  const callerEnv = { ...process.env, ...inputResolution.values };
+  const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
+  const mcpResolution = resolveMcpServersLenient(effectiveSelection.mcpServers, callerEnv);
+  emitDropWarnings(
+    formatDropWarnings(envResolution.dropped, mcpResolution.dropped, mcpResolution.droppedServers)
+  );
+  let spec: InteractiveSpec;
+  try {
+    const relayMcp = resolveRelayMcpFromEnv(process.env);
+    const aiMemory = resolveAiMemory(effectiveSelection.memory);
+    const aiHist = aiMemory.enabled
+      ? resolveAiHistConfig(process.env, aiMemory.dbPath)
+      : undefined;
+    spec = buildInteractiveSpec({
+      harness,
+      personaId,
+      model,
+      systemPrompt,
+      harnessSettings,
+      mcpServers: mcpResolution.servers,
+      ...(relayMcp ? { relayMcp } : {}),
+      ...(aiHist ? { aiHist } : {}),
+      permissions: effectiveSelection.permissions
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`✗ harness spec: ${msg}\n`);
+    return 1;
+  }
+  for (const w of spec.warnings) process.stderr.write(`warning: ${w}\n`);
+  process.stderr.write(`✓ harness spec: ${spec.bin} (${spec.args.length} args)\n`);
+
+  // Check 3: skill installs.
+  // Dry-run runs each install inside a fresh tempDir (see `cwd: tempDir` on
+  // the spawnSync below). Pass repoRoot=process.cwd() so `local`-kind skills
+  // resolve their relative source paths against the real repo, not the tmp.
+  const plan = materializeSkills(effectiveSelection.skills, harness, {
+    repoRoot: process.cwd()
+  });
+  if (plan.installs.length === 0) {
+    process.stderr.write('✓ skills: (none declared)\n');
+    process.stderr.write('✓ dry-run ok\n');
+    return 0;
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), `agentworkforce-dryrun-${personaId}-`));
+  process.stderr.write(`• temp dir: ${tempDir}\n`);
+  process.stderr.write(`• installing ${plan.installs.length} skill(s)\n`);
+
+  const failures: { skillId: string; exitCode: number }[] = [];
+  for (const inst of plan.installs) {
+    const [bin, ...args] = inst.installCommand;
+    if (!bin) {
+      process.stderr.write(`  skipped ${inst.skillId}: empty install command\n`);
+      continue;
+    }
+    process.stderr.write(`• ${inst.skillId} (${inst.sourceKind}) → ${inst.packageRef}\n`);
+    const res = spawnSync(bin, args, { stdio: 'inherit', shell: false, cwd: tempDir });
+    const code = subprocessExitCode(res);
+    if (code === 0) {
+      process.stderr.write(`  ✓ ${inst.skillId}\n`);
+    } else {
+      process.stderr.write(`  ✗ ${inst.skillId} (exit ${code})\n`);
+      failures.push({ skillId: inst.skillId, exitCode: code });
+    }
+  }
+
+  if (failures.length === 0) {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`warning: failed to clean up ${tempDir}: ${msg}\n`);
+    }
+    process.stderr.write(
+      `✓ dry-run ok: ${plan.installs.length} skill(s) installed cleanly\n`
+    );
+    return 0;
+  }
+
+  process.stderr.write(
+    `✗ dry-run failed: ${failures.length} of ${plan.installs.length} skill(s) failed\n`
+  );
+  process.stderr.write(`  inspect ${tempDir} for installer output\n`);
+  for (const f of failures) {
+    process.stderr.write(`  - ${f.skillId} (exit ${f.exitCode})\n`);
+  }
+  return failures[0]?.exitCode || 1;
+}
+
+/**
+ * Optional out-parameter populated by `runInteractive` so the caller can
+ * locate the just-ended session for follow-up tooling (e.g. the
+ * persona-improver post-session prompt). Populated regardless of exit
+ * status so failure paths are still inspectable.
+ */
+interface RunInteractiveCapture {
+  /** Cwd the harness child saw — mount dir for sandboxed sessions, real cwd otherwise. */
+  sessionCwd?: string;
+  /** Harness binary that was spawned. */
+  harness?: Harness;
+  /** Wallclock (ms) right before the harness child was spawned. Used to filter newer transcript files. */
+  startedAt?: number;
+  /**
+   * Burn-stamp enrichment written by launch-metadata (`agentworkforce`,
+   * `persona`, `personaVersion`, `personaTier`, `personaSource`). Empty
+   * `{}` when launch-metadata is disabled (opt-out via env or backend
+   * doesn't support stamps). Lets the post-session lookup match the
+   * just-ended session to its harness sessionId via `exportStamps`.
+   */
+  stampEnrichment?: Record<string, string>;
+  /** Whether burn stamping was actually wired this run (false → exportStamps lookup is moot). */
+  stampingEnabled?: boolean;
+}
+
+/** Mirror of persona-kit's local-skill-source detection (skill-cache.ts). */
+const SKILL_LOCAL_MD_RE = /\.md$/i;
+const SKILL_URL_PREFIX_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** Resolve a bare binary name to its absolute PATH entry, or null. */
+function resolveBinOnPath(bin: string): string | null {
+  if (isAbsolute(bin)) return existsSync(bin) ? bin : null;
+  for (const dir of (process.env.PATH ?? '').split(':')) {
+    if (!dir) continue;
+    const candidate = join(dir, bin);
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+}
+
+/**
+ * Build the warm-launch plan for this session, or null when the launch is
+ * not eligible for the fast path.
+ *
+ * Eligibility is deliberately strict: the plan stores a fully resolved argv,
+ * so anything whose value flowed in from the environment (persona `env`
+ * maps, MCP server configs, relay MCP injection on harnesses that wire it,
+ * env-provided persona inputs, ai-memory wiring) makes the launch ineligible
+ * rather than risking a stale or secret-bearing plan on disk. Digests are
+ * captured HERE — at resolution time — so an input file edited while the
+ * session runs invalidates the plan instead of being blessed at exit.
+ */
+function buildFastLaunchPlan(input: {
+  selector: string;
+  personaId: string;
+  harness: Harness;
+  model: string;
+  selection: PersonaSelection;
+  effectiveSelection: PersonaSelection;
+  relayMcp: RelayMcpConfig | undefined;
+  /** Resolution of the persona's declared `env` map (must be absent). */
+  envResolutionValue: Record<string, string> | undefined;
+  /** Input values from declared defaults — the only allowed env additions. */
+  inputEnv: Record<string, string>;
+  resolvedMcp: unknown;
+  aiHist: unknown;
+  skillCacheDir: string | undefined;
+  skillCacheFingerprint: string | undefined;
+  bin: string;
+  finalArgs: readonly string[];
+  ignoredPatterns: readonly string[];
+  readonlyPatterns: readonly string[];
+}): LaunchPlan | null {
+  const cwd = process.cwd();
+  if (input.envResolutionValue !== undefined) return null;
+  if (input.resolvedMcp !== undefined) return null;
+  if (input.aiHist !== undefined) return null;
+  if (input.selection.inputValues !== undefined) return null;
+  if (input.selection.env !== undefined) return null;
+  if (input.selection.mcpServers !== undefined) return null;
+  if (!input.skillCacheDir || !input.skillCacheFingerprint) return null;
+  // Opencode ignores relay MCP injection entirely; every other harness wires
+  // it into argv (tokens included), so those are only eligible with relay
+  // MCP unset — enforced via the env pins below.
+  if (input.relayMcp !== undefined && input.harness !== 'opencode') return null;
+
+  const envExact: Record<string, string | null> = {};
+  for (const name of Object.keys(input.selection.inputs ?? {})) {
+    // Inputs must have resolved from declared defaults: an env-provided
+    // value would bake user/session state (possibly secrets) into the plan.
+    if (process.env[name] !== undefined) return null;
+    envExact[name] = null;
+  }
+  envExact.AGENT_WORKFORCE_HOME = process.env.AGENT_WORKFORCE_HOME ?? null;
+  envExact.AGENT_WORKFORCE_CONFIG_DIR = process.env.AGENT_WORKFORCE_CONFIG_DIR ?? null;
+  if (input.harness !== 'opencode') {
+    for (const name of [
+      'RELAY_API_KEY',
+      'RELAY_AGENT_NAME',
+      'RELAY_BASE_URL',
+      'RELAY_DEFAULT_WORKSPACE'
+    ]) {
+      // relayMcp was undefined (checked above), so these were unset/blank;
+      // pin them to "unset" without ever recording a value.
+      if (process.env[name] !== undefined) return null;
+      envExact[name] = null;
+    }
+  }
+
+  const digests: StatDigest[] = [];
+  const personaFilePath = local.paths.get(input.personaId);
+  if (personaFilePath) digests.push(statDigestOf(personaFilePath));
+  const { directories, config } = buildPersonaSourceDirectories();
+  digests.push(statDigestOf(config.configPath));
+  for (const dir of directories) {
+    digests.push(statDigestOf(dir.dir));
+  }
+  // Dotfiles shape the mount patterns. Persona ids are kebab-case, so the
+  // per-agent filenames need no sanitization here.
+  for (const name of [
+    '.agentignore',
+    '.agentreadonly',
+    `.${input.personaId}.agentignore`,
+    `.${input.personaId}.agentreadonly`
+  ]) {
+    digests.push(statDigestOf(join(cwd, name)));
+  }
+  // Local skill sources feed the cache fingerprint by content hash; the fast
+  // path never recomputes the fingerprint, so pin the files themselves.
+  for (const skill of input.effectiveSelection.skills) {
+    if (SKILL_URL_PREFIX_RE.test(skill.source)) continue;
+    if (!SKILL_LOCAL_MD_RE.test(skill.source)) continue;
+    const trimmed = skill.source.startsWith('./') ? skill.source.slice(2) : skill.source;
+    digests.push(statDigestOf(isAbsolute(trimmed) ? trimmed : join(cwd, trimmed)));
+  }
+
+  const binPath = resolveBinOnPath(input.bin);
+  if (!binPath) return null;
+
+  return {
+    schemaVersion: LAUNCH_PLAN_SCHEMA_VERSION,
+    cliVersion: CLI_VERSION,
+    cwd,
+    selector: input.selector,
+    personaId: input.personaId,
+    harness: input.harness,
+    model: input.model,
+    digests,
+    envExact,
+    skillCache: {
+      dir: input.skillCacheDir,
+      fingerprint: input.skillCacheFingerprint,
+      upstreamIntervalRaw: process.env.AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL ?? null,
+      upstreamIntervalMs: resolveEnvCheckIntervalMs()
+    },
+    spawn: { binPath, args: [...input.finalArgs], envAdditions: { ...input.inputEnv } },
+    mount: {
+      warmDir: warmMountDir(cwd, input.selector),
+      ignoredPatterns: [...input.ignoredPatterns],
+      readonlyPatterns: [...input.readonlyPatterns]
+    }
+  };
+}
+
+/**
+ * Keep a finished session's mount as the warm mount for the next launch and
+ * persist the plan + autosync state next to it. Best-effort: any failure
+ * leaves no warm dir (or a partial one whose missing marker/state file the
+ * fast path rejects) and the next launch simply goes cold.
+ */
+function rewarmMountAndPlan(input: {
+  plan: LaunchPlan;
+  mountDir: string;
+  exportedState: Record<string, FileState>;
+}): void {
+  const warmDir = input.plan.mount.warmDir;
+  try {
+    rmSync(warmDir, { recursive: true, force: true });
+    mkdirSync(warmDir, { recursive: true });
+    renameSync(input.mountDir, join(warmDir, 'mount'));
+    writeFileSync(
+      join(warmDir, 'state.json'),
+      JSON.stringify(input.exportedState),
+      { mode: 0o600 }
+    );
+    writeLaunchPlan(input.plan);
+    perfMark('exit: mount re-warmed + plan written');
+  } catch (err) {
+    process.stderr.write(
+      `warning: could not keep warm mount for next launch: ${(err as Error).message}\n`
+    );
+    try {
+      rmSync(warmDir, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+/**
+ * Interpolate declared persona inputs ($TARGET_DIR, ${CREATE_MODE}, …) into
+ * the system prompt and sidecar content fields. Personas that move heavy
+ * authoring guidance out of the systemPrompt and into AGENTS.md / CLAUDE.md
+ * still want their declared inputs interpolated; without this the
+ * materialized sidecar would carry literal `$TARGET_DIR` strings. Shared by
+ * the full launch path and the fast-session resume (which re-renders to
+ * verify the cached plan and to feed launch metadata).
+ */
+function renderEffectiveSelection(selection: PersonaSelection): {
+  effectiveSelection: PersonaSelection;
+  inputResolution: ReturnType<typeof resolvePersonaInputs>;
+} {
+  const inputResolution = resolvePersonaInputs(
+    selection.inputs,
+    selection.inputValues,
+    process.env
+  );
+  const renderedSystemPrompt = renderPersonaInputs(
+    selection.systemPrompt,
+    inputResolution.values
+  );
+  const renderedClaudeContent =
+    selection.claudeMdContent !== undefined
+      ? renderPersonaInputs(selection.claudeMdContent, inputResolution.values)
+      : undefined;
+  const renderedAgentsContent =
+    selection.agentsMdContent !== undefined
+      ? renderPersonaInputs(selection.agentsMdContent, inputResolution.values)
+      : undefined;
+  const effectiveSelection: PersonaSelection = {
+    ...selection,
+    systemPrompt: renderedSystemPrompt,
+    ...(renderedClaudeContent !== undefined ? { claudeMdContent: renderedClaudeContent } : {}),
+    ...(renderedAgentsContent !== undefined ? { agentsMdContent: renderedAgentsContent } : {})
+  };
+  return { effectiveSelection, inputResolution };
+}
+
+async function runInteractive(
+  selection: PersonaSelection,
+  options: {
+    installInRepo?: boolean;
+    noLaunchMetadata?: boolean;
+    /** Bypass the persistent skill cache for this run (install fresh into a session dir). */
+    noSkillCache?: boolean;
+    /** Force reinstall into the cache dir, replacing any existing entry. */
+    refreshSkills?: boolean;
+    /** Force an upstream drift check this launch regardless of the TTL. */
+    checkUpstream?: boolean;
+    /** Skip the upstream drift check this launch regardless of the TTL. */
+    noCheckUpstream?: boolean;
+    personaSpec: PersonaSpec;
+    personaSource: PersonaSource;
+    capture?: RunInteractiveCapture;
+    /**
+     * The raw selector the user launched with. When set (plain
+     * `agent <persona>` launches), a successful mount session is kept warm
+     * and a launch plan written so the next launch can take the fast path.
+     */
+    selector?: string;
+  }
+): Promise<number> {
+  const { effectiveSelection, inputResolution } = renderEffectiveSelection(selection);
+  const { personaId, harness, model, harnessSettings, systemPrompt } = effectiveSelection;
+  // `installRoot` (out-of-repo skill staging via `--plugin-dir`) is currently
+  // claude-only; the workload-router SDK throws if it's set for other
+  // harnesses. For other harnesses, we instead keep installs out of the repo by
+  // running them inside a @relayfile/local-mount sandbox (see `useClean`
+  // below). The --install-in-repo flag forces legacy in-repo installs
+  // across the board.
+  const useClean = decideCleanMode(
+    harness,
+    options.installInRepo === true
+  ).useClean;
+  // Per-persona CLAUDE.md / AGENTS.md: load the author content if any. The
+  // file is materialized into the mount inside onBeforeLaunch. Without a
+  // mount (--install-in-repo) we skip-and-warn — writing into the real cwd
+  // would pollute the user's repo and is explicitly out of scope.
+  const sidecarLookup = loadSidecarForSelection(effectiveSelection);
+  if (sidecarLookup.warning) {
+    process.stderr.write(`warning: ${sidecarLookup.warning}\n`);
+  }
+  const resolvedSidecar = useClean ? sidecarLookup.sidecar : undefined;
+  if (sidecarLookup.sidecar && !useClean) {
+    process.stderr.write(
+      `warning: persona declares ${sidecarLookup.sidecar.mountFile} but no sandbox mount is available ` +
+        `(--install-in-repo disengages the mount); skipping sidecar materialization to avoid writing into your repo.\n`
+    );
+  }
+  // A session dir is needed whenever we either (a) stage skills out-of-repo
+  // via claude's installRoot, or (b) open a mount. Both engage by default;
+  // --install-in-repo disengages both.
+  const useSessionDir =
+    !options.installInRepo && (harness === 'claude' || useClean);
+  const sessionRoot = useSessionDir ? generateSessionRoot(personaId) : undefined;
+
+  // Persistent skill-install cache. Keyed by a content-addressed fingerprint
+  // of (harness, sorted skill sources, local file contents). On a hit we reuse
+  // the dir directly — for claude as `--plugin-dir`, for mount harnesses by
+  // mirroring its contents into the mount before launch. Disabled when the
+  // user opts into in-repo installs (the cache lives outside the repo, so
+  // mirroring it back would re-introduce the very leakage `--install-in-repo`
+  // is designed to surface to the user explicitly).
+  const skillCachingEnabled = !options.installInRepo && options.noSkillCache !== true;
+  const skillCacheFingerprint = skillCachingEnabled
+    ? computeSkillCacheFingerprint({
+        harness,
+        skills: effectiveSelection.skills,
+        repoRoot: process.cwd()
+      })
+    : undefined;
+  const skillCacheDir = skillCacheFingerprint
+    ? resolveSkillCacheDir(skillCacheFingerprint)
+    : undefined;
+  // Source-key hit: marker present and fingerprint matches. The upstream
+  // drift check below may still flip this to a miss.
+  perfMark('runInteractive: fingerprint computed');
+  const skillCacheSourceHit =
+    skillCacheDir !== undefined &&
+    skillCacheFingerprint !== undefined &&
+    !options.refreshSkills &&
+    isSkillCacheValid(skillCacheDir, skillCacheFingerprint);
+  perfMark('runInteractive: skill cache checked');
+  // Mutable: a detected upstream drift downgrades the hit into a miss so the
+  // install path reruns and rebuilds the cache dir in place.
+  let skillCacheHit = skillCacheSourceHit;
+
+  // installRoot: for claude this is the dir passed to `--plugin-dir`. With
+  // caching enabled it points at the persistent cache; without, at the
+  // ephemeral session dir (pre-cache behavior). Other harnesses do not use
+  // claude's plugin-dir flag — for them the cache (if any) is mirrored into
+  // the mount in `onBeforeLaunch`, not surfaced as an installRoot.
+  const installRoot =
+    harness === 'claude' && !options.installInRepo
+      ? skillCacheDir ?? (sessionRoot ? sessionInstallRoot(sessionRoot) : undefined)
+      : undefined;
+  // `repoRoot` lets the local skill provider (kind: 'local') resolve
+  // relative source paths like `.agentworkforce/workforce/skills/foo.md` to
+  // absolute paths before the install command runs. Critical for claude's
+  // installRoot mode, where the install runs `cd <installRoot> && cp ...`
+  // and a relative source would otherwise resolve against the wrong dir.
+  const install = buildInstallContext(effectiveSelection, {
+    ...(installRoot !== undefined ? { installRoot } : {}),
+    repoRoot: process.cwd()
+  });
+  process.stderr.write(`→ ${personaId} via ${harness} (${model})\n`);
+
+  // Upstream drift check (opt-in, TTL-gated). Only meaningful on a
+  // source-key hit — a miss reinstalls anyway, and a refresh is
+  // unconditional. Resolve the interval: --check-upstream forces (0 = always
+  // this launch), --no-check-upstream disables (null = never), otherwise the
+  // env var, otherwise the 24h default.
+  if (skillCacheSourceHit && skillCacheDir && skillCacheFingerprint) {
+    const intervalMs = options.checkUpstream
+      ? 0
+      : options.noCheckUpstream
+        ? null
+        : resolveEnvCheckIntervalMs();
+    const marker = readSkillCacheMarker(skillCacheDir);
+    if (marker && isUpstreamCheckDue(marker, intervalMs)) {
+      const spinner = ora({
+        text: 'Checking skills for upstream updates…',
+        stream: process.stderr
+      }).start();
+      try {
+        const { drifted, details } = await detectSkillUpstreamDrift(marker);
+        const moved = details.filter((d) => d.drifted);
+        if (drifted) {
+          spinner.warn(
+            `Upstream changed for ${moved.length} skill(s): ${moved
+              .map((d) => `${d.skillId} (${d.note})`)
+              .join(', ')}`
+          );
+          skillCacheHit = false;
+        } else {
+          spinner.succeed(
+            `Skills up to date (${details.length} checked) — reusing cache`
+          );
+          // Record the clean check so we don't re-probe until the TTL lapses.
+          updateSkillCacheMarkerUpstream(skillCacheDir, {
+            lastUpstreamCheckAt: new Date().toISOString()
+          });
+        }
+      } catch (err) {
+        // Fail-open: a probe-layer crash must never block the launch.
+        spinner.warn(
+          `Upstream check failed (${(err as Error).message}); using cached skills`
+        );
+      }
+    }
+  }
+
+  if (skillCacheFingerprint && skillCacheDir) {
+    if (skillCacheHit) {
+      process.stderr.write(
+        `• skill cache hit (${skillCacheFingerprint.slice(0, 12)}) → reusing ${skillCacheDir}\n`
+      );
+    } else if (options.refreshSkills) {
+      process.stderr.write(
+        `• skill cache refresh requested (${skillCacheFingerprint.slice(0, 12)}) → reinstalling into ${skillCacheDir}\n`
+      );
+    } else if (skillCacheSourceHit) {
+      process.stderr.write(
+        `• skill cache stale (${skillCacheFingerprint.slice(0, 12)}) → upstream drift, reinstalling into ${skillCacheDir}\n`
+      );
+    } else {
+      process.stderr.write(
+        `• skill cache miss (${skillCacheFingerprint.slice(0, 12)}) → installing into ${skillCacheDir}\n`
+      );
+    }
+  }
+
+  const startLaunchMetadataForLaunch = (cwd = process.cwd()) =>
+    startLaunchMetadataRecording({
+      selection: effectiveSelection,
+      personaSpec: options.personaSpec,
+      personaSource: options.personaSource,
+      cwd,
+      noLaunchMetadata: options.noLaunchMetadata,
+      env: process.env,
+      // Launch metadata ingest runs in the background while the user is reading
+      // persona output; route its warnings to the CLI log file rather than the
+      // terminal so a transient backend hiccup doesn't surface as scary noise.
+      onWarn: (msg) => launchMetadataLog.warn(msg)
+    });
+
+  const inputEnv = inputResolution.values;
+  const callerEnv = { ...process.env, ...inputEnv };
+  const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
+  const mcpResolution = resolveMcpServersLenient(effectiveSelection.mcpServers, callerEnv);
+  emitDropWarnings(
+    formatDropWarnings(envResolution.dropped, mcpResolution.dropped, mcpResolution.droppedServers)
+  );
+  const resolvedEnv =
+    Object.keys(inputEnv).length > 0 || envResolution.value
+      ? { ...(envResolution.value ?? {}), ...inputEnv }
+      : undefined;
+  const resolvedMcp = mcpResolution.servers;
+
+  // In session mode the install command is never `:` — it at minimum runs
+  // the plugin scaffold (mkdir + manifest + symlink) so `--plugin-dir` has a
+  // valid target even for skill-less local personas. Gate on the
+  // command string rather than `installs.length` so we don't skip that.
+  const skillIds = install.plan.installs.map((i) => i.skillId).join(', ');
+  const installLabel =
+    install.plan.installs.length === 0
+      ? `Staging session plugin dir${installRoot ? ` → ${installRoot}` : ''}`
+      : `Installing skills: ${skillIds}${installRoot ? ` → ${installRoot}` : ''}`;
+  // When useClean engages on a non-claude harness, the install must run
+  // INSIDE the mount so harness skill roots, prpm.lock, etc. land in the
+  // sandbox rather than the real repo. We defer it to `onBeforeLaunch`
+  // below instead of pre-running here.
+  const deferInstallToMount =
+    useClean && harness !== 'claude' && install.commandString !== ':';
+  if (
+    install.commandString !== ':' &&
+    !deferInstallToMount &&
+    !skillCacheHit
+  ) {
+    const cacheable = skillCachingEnabled && !!skillCacheDir && !!skillCacheFingerprint;
+    const lock =
+      cacheable && skillCacheDir ? await acquireSkillCacheLock(skillCacheDir) : null;
+    try {
+      // Re-check under the lock: a concurrent launch may have populated the
+      // cache while we waited. (Not on refresh — that's an explicit rebuild.)
+      const peerPopulated =
+        cacheable &&
+        !options.refreshSkills &&
+        skillCacheDir !== undefined &&
+        skillCacheFingerprint !== undefined &&
+        isSkillCacheValid(skillCacheDir, skillCacheFingerprint);
+      if (peerPopulated) {
+        process.stderr.write(
+          `• skill cache populated by a concurrent launch → reusing ${skillCacheDir}\n`
+        );
+      } else {
+        // `--refresh-skills`: wipe the entry first so the reinstall is a true
+        // rebuild — no stale files from a prior version, and a partial
+        // failure can't leave the old marker behind to fake a later hit.
+        // Done under the lock so a peer's in-progress install isn't clobbered.
+        if (options.refreshSkills && cacheable && skillCacheDir) {
+          rmSync(skillCacheDir, { recursive: true, force: true });
+        }
+        await runInstall(install.command, installLabel);
+        if (skillCacheFingerprint && skillCacheDir) {
+          await writeMarkerWithUpstream(
+            skillCacheDir,
+            skillCacheFingerprint,
+            harness,
+            effectiveSelection.skills.map((s) => ({ id: s.id, source: s.source }))
+          );
+        }
+      }
+    } finally {
+      lock?.release();
+    }
+  }
+
+  perfMark('runInteractive: install block done');
+  const relayMcp = resolveRelayMcpFromEnv(process.env);
+  const aiMemory = resolveAiMemory(effectiveSelection.memory);
+  const aiHist = aiMemory.enabled
+    ? resolveAiHistConfig(process.env, aiMemory.dbPath)
+    : undefined;
+  const brokerRelayHarness = relayMcp && (harness === 'claude' || harness === 'codex');
+  const specInput = {
+    harness,
+    personaId,
+    model,
+    systemPrompt,
+    harnessSettings,
+    mcpServers: resolvedMcp,
+    ...(aiHist ? { aiHist } : {}),
+    permissions: effectiveSelection.permissions,
+    ...(installRoot !== undefined ? { pluginDirs: [installRoot] } : {})
+  };
+  const spec = buildInteractiveSpec({
+    ...specInput,
+    ...(relayMcp && !brokerRelayHarness ? { relayMcp } : {})
+  });
+  for (const w of spec.warnings) process.stderr.write(`warning: ${w}\n`);
+  let spawnArgs = [...spec.args];
+
+  // Broker-aware relay MCP injection: prefer the broker binary's `mcp-args
+  // --register` subcommand (pre-mints RELAY_AGENT_TOKEN, sets
+  // RELAY_SKIP_BOOTSTRAP=1) over the legacy `@relaycast/mcp` self-registration
+  // path. Falls back to @relaycast/mcp when the broker binary is unavailable.
+  const cliRelayLog = (level: 'debug' | 'info' | 'warn' | 'error', message: string, attrs?: Record<string, unknown>) => {
+    if (level === 'warn' || level === 'error') {
+      process.stderr.write(`warning: ${message}${attrs ? ` ${JSON.stringify(attrs)}` : ''}\n`);
+    }
+  };
+  if (relayMcp && harness === 'claude') {
+    if (claudeMcpConfigHasRelayOverride(spawnArgs)) {
+      process.stderr.write('• relay: persona overrides relay MCP config\n');
+    } else {
+      const brokerMcpArgs = await resolveAgentRelayBrokerMcpArgs({
+        cli: 'claude',
+        env: process.env,
+        relayMcp,
+        cwd: process.cwd(),
+        existingArgs: [],
+        log: cliRelayLog
+      });
+      const mergedArgs = brokerMcpArgs
+        ? injectClaudeAgentRelayMcpConfig(spawnArgs, brokerMcpArgs, cliRelayLog)
+        : undefined;
+      if (mergedArgs) {
+        spawnArgs = mergedArgs;
+        process.stderr.write('• relay: agent-relay (broker pre-registered)\n');
+      } else {
+        const fallbackSpec = buildInteractiveSpec({ ...specInput, relayMcp });
+        spawnArgs = [...fallbackSpec.args];
+        process.stderr.write('• relay: @relaycast/mcp (fallback)\n');
+      }
+    }
+  } else if (relayMcp && harness === 'codex') {
+    const brokerMcpArgs = await resolveAgentRelayBrokerMcpArgs({
+      cli: 'codex',
+      env: process.env,
+      relayMcp,
+      cwd: process.cwd(),
+      existingArgs: codexExistingArgs(spawnArgs),
+      log: cliRelayLog
+    });
+    if (brokerMcpArgs) {
+      spawnArgs = injectCodexSubcommandArgs(spawnArgs, brokerMcpArgs);
+      process.stderr.write('• relay: agent-relay (broker pre-registered)\n');
+    } else {
+      const fallbackSpec = buildInteractiveSpec({ ...specInput, relayMcp });
+      spawnArgs = [...fallbackSpec.args];
+      process.stderr.write('• relay: @relaycast/mcp (fallback)\n');
+    }
+  }
+
+  // Config-file materialization strategy:
+  //  - Mount path (default): write each configFile into the
+  //    mount dir via onBeforeLaunch, so it lives only in the sandbox and is
+  //    torn down with the session.
+  //  - Non-mount path: today the only configFile producer is opencode
+  //    (opencode.json for the --agent wiring), and the non-mount opencode
+  //    path only engages under --install-in-repo. Writing opencode.json
+  //    into the user's real repo would pollute the working tree, so we
+  //    degrade: drop --agent from the argv, warn, and launch opencode with
+  //    its default agent. The persona's prompt will not be applied in that
+  //    mode; users who want it should drop --install-in-repo (the mount
+  //    default handles this cleanly).
+  const hasConfigFiles = spec.configFiles.length > 0;
+  const degradeConfigFiles = hasConfigFiles && !useClean;
+  let effectiveArgs: readonly string[] = spawnArgs;
+  if (degradeConfigFiles) {
+    process.stderr.write(
+      'warning: --install-in-repo cannot safely materialize the persona agent config (would write opencode.json into your repo); launching without --agent. Drop --install-in-repo to apply the persona prompt.\n'
+    );
+    effectiveArgs = stripAgentFlag(spawnArgs);
+  }
+  const finalArgs = spec.initialPrompt ? [...effectiveArgs, spec.initialPrompt] : [...effectiveArgs];
+
+  // Print a sanitized summary rather than raw argv: spec.args for the claude
+  // harness contains the resolved --mcp-config JSON and the full system
+  // prompt, either of which can carry secrets (Bearer tokens, API keys) once
+  // env refs are interpolated. We show the bin, model, and the *names* of
+  // the servers / permission fields so the user can verify the shape without
+  // leaking credentials to stderr or CI logs.
+  const summary = buildSpawnSummary({
+    harness,
+    model,
+    spec,
+    permissions: effectiveSelection.permissions,
+    useClean
+  });
+  process.stderr.write(`• spawning ${spec.bin} (${summary.join(', ')})\n`);
+  perfMark('runInteractive: harness spec + relay MCP resolved');
+
+
+  // Mount branch: delegate process lifecycle (spawn, signal forwarding,
+  // syncback, cleanup) to @relayfile/local-mount.
+  //
+  // For interactive harnesses: mount engages by default (unless
+  // `--install-in-repo`). For claude this hides CLAUDE.md / .claude /
+  // .mcp.json; for non-claude harnesses it routes `npx prpm install` /
+  // `npx skills add` writes into the sandbox (skill plugin dir for claude
+  // lives outside the mount at an absolute path, so claude still resolves
+  // `--plugin-dir` normally).
+  //
+  // The install itself runs inside the mount via `onBeforeLaunch` so that
+  // `npx prpm install` / `npx skills add` writes land in the sandbox. The
+  // skill-install paths are added to `ignoredPatterns` so they are neither
+  // copied in from the real repo nor synced back on exit.
+  if (useClean && sessionRoot) {
+    const mountDir = sessionMountDir(sessionRoot);
+    let launchMetadata: LaunchMetadataRun | undefined;
+    // Anything we materialize into the mount via onBeforeLaunch must be
+    // hidden from the mount-mirror in both directions: without this, any
+    // opencode.json already present in the real repo would be copied into
+    // the mount (masking the per-session agent config we write), and the
+    // fresh write from onBeforeLaunch would sync back out on exit and
+    // pollute the user's working tree. Added dynamically so this stays
+    // generic for any future configFile producer.
+    const { ignoredPatterns, readonlyPatterns } = buildRelayfileMountPatterns({
+      projectDir: process.cwd(),
+      personaId,
+      harness,
+      mount: effectiveSelection.mount,
+      configFilePaths: spec.configFiles.map((file) => file.path)
+    });
+    // Warm-launch plan for the NEXT invocation of this selector. Built at
+    // resolution time (digests must reflect the inputs this argv came from),
+    // consumed at teardown if the session ends cleanly.
+    const fastPlan =
+      options.selector && skillCachingEnabled
+        ? buildFastLaunchPlan({
+            selector: options.selector,
+            personaId,
+            harness,
+            model,
+            selection,
+            effectiveSelection,
+            relayMcp,
+            envResolutionValue: envResolution.value,
+            inputEnv,
+            resolvedMcp,
+            aiHist,
+            skillCacheDir,
+            skillCacheFingerprint,
+            bin: spec.bin,
+            finalArgs,
+            ignoredPatterns,
+            readonlyPatterns
+          })
+        : null;
+    // 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 | undefined = 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 — 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: Ora | undefined;
+    let isSyncing = false;
+    let childSpawned = false;
+    let abortPresses = 0;
+    const sigintHandler = () => {
+      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) {
+          syncSpinner.text =
+            'Aborting sync — partial changes will be propagated. (Ctrl-C again to force quit)';
+        }
+        shutdownController.abort();
+        return;
+      }
+      if (syncSpinner) {
+        syncSpinner.fail('Force-quit: mount teardown skipped. Session dir may be left behind.');
+        syncSpinner = undefined;
+      } else {
+        process.stderr.write(
+          '\n✗ Force-quit: mount teardown skipped. Session dir may be left behind.\n'
+        );
+      }
+      try {
+        rmSync(sessionRoot, { recursive: true, force: true });
+      } catch {
+        /* swallow — we're exiting anyway */
+      }
+      process.exit(130);
+    };
+    process.on('SIGINT', sigintHandler);
+
+    let handle: Awaited<ReturnType<typeof createMount>> | undefined;
+    let autoSync: AutoSyncHandle | undefined;
+    let exitCode = 0;
+    try {
+      // createMount inside the try so its initial-mirror failures fall into
+      // the catch path and clean up the setup spinner.
+      perfMark('mount: createMount start');
+      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,
+        // Enumerate via `git ls-files` when the cwd is a git checkout: only
+        // tracked + untracked-unignored files enter the mount, so gitignored
+        // trees (worktrees, build outputs, caches) never get mirrored or
+        // rescanned by autosync/syncBack. Falls back to the walk elsewhere.
+        population: 'auto'
+      });
+      // 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.
+      perfMark('mount: createMount done');
+      configureGitForMount(handle.mountDir, ignoredPatterns);
+      perfMark('mount: git configured');
+      if (deferInstallToMount) {
+        // Cache-aware mount install:
+        //   - If we have a cache hit, skip the install and just mirror the
+        //     pre-populated cache dir into the mount. `npx prpm install`
+        //     never runs and no install spinner is needed.
+        //   - On miss (or `--refresh-skills`), run the install once with
+        //     cwd set to the cache dir so artifacts land in the persistent
+        //     location, then mirror into the mount and write the marker.
+        //   - With caching disabled (`--install-in-repo` or
+        //     `--no-skill-cache`), fall back to the legacy in-mount install.
+        //
+        // The setup spinner is only stopped around branches that print their
+        // own spinner (install) so the two don't fight for the same stream.
+        // The pure cache-hit path is a near-instant cpSync — leaving the
+        // setup spinner running avoids a redundant "Setting up sandbox
+        // mount…" redraw in the user-visible output.
+        if (skillCacheHit && skillCacheDir) {
+          mirrorSkillCacheInto(skillCacheDir, handle.mountDir);
+        } else if (skillCachingEnabled && skillCacheDir && skillCacheFingerprint) {
+          const lock = await acquireSkillCacheLock(skillCacheDir);
+          try {
+            // A concurrent launch may have populated the cache while we
+            // waited for the lock — mirror it instead of reinstalling.
+            // (Skipped on refresh, which is an explicit rebuild.)
+            if (
+              !options.refreshSkills &&
+              isSkillCacheValid(skillCacheDir, skillCacheFingerprint)
+            ) {
+              mirrorSkillCacheInto(skillCacheDir, handle.mountDir);
+            } else {
+              setupSpinner?.stop();
+              // `--refresh-skills`: wipe first so the reinstall is a true
+              // rebuild and a partial failure can't leave a stale marker.
+              if (options.refreshSkills) {
+                rmSync(skillCacheDir, { recursive: true, force: true });
+              }
+              mkdirSync(skillCacheDir, { recursive: true });
+              await runInstallOrThrow(install.command, installLabel, skillCacheDir);
+              await writeMarkerWithUpstream(
+                skillCacheDir,
+                skillCacheFingerprint,
+                harness,
+                effectiveSelection.skills.map((s) => ({ id: s.id, source: s.source }))
+              );
+              mirrorSkillCacheInto(skillCacheDir, handle.mountDir);
+              setupSpinner?.start();
+            }
+          } finally {
+            lock?.release();
+          }
+        } else {
+          setupSpinner?.stop();
+          await runInstallOrThrow(install.command, installLabel, handle.mountDir);
+          setupSpinner?.start();
+        }
+      }
+      perfMark('mount: skills mirrored/installed');
+      for (const file of spec.configFiles) {
+        assertSafeRelativePath(file.path);
+        const target = join(handle.mountDir, file.path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, file.contents, 'utf8');
+      }
+      if (resolvedSidecar) {
+        const body = buildSidecarBody(resolvedSidecar, process.cwd());
+        writeFileSync(join(handle.mountDir, resolvedSidecar.mountFile), body, 'utf8');
+      }
+      perfMark('mount: config files + sidecar written');
+      launchMetadata = await startLaunchMetadataForLaunch(handle.mountDir);
+      perfMark('mount: launch metadata started');
+      if (options.capture) {
+        options.capture.stampEnrichment = { ...launchMetadata.metadata };
+        options.capture.stampingEnabled = launchMetadata.enabled;
+      }
+
+      autoSync = handle.startAutoSync();
+      perfMark('mount: autosync started');
+
+      // Stop the setup spinner before spawning the child — the child
+      // inherits stdio and would otherwise interleave its output with
+      // spinner frames.
+      setupSpinner?.succeed(formatSandboxMountReadyMessage(mountDir, handle));
+      setupSpinner = undefined;
+
+      const childEnv = resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env;
+      const childCwd = handle.mountDir;
+      if (options.capture) {
+        options.capture.sessionCwd = childCwd;
+        options.capture.harness = 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;
+      perfMark('spawn: harness child spawning');
+      exitCode = await new Promise<number>((resolve, reject) => {
+        const child = spawn(spec.bin, finalArgs, {
+          cwd: childCwd,
+          stdio: 'inherit',
+          env: childEnv
+        });
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+          if (typeof code === 'number') resolve(code);
+          else if (signal) resolve(signalExitCode(signal));
+          else resolve(1);
+        });
+      });
+
+      // Child exited — start the spinner immediately so the sync-back is
+      // visibly live rather than a silent pause.
+      perfMark('exit: harness child exited');
+      isSyncing = true;
+      syncSpinner = ora({
+        text: 'Syncing session changes back to the repo… (Ctrl-C to skip)',
+        stream: process.stderr
+      }).start();
+
+      let count = 0;
+      let exportedState: Record<string, FileState> | undefined;
+      if (autoSync) {
+        if (fastPlan && !shutdownController.signal.aborted) {
+          // Full pass before stopping so the exported state also covers
+          // paths only reconciles visit (`.git/**` under includeGit) —
+          // without those entries, files git gc removes from the project
+          // between sessions would survive as stale copies in the warm
+          // mount. Re-warming is best-effort; a failure here only costs
+          // the next launch its fast path.
+          try {
+            await autoSync.reconcile({ signal: shutdownController.signal });
+          } catch {
+            /* fall through to the normal drain */
+          }
+        }
+        await autoSync.stop({ signal: shutdownController.signal });
+        count += autoSync.totalChanges();
+        if (fastPlan && !shutdownController.signal.aborted) {
+          try {
+            exportedState = autoSync.exportState();
+          } catch {
+            /* re-warm skipped below */
+          }
+        }
+        autoSync = undefined;
+      }
+      perfMark('exit: autosync stopped (draining reconcile done)');
+      // NOTE: `count` is bidirectional — it sums autosync activity in both
+      // directions (inbound project→mount and outbound mount→project,
+      // including deletes) plus the final mount→project syncBack. Phrase as
+      // "file events during session" so we don't overclaim direction.
+      count += await handle.syncBack({ signal: shutdownController.signal });
+      perfMark('exit: final syncBack done');
+
+      const aborted = shutdownController.signal.aborted;
+      if (fastPlan && exportedState && !aborted) {
+        // The session settled cleanly: keep the mount warm for the next
+        // launch instead of discarding it. cleanup()/removeSessionRoot in
+        // the finally below no-op on the moved-away mount dir.
+        rewarmMountAndPlan({ plan: fastPlan, mountDir: handle.mountDir, exportedState });
+      }
+      const qualifier = aborted ? ' (partial)' : '';
+      const message =
+        count > 0
+          ? `Session complete — ${count} file event${count === 1 ? '' : 's'} during session${qualifier}.`
+          : 'Session complete — no file events.';
+      syncSpinner.succeed(message);
+      syncSpinner = undefined;
+      return exitCode;
+    } catch (err) {
+      if (setupSpinner) {
+        setupSpinner.fail('Sandbox mount setup failed');
+        setupSpinner = undefined;
+      }
+      if (syncSpinner) {
+        syncSpinner.fail('Sync did not complete');
+        syncSpinner = undefined;
+      }
+      // InstallCommandError carries the real install exit code — surfacing
+      // it (rather than collapsing onto 127) lets callers distinguish a
+      // failed `npx prpm install` from a missing harness binary. The message
+      // itself was already shown via spinner.fail inside runInstallWithSpinner,
+      // so we just return the code here.
+      if (err instanceof InstallCommandError) {
+        return err.exitCode;
+      }
+      const e = err as NodeJS.ErrnoException;
+      if (e.code === 'ENOENT') {
+        process.stderr.write(
+          `Failed to spawn "${spec.bin}" inside sandbox mount: binary not found on PATH. Install the ${harness} CLI and retry.\n`
+        );
+        return 127;
+      }
+      process.stderr.write(`Failed to launch sandbox mount: ${e.message}\n`);
+      return 1;
+    } finally {
+      if (setupSpinner) {
+        setupSpinner.stop();
+        setupSpinner = undefined;
+      }
+      if (syncSpinner) {
+        syncSpinner.stop();
+        syncSpinner = undefined;
+      }
+      // Best-effort: stop autosync if we errored out before the success path
+      // already cleared it.
+      if (autoSync) {
+        try {
+          await autoSync.stop({ signal: shutdownController.signal });
+        } catch {
+          /* ignore — we're tearing down anyway */
+        }
+      }
+      handle?.cleanup();
+      await launchMetadata?.stop();
+      process.removeListener('SIGINT', sigintHandler);
+      // When the install ran inside the mount, its cleanup paths are
+      // mount-relative (e.g. `.skills/<name>`, `skills/<name>`) and running
+      // cleanup here would resolve them against the real repo cwd —
+      // potentially `rm -rf`ing pre-existing user content. The mount dir is
+      // removed wholesale by `removeSessionRoot` below, so the install's
+      // cleanup is redundant anyway in that case.
+      //
+      // Skill caching also suppresses the cleanup: the cache dir IS the
+      // persistence layer, so the rm command (which targets the
+      // sessionInstallRoot — now pointing at the cache dir for claude) would
+      // wipe the very thing we want to keep across launches.
+      if (!deferInstallToMount && !skillCachingEnabled) {
+        runCleanup(install.cleanupCommand, install.cleanupCommandString);
+      }
+      removeSessionRoot(sessionRoot);
+    }
+  }
+
+  const launchMetadata = await startLaunchMetadataForLaunch();
+  if (options.capture) {
+    options.capture.sessionCwd = process.cwd();
+    options.capture.harness = 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: number) => {
+      if (settled) return;
+      settled = true;
+      // Skill caching takes ownership of the install dir; running cleanup
+      // here would `rm -rf` the persistent cache. Skip in that case and
+      // rely on the cache marker as the source of truth for "valid install".
+      if (!skillCachingEnabled) {
+        runCleanup(install.cleanupCommand, install.cleanupCommandString);
+      }
+      removeSessionRoot(sessionRoot);
+      void launchMetadata.stop().finally(() => resolve(code));
+    };
+
+    const child = spawn(spec.bin, finalArgs, {
+      stdio: 'inherit',
+      env: resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env
+    });
+
+    const forward = (signal: NodeJS.Signals) => {
+      if (!child.killed) child.kill(signal);
+    };
+    process.on('SIGINT', () => forward('SIGINT'));
+    process.on('SIGTERM', () => forward('SIGTERM'));
+
+    child.on('exit', (code, signal) => {
+      finish(code ?? signalExitCode(signal));
+    });
+    child.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'ENOENT') {
+        process.stderr.write(
+          `Failed to spawn "${spec.bin}": binary not found on PATH. Install the ${harness} CLI and retry.\n`
+        );
+      } else {
+        process.stderr.write(`Failed to spawn "${spec.bin}": ${err.message}\n`);
+      }
+      finish(127);
+    });
+  });
+}
+
+function formatAvailabilityTable(results: readonly HarnessAvailability[]): string {
+  const rows = results.map((r) => ({
+    harness: r.harness,
+    status: r.available ? 'ok' : 'missing',
+    version: r.available ? (r.version ?? '') : '',
+    detail: r.available ? (r.path ?? '') : (r.error ?? '')
+  }));
+  const headers = { harness: 'HARNESS', status: 'STATUS', version: 'VERSION', detail: 'DETAIL' };
+  const cols = ['harness', 'status', 'version', 'detail'] as const;
+  const widths = Object.fromEntries(
+    cols.map((c) => [c, Math.max(headers[c].length, ...rows.map((r) => r[c].length))])
+  ) as Record<(typeof cols)[number], number>;
+  const line = (row: Record<(typeof cols)[number], string>) =>
+    cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
+  return [line(headers), ...rows.map(line)].join('\n') + '\n';
+}
+
+interface SourceDirRow {
+  cascade: string;
+  config: string;
+  source: string;
+  exists: string;
+  dir: string;
+}
+
+function collectSourceDirRows(): {
+  configPath: string;
+  personaDirs: string[];
+  defaultCreateTarget?: string;
+  rows: SourceDirRow[];
+} {
+  const { directories, config } = buildPersonaSourceDirectories();
+  const rows: SourceDirRow[] = directories.map((sourceDir, idx) => ({
+    cascade: String(idx + 1),
+    config: sourceDir.configurable ? String(config.personaDirs.indexOf(sourceDir.dir) + 1) : '-',
+    source: sourceDir.source,
+    exists: existsSync(sourceDir.dir) ? 'yes' : 'no',
+    dir: sourceDir.dir
+  }));
+  rows.push({
+    cascade: String(rows.length + 1),
+    config: '-',
+    source: 'library',
+    exists: 'yes',
+    dir: '(built-in)'
+  });
+  return {
+    configPath: config.configPath,
+    personaDirs: config.personaDirs,
+    ...(config.defaultCreateTarget ? { defaultCreateTarget: config.defaultCreateTarget } : {}),
+    rows
+  };
+}
+
+function formatSourcesTable(
+  rows: readonly SourceDirRow[],
+  configPath: string,
+  defaultCreateTarget: string | undefined
+): string {
+  const headers: SourceDirRow = {
+    cascade: 'CASCADE',
+    config: 'CONFIG',
+    source: 'SOURCE',
+    exists: 'EXISTS',
+    dir: 'DIR'
+  };
+  const cols = ['cascade', 'config', 'source', 'exists', 'dir'] as const;
+  // Display label only — the underlying `source` literal flows through to
+  // --json so tooling that pins on `'cwd'` / `'user'` / `'library'` is fine.
+  const display: readonly SourceDirRow[] = rows.map((r) => ({
+    ...r,
+    source: formatPersonaSourceLabel(r.source)
+  }));
+  const widths = Object.fromEntries(
+    cols.map((c) => [c, Math.max(headers[c].length, ...display.map((r) => r[c].length))])
+  ) as Record<(typeof cols)[number], number>;
+  const line = (row: SourceDirRow) =>
+    cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
+  return [
+    `Config: ${configPath}`,
+    `Default create target: ${defaultCreateTarget ?? '(auto)'}`,
+    [line(headers), ...display.map(line)].join('\n'),
+    ''
+  ].join('\n');
+}
+
+function parseSourcesListArgs(args: readonly string[]): { json: boolean } {
+  let json = false;
+  for (const arg of args) {
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '-h' || arg === '--help') {
+      process.stdout.write('Usage: agentworkforce sources list [--json]\n');
+      process.exit(0);
+    } else {
+      die(`sources list: unexpected argument "${arg}".`);
+    }
+  }
+  return { json };
+}
+
+function runSourcesList(args: readonly string[]): never {
+  const { json } = parseSourcesListArgs(args);
+  const { configPath, personaDirs, defaultCreateTarget, rows } = collectSourceDirRows();
+  if (json) {
+    process.stdout.write(
+      JSON.stringify({ configPath, personaDirs, defaultCreateTarget, sources: rows }, null, 2) + '\n'
+    );
+  } else {
+    process.stdout.write(formatSourcesTable(rows, configPath, defaultCreateTarget));
+  }
+  process.exit(0);
+}
+
+function assertDirectoryForAdd(dir: string): void {
+  try {
+    if (!existsSync(dir)) {
+      die(`sources add: directory does not exist: ${dir}`);
+    }
+    if (!statSync(dir).isDirectory()) {
+      die(`sources add: path is not a directory: ${dir}`);
+    }
+  } catch (err) {
+    if ((err as Error).message.startsWith('sources add:')) throw err;
+    die(`sources add: could not inspect ${dir}: ${(err as Error).message}`);
+  }
+}
+
+function parseSourcesAddArgs(args: readonly string[]): { dir: string; position?: number } {
+  let dir: string | undefined;
+  let position: number | undefined;
+  const valueOf = (i: number, flag: string): string => {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      die(`sources add: ${flag} requires a value.`);
+    }
+    return v;
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      process.stdout.write('Usage: agentworkforce sources add <dir> [--position <n>]\n');
+      process.exit(0);
+    } else if (arg === '--position') {
+      const raw = valueOf(i++, arg);
+      const parsed = Number(raw);
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        die(`sources add: --position must be a positive integer.`);
+      }
+      position = parsed;
+    } else if (arg.startsWith('--')) {
+      die(`sources add: unexpected flag "${arg}".`);
+    } else if (dir === undefined) {
+      dir = arg;
+    } else {
+      die(`sources add: unexpected argument "${arg}".`);
+    }
+  }
+  if (!dir) die('sources add: missing directory.');
+  return { dir, position };
+}
+
+function runSourcesAdd(args: readonly string[]): never {
+  const { dir: rawDir, position } = parseSourcesAddArgs(args);
+  const dir = normalizePersonaDir(rawDir);
+  assertDirectoryForAdd(dir);
+
+  const config = loadPersonaSourceConfig();
+  if (config.personaDirs.includes(dir)) {
+    die(`sources add: directory is already configured: ${dir}`);
+  }
+  const insertAt = position === undefined ? config.personaDirs.length : position - 1;
+  if (insertAt < 0 || insertAt > config.personaDirs.length) {
+    die(
+      `sources add: --position must be between 1 and ${config.personaDirs.length + 1}.`
+    );
+  }
+  const nextDirs = [...config.personaDirs];
+  nextDirs.splice(insertAt, 0, dir);
+  const saved = savePersonaSourceConfig(nextDirs);
+  process.stdout.write(
+    `Added persona source directory at configurable position ${insertAt + 1}: ${dir}\nConfig: ${saved.configPath}\n`
+  );
+  process.exit(0);
+}
+
+function parseSourcesRemoveArgs(args: readonly string[]): { target: string } {
+  let target: string | undefined;
+  for (const arg of args) {
+    if (arg === '-h' || arg === '--help') {
+      process.stdout.write('Usage: agentworkforce sources remove <dir|config-position>\n');
+      process.exit(0);
+    } else if (arg.startsWith('--')) {
+      die(`sources remove: unexpected flag "${arg}".`);
+    } else if (target === undefined) {
+      target = arg;
+    } else {
+      die(`sources remove: unexpected argument "${arg}".`);
+    }
+  }
+  if (!target) die('sources remove: missing directory or config-position.');
+  return { target };
+}
+
+function runSourcesRemove(args: readonly string[]): never {
+  const { target } = parseSourcesRemoveArgs(args);
+  const config = loadPersonaSourceConfig();
+  let idx: number;
+  if (/^[1-9]\d*$/.test(target)) {
+    idx = Number(target) - 1;
+  } else {
+    const dir = normalizePersonaDir(target);
+    idx = config.personaDirs.indexOf(dir);
+  }
+  if (idx < 0 || idx >= config.personaDirs.length) {
+    die(`sources remove: no configurable persona source matched "${target}".`);
+  }
+  const nextDirs = [...config.personaDirs];
+  const [removed] = nextDirs.splice(idx, 1);
+  const saved = savePersonaSourceConfig(nextDirs);
+  process.stdout.write(
+    `Removed persona source directory from configurable position ${idx + 1}: ${removed}\nConfig: ${saved.configPath}\n`
+  );
+  process.exit(0);
+}
+
+function runSources(args: readonly string[]): never {
+  const [action, ...rest] = args;
+  if (!action || action === '-h' || action === '--help') {
+    process.stdout.write(
+      'Usage: agentworkforce sources <list|add|remove> [args...]\n' +
+        '  agentworkforce sources list [--json]\n' +
+        '  agentworkforce sources add <dir> [--position <n>]\n' +
+        '  agentworkforce sources remove <dir|config-position>\n'
+    );
+    process.exit(action ? 0 : 1);
+  }
+  if (action === 'list') runSourcesList(rest);
+  if (action === 'add') runSourcesAdd(rest);
+  if (action === 'remove') runSourcesRemove(rest);
+  die(`sources: unknown action "${action}". Expected: list, add, remove.`);
+}
+
+export interface PersonaInstallArgs {
+  source: string;
+  personaIds: string[];
+  overwrite: boolean;
+}
+
+export function parseInstallArgs(args: readonly string[]): PersonaInstallArgs {
+  let source: string | undefined;
+  const personaIds: string[] = [];
+  let overwrite = false;
+  const valueOf = (i: number, flag: string): string => {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      throw new Error(`install: ${flag} requires a value.`);
+    }
+    return v;
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--overwrite') {
+      overwrite = true;
+    } else if (arg === '--persona') {
+      const value = valueOf(i++, arg);
+      if (!value.trim()) throw new Error('install: --persona requires a non-empty value.');
+      personaIds.push(value);
+    } else if (arg.startsWith('--')) {
+      throw new Error(`install: unexpected flag "${arg}".`);
+    } else if (source === undefined) {
+      source = arg;
+    } else {
+      throw new Error(`install: unexpected argument "${arg}".`);
+    }
+  }
+
+  if (!source) throw new Error('install: missing package or local path.');
+  return { source, personaIds, overwrite };
+}
+
+function formatPersonaInstallSummary(result: PersonaInstallResult): string {
+  const lines: string[] = [];
+  for (const persona of result.installed) {
+    lines.push(`installed ${persona.id} -> ${persona.targetPath}`);
+  }
+  if (result.installed.length > 0) {
+    lines.push(
+      `Installed ${result.installed.length} persona(s) into ${result.targetDir}.`
+    );
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+
+function formatPersonaInstallConflicts(result: PersonaInstallResult): string {
+  if (result.conflicts.length === 0) return '';
+  const lines = result.conflicts.map(
+    (conflict) =>
+      `conflict ${conflict.id}: ${conflict.targetPath} already exists (use --overwrite to replace it)`
+  );
+  lines.push(
+    `Skipped ${result.conflicts.length} existing persona file(s); re-run with --overwrite to replace.`
+  );
+  return lines.join('\n') + '\n';
+}
+
+function runPersonaInstall(args: readonly string[]): never {
+  if (args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(
+      'Usage: agentworkforce install <pkg|path> [--persona <id> ...] [--overwrite]\n'
+    );
+    process.exit(0);
+  }
+  let parsed: PersonaInstallArgs;
+  try {
+    parsed = parseInstallArgs(args);
+  } catch (err) {
+    die((err as Error).message);
+  }
+
+  let result: PersonaInstallResult;
+  try {
+    result = installPersonas({
+      source: parsed.source,
+      personaIds: parsed.personaIds,
+      overwrite: parsed.overwrite
+    });
+  } catch (err) {
+    die((err as Error).message, false);
+  }
+
+  process.stdout.write(formatPersonaInstallSummary(result));
+  process.stderr.write(formatPersonaInstallConflicts(result));
+  process.exit(result.conflicts.length > 0 ? 1 : 0);
+}
+
+interface PersonaListRow {
+  persona: string;
+  source: PersonaSource;
+  harness: string;
+  model: string;
+  intent: string;
+  tags: readonly PersonaTag[];
+  description: string;
+}
+
+function collectPersonaRows(): PersonaListRow[] {
+  const rows: PersonaListRow[] = [];
+  const pushSpec = (spec: PersonaSpec, source: PersonaSource): void => {
+    rows.push({
+      persona: spec.id,
+      source,
+      harness: spec.harness ?? '—',
+      model: spec.model ?? '—',
+      intent: spec.intent,
+      tags: spec.tags ?? [],
+      description: spec.description
+    });
+  };
+  const seen = new Set<string>();
+  for (const [id, spec] of local.byId) {
+    pushSpec(spec, local.sources.get(id) ?? 'library');
+    seen.add(id);
+  }
+  for (const spec of listBuiltInPersonas()) {
+    if (seen.has(spec.id)) continue;
+    pushSpec(spec, 'library');
+  }
+  return rows.sort((a, b) => a.persona.localeCompare(b.persona));
+}
+
+interface ListDisplayOptions {
+  description: boolean;
+}
+
+function formatPersonaTable(
+  rows: readonly PersonaListRow[],
+  display: ListDisplayOptions
+): string {
+  interface RenderRow {
+    persona: string;
+    source: string;
+    harness: string;
+    model: string;
+    tags: string;
+    description: string;
+  }
+  const headers: RenderRow = {
+    persona: 'PERSONA',
+    source: 'SOURCE',
+    harness: 'HARNESS',
+    model: 'MODEL',
+    tags: 'TAGS',
+    description: 'DESCRIPTION'
+  };
+  const rendered: RenderRow[] = rows.map((r) => ({
+    persona: r.persona,
+    source: formatPersonaSourceLabel(r.source),
+    harness: r.harness,
+    model: r.model,
+    tags: r.tags.join(','),
+    description: r.description
+  }));
+  const widths = {
+    persona: Math.max(headers.persona.length, ...rendered.map((r) => r.persona.length)),
+    source: Math.max(headers.source.length, ...rendered.map((r) => r.source.length)),
+    harness: Math.max(headers.harness.length, ...rendered.map((r) => r.harness.length)),
+    model: Math.max(headers.model.length, ...rendered.map((r) => r.model.length)),
+    tags: Math.max(headers.tags.length, ...rendered.map((r) => r.tags.length)),
+    description: headers.description.length
+  };
+  const termWidth =
+    process.stdout.isTTY && typeof process.stdout.columns === 'number' ? process.stdout.columns : 140;
+  const fixed =
+    widths.persona +
+    widths.source +
+    widths.harness +
+    widths.model +
+    widths.tags +
+    (5 + (display.description ? 1 : 0) - 1) * 2;
+  const descBudget = Math.max(20, termWidth - fixed - 1);
+  const truncate = (s: string, n: number) => (s.length <= n ? s : s.slice(0, Math.max(1, n - 1)) + '…');
+  const line = (row: RenderRow) => {
+    const parts = [
+      row.persona.padEnd(widths.persona),
+      row.source.padEnd(widths.source),
+      row.harness.padEnd(widths.harness),
+      row.model.padEnd(widths.model),
+      row.tags.padEnd(widths.tags)
+    ];
+    if (display.description) {
+      parts.push(truncate(row.description.replace(/\s+/g, ' ').trim(), descBudget));
+    }
+    return parts.join('  ').trimEnd();
+  };
+  return [line(headers), ...rendered.map(line)].join('\n') + '\n';
+}
+
+function parseListArgs(args: readonly string[]): {
+  json: boolean;
+  filterHarness?: Harness;
+  filterTag?: PersonaTag;
+  display: ListDisplayOptions;
+  deployments: boolean;
+} {
+  let json = false;
+  let filterHarness: Harness | undefined;
+  let filterTag: PersonaTag | undefined;
+  const display: ListDisplayOptions = { description: true };
+  let deployments = false;
+
+  const valueOf = (i: number, flag: string): string => {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      die(`list: ${flag} requires a value.`);
+    }
+    return v;
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--deployments') {
+      deployments = true;
+    } else if (arg === '-h' || arg === '--help') {
+      process.stdout.write(
+        'Usage: agentworkforce list [--deployments] [--status <status>] [--persona <slug>] [--json] [--filter-harness <harness>] [--filter-tag <tag>] [--no-display-description]\n'
+      );
+      process.exit(0);
+    } else if (arg === '--filter-harness') {
+      const v = valueOf(i++, arg);
+      if (!(HARNESS_VALUES as readonly string[]).includes(v)) {
+        die(`list: invalid --filter-harness "${v}". Must be one of: ${HARNESS_VALUES.join(', ')}`);
+      }
+      filterHarness = v as Harness;
+    } else if (arg === '--filter-tag') {
+      const v = valueOf(i++, arg);
+      const trimmed = v.trim();
+      if (!trimmed) {
+        die('list: --filter-tag requires a non-empty value.');
+      }
+      filterTag = trimmed as PersonaTag;
+    } else if (arg === '--display-description') {
+      display.description = true;
+    } else if (arg === '--no-display-description') {
+      display.description = false;
+    } else {
+      die(`list: unexpected argument "${arg}".`);
+    }
+  }
+  return { json, filterHarness, filterTag, display, deployments };
+}
+
+async function runList(args: readonly string[]): Promise<never> {
+  if (args.includes('--deployments')) {
+    const { runDeploymentList } = await import('./list-command.js');
+    await runDeploymentList(args.filter((arg) => arg !== '--deployments'));
+    process.exit(0);
+  }
+
+  const { json, filterHarness, filterTag, display } = parseListArgs(args);
+
+  const rows = collectPersonaRows().filter((r) => {
+    if (filterHarness && r.harness !== filterHarness) return false;
+    if (filterTag && !r.tags.includes(filterTag)) return false;
+    return true;
+  });
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ personas: rows }, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatPersonaTable(rows, display));
+    process.stdout.write(`\n${rows.length} persona(s).\n`);
+  }
+  process.exit(0);
+}
+
+function parseShowArgs(args: readonly string[]): {
+  selector: string;
+  json: boolean;
+} {
+  let json = false;
+  let selector: string | undefined;
+  for (const arg of args) {
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '-h' || arg === '--help') {
+      process.stdout.write('Usage: agentworkforce show <persona> [--json]\n');
+      process.exit(0);
+    } else if (arg.startsWith('--')) {
+      die(`show: unexpected flag "${arg}".`);
+    } else if (selector === undefined) {
+      selector = arg;
+    } else {
+      die(`show: unexpected argument "${arg}".`);
+    }
+  }
+  if (!selector) die('show: missing persona name.');
+  return { selector, json };
+}
+
+function resolveShowTarget(selector: string): { spec: PersonaSpec; source: PersonaSource } {
+  if (selector.includes('@')) {
+    die(
+      'show: @<tier> selectors were removed; tiers are no longer part of the persona shape. ' +
+        `Use 'agentworkforce show ${selector.slice(0, selector.indexOf('@'))}' instead.`,
+      false
+    );
+  }
+  const key = selector;
+  if (!key) die('show: missing persona name.');
+
+  const localSpec = local.byId.get(key);
+  let spec: PersonaSpec | undefined;
+  let source: PersonaSource = 'library';
+  if (localSpec) {
+    spec = localSpec;
+    source = local.sources.get(key) ?? 'cwd';
+  } else {
+    const byIntent = (personaCatalog as Record<string, PersonaSpec | undefined>)[key];
+    if (byIntent) {
+      spec = byIntent;
+    } else {
+      const byId = listBuiltInPersonas().find((p) => p.id === key);
+      if (byId) spec = byId;
+    }
+  }
+  if (!spec) {
+    const result = resolveSpec(key);
+    if ('error' in result) die(result.error, false);
+    spec = result;
+  }
+  return { spec, source };
+}
+
+function indent(text: string, prefix: string): string {
+  return text
+    .split('\n')
+    .map((line) => (line.length > 0 ? prefix + line : line))
+    .join('\n');
+}
+
+function formatPersonaShow(spec: PersonaSpec, source: PersonaSource): string {
+  const lines: string[] = [];
+  lines.push(`PERSONA      ${spec.id}`);
+  lines.push(`SOURCE       ${source}`);
+  lines.push(`INTENT       ${spec.intent}`);
+  lines.push(`TAGS         ${spec.tags && spec.tags.length ? spec.tags.join(', ') : '(none)'}`);
+  lines.push(`DESCRIPTION  ${spec.description}`);
+
+  lines.push('');
+  lines.push('SKILLS');
+  if (spec.skills.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const s of spec.skills) {
+      lines.push(`  - ${s.id}`);
+      lines.push(`      source:      ${s.source}`);
+      lines.push(`      description: ${s.description}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('INPUTS');
+  const inputs = Object.entries(spec.inputs ?? {});
+  if (inputs.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const [name, input] of inputs) {
+      lines.push(`  - ${name}`);
+      if (input.description) lines.push(`      description: ${input.description}`);
+      lines.push(`      env:         ${input.env ?? name}`);
+      lines.push(`      default:     ${input.default ?? '(required)'}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('MCP SERVERS');
+  const servers = Object.entries(spec.mcpServers ?? {});
+  if (servers.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const [name, server] of servers) {
+      lines.push(`  - ${name} (${server.type})`);
+      if (server.type === 'stdio') {
+        lines.push(`      command: ${server.command}${server.args?.length ? ' ' + server.args.join(' ') : ''}`);
+        if (server.env && Object.keys(server.env).length > 0) {
+          lines.push(`      env:     ${Object.keys(server.env).join(', ')}`);
+        }
+      } else {
+        lines.push(`      url:     ${server.url}`);
+        if (server.headers && Object.keys(server.headers).length > 0) {
+          lines.push(`      headers: ${Object.keys(server.headers).join(', ')}`);
+        }
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('PERMISSIONS');
+  const perms = spec.permissions;
+  if (!perms || (!perms.allow?.length && !perms.deny?.length && !perms.mode)) {
+    lines.push('  (none)');
+  } else {
+    if (perms.mode) lines.push(`  mode:  ${perms.mode}`);
+    if (perms.allow?.length) lines.push(`  allow: ${perms.allow.join(', ')}`);
+    if (perms.deny?.length) lines.push(`  deny:  ${perms.deny.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('MOUNT');
+  const mount = spec.mount;
+  if (!mount || (!mount.ignoredPatterns?.length && !mount.readonlyPatterns?.length)) {
+    lines.push('  (none)');
+  } else {
+    if (mount.ignoredPatterns?.length) {
+      lines.push(`  ignored:  ${mount.ignoredPatterns.join(', ')}`);
+    }
+    if (mount.readonlyPatterns?.length) {
+      lines.push(`  readonly: ${mount.readonlyPatterns.join(', ')}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('ENV');
+  const envKeys = Object.keys(spec.env ?? {});
+  if (envKeys.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const k of envKeys) lines.push(`  ${k}=${spec.env![k]}`);
+  }
+
+  lines.push('');
+  lines.push('RUNTIME');
+  lines.push(`  harness:  ${spec.harness ?? '— (handler-style persona)'}`);
+  lines.push(`  model:    ${spec.model ?? '—'}`);
+  lines.push(`  reasoning: ${spec.harnessSettings.reasoning}`);
+  lines.push(`  timeout:  ${spec.harnessSettings.timeoutSeconds}s`);
+  if (spec.harnessSettings.sandboxMode) {
+    lines.push(`  sandbox:  ${spec.harnessSettings.sandboxMode}`);
+  }
+  if (spec.harnessSettings.approvalPolicy) {
+    lines.push(`  approvals: ${spec.harnessSettings.approvalPolicy}`);
+  }
+  if (spec.harnessSettings.workspaceWriteNetworkAccess !== undefined) {
+    lines.push(`  network:  ${spec.harnessSettings.workspaceWriteNetworkAccess}`);
+  }
+  if (spec.harnessSettings.webSearch !== undefined) {
+    lines.push(`  webSearch: ${spec.harnessSettings.webSearch}`);
+  }
+  lines.push('  systemPrompt:');
+  lines.push(indent(spec.systemPrompt ?? '(none — handler-style persona)', '    '));
+
+  return lines.join('\n') + '\n';
+}
+
+function runShow(args: readonly string[]): never {
+  const { selector, json } = parseShowArgs(args);
+  const { spec, source } = resolveShowTarget(selector);
+  if (json) {
+    process.stdout.write(JSON.stringify({ source, spec }, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatPersonaShow(spec, source));
+  }
+  process.exit(0);
+}
+
+function runHarnessCheck(): never {
+  const results = detectHarnesses();
+  process.stdout.write(formatAvailabilityTable(results));
+  const available = results.filter((r) => r.available).length;
+  process.stdout.write(`\n${available}/${results.length} harness(es) available.\n`);
+  process.exit(0);
+}
+
+interface CreateTarget {
+  raw: string;
+  kind: string;
+  dir: string;
+  createMode: 'local' | 'built-in';
+}
+
+function defaultCreateTargetSelector(): string {
+  return loadPersonaSourceConfig().defaultCreateTarget ?? 'cwd';
+}
+
+function resolveCreateTarget(rawTarget: string | undefined): CreateTarget {
+  const raw = rawTarget?.trim() || defaultCreateTargetSelector();
+  const config = loadPersonaSourceConfig();
+
+  if (raw === 'cwd') {
+    return {
+      raw,
+      kind: 'cwd',
+      dir: defaultCwdPersonaDir(process.cwd()),
+      createMode: 'local'
+    };
+  }
+  if (raw === 'user') {
+    return {
+      raw,
+      kind: 'user',
+      dir: config.userPersonaDir,
+      createMode: 'local'
+    };
+  }
+  if (raw === 'library') {
+    const dir = resolvePath(process.cwd(), 'personas');
+    if (!existsSync(dir)) {
+      die(
+        'create: --save-in-directory=library requires running from the AgentWorkforce repo root, where ./personas exists.'
+      );
+    }
+    return {
+      raw,
+      kind: 'library',
+      dir,
+      createMode: 'built-in'
+    };
+  }
+  const dirMatch = /^dir:([1-9]\d*)$/.exec(raw);
+  if (dirMatch) {
+    const idx = Number(dirMatch[1]) - 1;
+    const dir = config.personaDirs[idx];
+    if (!dir) {
+      die(`create: ${raw} does not exist. Run "agentworkforce sources list" to see configured dirs.`);
+    }
+    return {
+      raw,
+      kind: raw,
+      dir,
+      createMode: 'local'
+    };
+  }
+
+  return {
+    raw: normalizePersonaDir(raw),
+    kind: 'path',
+    dir: normalizePersonaDir(raw),
+    createMode: 'local'
+  };
+}
+
+function buildCreateInputValues(target: CreateTarget): Record<string, string> {
+  return {
+    [CREATE_INPUT_TARGET_DIR]: target.dir,
+    [CREATE_INPUT_CREATE_MODE]: target.createMode
+  };
+}
+
+function ensureCreateTargetDir(target: CreateTarget): void {
+  if (target.createMode === 'built-in') return;
+  mkdirSync(target.dir, { recursive: true });
+}
+
+function saveDefaultCreateTarget(target: CreateTarget): void {
+  const config = loadPersonaSourceConfig();
+  const raw = target.kind === 'path' ? target.dir : target.raw;
+  const saved = savePersonaSourceConfig(config.personaDirs, { defaultCreateTarget: raw });
+  process.stderr.write(`• default create target saved: ${raw}\n`);
+  process.stderr.write(`• config: ${saved.configPath}\n`);
+}
+
+async function runAgentSelector(
+  selector: string,
+  flags: AgentFlags,
+  inputValues?: Record<string, string>
+): Promise<never> {
+  perfMark('runAgentSelector: start');
+  const target = parseSelector(selector);
+  perfMark('runAgentSelector: persona resolved');
+  const selection = {
+    ...buildSelection(target.spec, target.kind),
+    ...(inputValues ? { inputValues } : {})
+  };
+
+  if (flags.dryRun) {
+    const code = runDryRun(selection);
+    process.exit(code);
+  }
+
+  // Record only on real launches so `--dry-run` validations don't pollute the
+  // MRU list used by the bare-invocation picker.
+  recordRecent(target.spec.id);
+  const capture: RunInteractiveCapture = {};
+  const code = await runInteractive(selection, {
+    installInRepo: flags.installInRepo,
+    noLaunchMetadata: flags.noLaunchMetadata,
+    noSkillCache: flags.noSkillCache,
+    refreshSkills: flags.refreshSkills,
+    checkUpstream: flags.checkUpstream,
+    noCheckUpstream: flags.noCheckUpstream,
+    personaSpec: target.spec,
+    personaSource: target.source,
+    capture,
+    // Only unflagged launches feed the warm fast path: flags change launch
+    // semantics in ways the cached plan doesn't encode.
+    ...(inputValues === undefined &&
+    !flags.installInRepo &&
+    !flags.noLaunchMetadata &&
+    !flags.noSkillCache &&
+    !flags.refreshSkills &&
+    !flags.checkUpstream &&
+    !flags.noCheckUpstream &&
+    !flags.dryRun
+      ? { selector }
+      : {})
+  });
+  // 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);
+}
+
+/**
+ * Manage a session the fast path already spawned (see fast-launch.ts): the
+ * harness child is running inside a claimed warm mount, and this function —
+ * loaded while the harness TUI is still booting — owns everything else:
+ * reattach the mount with the previous session's autosync state, reconcile
+ * to catch up with repo changes made while the mount sat warm, start launch
+ * metadata, and on child exit run the same drain/sync-back/re-warm flow as
+ * a full launch.
+ *
+ * Also re-derives the harness spec from live persona resolution and compares
+ * it against the plan's argv. The plan's digests should make a mismatch
+ * impossible; if one slips through, the session keeps running (killing it
+ * would eat the user's terminal for a stale-plan technicality) but the plan
+ * is deleted and the mismatch reported so the next launch re-resolves.
+ */
+export async function resumeFastSession(fast: FastLaunch): Promise<never> {
+  perfMark('resume: cli-impl loaded (child already running)');
+  const { plan, child, sessionRoot, mountDir, statePath } = fast;
+  recordRecent(plan.personaId);
+  process.stderr.write(
+    `→ ${plan.personaId} via ${plan.harness} (${plan.model}) [warm launch]\n`
+  );
+
+  // Child-running / syncing SIGINT semantics, mirroring runInteractive
+  // (there is no pre-launch phase here — the child is already up).
+  const shutdownController = new AbortController();
+  let syncSpinner: Ora | undefined;
+  let isSyncing = false;
+  let abortPresses = 0;
+  const sigintHandler = () => {
+    if (!isSyncing) return;
+    abortPresses += 1;
+    if (abortPresses === 1) {
+      if (syncSpinner) {
+        syncSpinner.text =
+          'Aborting sync — partial changes will be propagated. (Ctrl-C again to force quit)';
+      }
+      shutdownController.abort();
+      return;
+    }
+    if (syncSpinner) {
+      syncSpinner.fail('Force-quit: mount teardown skipped. Session dir may be left behind.');
+      syncSpinner = undefined;
+    }
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  const exitCodePromise = new Promise<number>((resolve) => {
+    child.on('error', () => resolve(127));
+    child.on('close', (code, signal) => {
+      if (typeof code === 'number') resolve(code);
+      else if (signal) resolve(signalExitCode(signal));
+      else resolve(1);
+    });
+  });
+
+  // Live resolution replay: rebuild the selection and spec, verify the plan
+  // argv, and capture fresh digests for the re-warm at exit.
+  let target: ResolvedTarget | undefined;
+  let nextPlan: LaunchPlan | null = null;
+  let launchMetadata: LaunchMetadataRun | undefined;
+  const capture: RunInteractiveCapture = {
+    sessionCwd: mountDir,
+    harness: plan.harness as Harness,
+    startedAt: fast.startedAt
+  };
+  try {
+    target = parseSelector(plan.selector);
+    const selection = buildSelection(target.spec, target.kind);
+    const { effectiveSelection, inputResolution } = renderEffectiveSelection(selection);
+    const { personaId, harness, model, harnessSettings, systemPrompt } = effectiveSelection;
+    const skillCacheFingerprint = computeSkillCacheFingerprint({
+      harness,
+      skills: effectiveSelection.skills,
+      repoRoot: plan.cwd
+    });
+    const installRoot =
+      harness === 'claude' ? resolveSkillCacheDir(skillCacheFingerprint) : undefined;
+    const spec = buildInteractiveSpec({
+      harness,
+      personaId,
+      model,
+      systemPrompt,
+      harnessSettings,
+      mcpServers: undefined,
+      permissions: effectiveSelection.permissions,
+      ...(installRoot !== undefined ? { pluginDirs: [installRoot] } : {})
+    });
+    const finalArgs = spec.initialPrompt ? [...spec.args, spec.initialPrompt] : [...spec.args];
+    const argvMatches =
+      finalArgs.length === plan.spawn.args.length &&
+      finalArgs.every((arg, i) => arg === plan.spawn.args[i]) &&
+      skillCacheFingerprint === plan.skillCache.fingerprint;
+    if (!argvMatches) {
+      deleteLaunchPlan(plan.cwd, plan.selector);
+      process.stderr.write(
+        'warning: cached launch plan no longer matches live persona resolution; ' +
+          'this session runs with the cached spec, the next launch re-resolves.\n'
+      );
+    } else {
+      nextPlan = buildFastLaunchPlan({
+        selector: plan.selector,
+        personaId,
+        harness,
+        model,
+        selection,
+        effectiveSelection,
+        relayMcp: resolveRelayMcpFromEnv(process.env),
+        envResolutionValue: undefined,
+        inputEnv: inputResolution.values,
+        resolvedMcp: undefined,
+        aiHist: undefined,
+        skillCacheDir: resolveSkillCacheDir(skillCacheFingerprint),
+        skillCacheFingerprint,
+        bin: spec.bin,
+        finalArgs,
+        ignoredPatterns: plan.mount.ignoredPatterns,
+        readonlyPatterns: plan.mount.readonlyPatterns
+      });
+    }
+    launchMetadata = await startLaunchMetadataRecording({
+      selection: effectiveSelection,
+      personaSpec: target.spec,
+      personaSource: target.source,
+      cwd: mountDir,
+      noLaunchMetadata: false,
+      env: process.env,
+      onWarn: (msg) => launchMetadataLog.warn(msg)
+    });
+    capture.stampEnrichment = { ...launchMetadata.metadata };
+    capture.stampingEnabled = launchMetadata.enabled;
+  } catch (err) {
+    process.stderr.write(
+      `warning: post-spawn resolution failed (${(err as Error).message}); ` +
+        'session continues, next launch takes the full path.\n'
+    );
+    deleteLaunchPlan(plan.cwd, plan.selector);
+  }
+
+  // Reattach the warm mount and catch up with anything that changed in the
+  // repo while it sat idle. The harness is booting its TUI concurrently;
+  // autosync's watchers take over from here exactly as in a full launch.
+  let handle: MountHandle | undefined;
+  let autoSync: AutoSyncHandle | undefined;
+  try {
+    const initialState = JSON.parse(readFileSync(statePath, 'utf8')) as Record<
+      string,
+      FileState
+    >;
+    handle = await attachMount(plan.cwd, mountDir, {
+      ignoredPatterns: [...plan.mount.ignoredPatterns],
+      readonlyPatterns: [...plan.mount.readonlyPatterns],
+      excludeDirs: [],
+      agentName: plan.personaId,
+      includeGit: true,
+      population: 'auto',
+      initialState
+    });
+    autoSync = handle.startAutoSync();
+    await autoSync.reconcile();
+    perfMark('resume: mount reattached + reconciled');
+  } catch (err) {
+    process.stderr.write(
+      `warning: could not reattach warm mount (${(err as Error).message}). ` +
+        `Session changes will NOT sync back automatically; they remain in ${mountDir}.\n`
+    );
+    deleteLaunchPlan(plan.cwd, plan.selector);
+    nextPlan = null;
+  }
+
+  const exitCode = await exitCodePromise;
+  perfMark('exit: harness child exited');
+
+  isSyncing = true;
+  syncSpinner = ora({
+    text: 'Syncing session changes back to the repo… (Ctrl-C to skip)',
+    stream: process.stderr
+  }).start();
+  let count = 0;
+  let exportedState: Record<string, FileState> | undefined;
+  try {
+    if (autoSync) {
+      if (nextPlan && !shutdownController.signal.aborted) {
+        try {
+          await autoSync.reconcile({ signal: shutdownController.signal });
+        } catch {
+          /* fall through to the normal drain */
+        }
+      }
+      await autoSync.stop({ signal: shutdownController.signal });
+      count += autoSync.totalChanges();
+      if (nextPlan && !shutdownController.signal.aborted) {
+        try {
+          exportedState = autoSync.exportState();
+        } catch {
+          /* re-warm skipped below */
+        }
+      }
+      autoSync = undefined;
+    }
+    if (handle) {
+      count += await handle.syncBack({ signal: shutdownController.signal });
+    }
+    const aborted = shutdownController.signal.aborted;
+    if (handle && nextPlan && exportedState && !aborted) {
+      rewarmMountAndPlan({ plan: nextPlan, mountDir: handle.mountDir, exportedState });
+    }
+    const qualifier = aborted ? ' (partial)' : '';
+    syncSpinner.succeed(
+      count > 0
+        ? `Session complete — ${count} file event${count === 1 ? '' : 's'} during session${qualifier}.`
+        : 'Session complete — no file events.'
+    );
+    syncSpinner = undefined;
+  } catch (err) {
+    if (syncSpinner) {
+      syncSpinner.fail(`Sync did not complete: ${(err as Error).message}`);
+      syncSpinner = undefined;
+    }
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+    if (handle) {
+      handle.cleanup();
+      removeSessionRoot(sessionRoot);
+    }
+    await launchMetadata?.stop();
+  }
+
+  if (target) {
+    await maybeOfferLearningsImprover({
+      target,
+      capture,
+      flags: {
+        installInRepo: false,
+        noLaunchMetadata: false,
+        dryRun: false,
+        noSkillCache: false,
+        refreshSkills: false,
+        checkUpstream: false,
+        noCheckUpstream: false
+      }
+    });
+  }
+  process.exit(exitCode);
+}
+
+interface LocalPersonaImproverContext {
+  target: ResolvedTarget;
+  capture: RunInteractiveCapture;
+  flags: AgentFlags;
+}
+
+/**
+ * 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: LocalPersonaImproverContext): Promise<void> {
+  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 as Error).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: ImproverProposalsFile | undefined;
+  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 as Error).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 as Error).message}\n`
+    );
+  }
+}
+
+export interface ImproverPatch {
+  path: string;
+  op: 'set' | 'append';
+  value: unknown;
+}
+
+/**
+ * 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: readonly string[] = [
+  'description',
+  'agentsMdContent',
+  'claudeMdContent',
+  'tags',
+  '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: readonly string[] = ['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: string, context: string): readonly string[] {
+  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: ImproverPatch, context: string): void {
+  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 as { op: string }).op}"`);
+}
+
+export interface ImproverProposal {
+  id: string;
+  summary: string;
+  rationale: string;
+  patches: ImproverPatch[];
+}
+
+export interface ImproverProposalsFile {
+  personaId: string;
+  personaFilePath: string;
+  transcriptPath: string;
+  proposals: ImproverProposal[];
+}
+
+/**
+ * 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: {
+  harness?: Harness;
+  sessionCwd?: string;
+  enrichment: Record<string, string>;
+  startedAt?: number;
+}): Promise<string | undefined> {
+  if (!input.harness || !input.sessionCwd) return undefined;
+  const persona = input.enrichment.persona;
+  const personaVersion = input.enrichment.personaVersion;
+  if (!persona || !personaVersion) return undefined;
+  let sdk: typeof import('@relayburn/sdk');
+  try {
+    sdk = await import('@relayburn/sdk');
+  } catch {
+    return undefined;
+  }
+  if (typeof sdk.exportStamps !== 'function') return undefined;
+  let rows: unknown[];
+  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: string | undefined;
+  // 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 as {
+      ts?: unknown;
+      selector?: { sessionId?: unknown };
+      enrichment?: Record<string, unknown>;
+    };
+    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: Harness,
+  sessionCwd: string,
+  sessionId: string
+): string | undefined {
+  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: string,
+  needle: string,
+  extensions: readonly string[]
+): string | undefined {
+  const wantsExt = (name: string) => extensions.some((ext) => name.endsWith(ext));
+  const visit = (cur: string, depth: number): string | undefined => {
+    let entries: Dirent[];
+    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: {
+  harness?: Harness;
+  sessionCwd?: string;
+  startedAt?: number;
+}): string | undefined {
+  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;
+}
+
+interface FindMatchingOptions {
+  dir: string;
+  /** Whether to walk subdirectories (codex date-grouped, opencode project-hash-grouped). */
+  recursive: boolean;
+  extensions: readonly string[];
+  sinceMs: number;
+  sessionCwd: string;
+  /**
+   * Extract the embedded cwd from the candidate file. Returns undefined
+   * when the file has no parseable cwd (skip rather than match).
+   */
+  readCwd: (path: string) => string | 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: FindMatchingOptions): string | undefined {
+  const wantsExt = (name: string) => opts.extensions.some((ext) => name.endsWith(ext));
+  let bestPath: string | undefined;
+  let bestMtime = -1;
+  const visit = (cur: string, depth: number) => {
+    let entries: Dirent[];
+    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 ~64KB from `path` (enough for a JSONL header line plus
+ * margin) and return it as a string. Used by the per-harness cwd
+ * extractors so we don't slurp multi-megabyte transcripts to find a
+ * field on line 1.
+ */
+interface TranscriptHeader {
+  text: string;
+  /** True if the file was longer than `maxBytes` and we only read the prefix. */
+  truncated: boolean;
+}
+
+/**
+ * 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: string,
+  maxBytes = 65536
+): TranscriptHeader | undefined {
+  let fd: number | undefined;
+  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: string): string | undefined {
+  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) as { cwd?: unknown };
+      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: string): string | undefined {
+  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) as { payload?: { cwd?: unknown } };
+    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: string): string | undefined {
+  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) as { directory?: unknown };
+    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: {
+  personaFilePath: string;
+  transcriptPath: string;
+  proposalsOutputPath: string;
+}): Promise<ImproverProposalsFile> {
+  const improverSpec = personaCatalog['persona-improvement' as const];
+  if (!improverSpec) {
+    throw new Error('built-in persona "persona-improver" is not registered in the catalog');
+  }
+  const selection = buildSelection(improverSpec, 'repo');
+  const inputValues: Record<string, string> = {
+    PERSONA_FILE_PATH: args.personaFilePath,
+    SESSION_TRANSCRIPT_PATH: args.transcriptPath,
+    PROPOSALS_OUTPUT_PATH: args.proposalsOutputPath
+  };
+  const inputResolution = resolvePersonaInputs(
+    selection.inputs,
+    inputValues,
+    process.env
+  );
+  const renderedSystemPrompt = renderPersonaInputs(
+    selection.systemPrompt,
+    inputResolution.values
+  );
+  const callerEnv = { ...process.env, ...inputResolution.values };
+  const envResolution = resolveStringMapLenient(selection.env, callerEnv, 'env');
+  const mcpResolution = resolveMcpServersLenient(selection.mcpServers, callerEnv);
+  const taskBody = [
+    '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}`
+  ].join('\n');
+  const task = `${taskBody}\n\nRun inputs:\n${JSON.stringify(inputValues, null, 2)}`;
+  const spec = buildNonInteractiveSpec({
+    harness: selection.harness,
+    personaId: selection.personaId,
+    model: selection.model,
+    systemPrompt: renderedSystemPrompt,
+    harnessSettings: selection.harnessSettings,
+    mcpServers: mcpResolution.servers,
+    permissions: selection.permissions,
+    task
+  });
+  const childEnv = { ...callerEnv, ...(envResolution.value ?? {}), ...inputResolution.values };
+  const cwd = process.cwd();
+  const configWrites: { path: string; existed: boolean; previous?: string }[] = [];
+  for (const file of spec.configFiles) {
+    assertSafeRelativePath(file.path);
+    const target = join(cwd, file.path);
+    const existed = existsSync(target);
+    const previous = existed ? readFileSync(target, 'utf8') : undefined;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.contents, 'utf8');
+    configWrites.push({ path: target, existed, ...(previous !== undefined ? { previous } : {}) });
+  }
+  const restoreConfigWrites = () => {
+    for (const write of [...configWrites].reverse()) {
+      if (write.existed) {
+        writeFileSync(write.path, write.previous ?? '', 'utf8');
+      } else {
+        rmSync(write.path, { force: true });
+      }
+    }
+  };
+  const timeoutMs = selection.harnessSettings.timeoutSeconds
+    ? selection.harnessSettings.timeoutSeconds * 1000
+    : undefined;
+  let captureResult: { exitCode: number | null; stderr: string };
+  try {
+    captureResult = await new Promise<{ exitCode: number | null; stderr: string }>(
+      (resolveResult) => {
+        const child = spawn(spec.bin, [...spec.args], {
+          cwd,
+          env: childEnv,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          shell: false
+        });
+        let stderrBuf = '';
+        let forceKillTimeout: NodeJS.Timeout | undefined;
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk: string) => {
+          stderrBuf += chunk;
+        });
+        // SIGTERM first; if the harness traps or ignores it, escalate to
+        // SIGKILL after a 1s grace so the timeout is actually enforced.
+        const timeout =
+          timeoutMs !== undefined
+            ? setTimeout(() => {
+                child.kill('SIGTERM');
+                forceKillTimeout = setTimeout(() => {
+                  if (!child.killed) child.kill('SIGKILL');
+                }, 1000);
+              }, timeoutMs)
+            : undefined;
+        const clearTimers = () => {
+          if (timeout) clearTimeout(timeout);
+          if (forceKillTimeout) clearTimeout(forceKillTimeout);
+        };
+        child.on('error', (err) => {
+          clearTimers();
+          resolveResult({ exitCode: 1, stderr: `${stderrBuf}${err.message}\n` });
+        });
+        child.on('close', (code, signal) => {
+          clearTimers();
+          const exitCode =
+            typeof code === 'number' ? code : signal ? signalExitCode(signal) : null;
+          resolveResult({ exitCode, stderr: stderrBuf });
+        });
+      }
+    );
+  } finally {
+    // Always restore — a synchronous spawn() throw or unexpected promise
+    // rejection must not leave orphaned `opencode.json` (or any other
+    // configFile) sitting in the user's working directory.
+    restoreConfigWrites();
+  }
+  if (captureResult.exitCode !== 0) {
+    throw new Error(
+      `improver exited with code=${captureResult.exitCode ?? 'null'}.${captureResult.stderr ? ` stderr: ${captureResult.stderr.slice(0, 400)}` : ''}`
+    );
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(args.proposalsOutputPath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `improver did not write proposals file at ${args.proposalsOutputPath}: ${(err as Error).message}`
+    );
+  }
+  return parseProposals(raw);
+}
+
+export function parseProposals(raw: string): ImproverProposalsFile {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`proposals file is not valid JSON: ${(err as Error).message}`);
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('proposals file must be a JSON object');
+  }
+  const obj = parsed as Record<string, unknown>;
+  const proposalsArr = Array.isArray(obj.proposals) ? obj.proposals : [];
+  const proposals: ImproverProposal[] = [];
+  for (const [idx, item] of proposalsArr.entries()) {
+    if (!item || typeof item !== 'object') {
+      throw new Error(`proposals[${idx}] must be an object`);
+    }
+    const p = item as Record<string, unknown>;
+    const id = normalizeNonEmptyString(p.id) ?? `proposal-${idx + 1}`;
+    const rationale = typeof p.rationale === 'string' ? p.rationale.trim() : '';
+    if (!Array.isArray(p.patches) || p.patches.length === 0) {
+      throw new Error(`proposals[${idx}].patches must be a non-empty array`);
+    }
+    const patches: ImproverPatch[] = [];
+    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 as Record<string, unknown>;
+      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: ImproverPatch = { path: rp.path, op: rp.op, value: rp.value };
+      assertAllowedImproverPatch(patch, `proposals[${idx}].patches[${pidx}]`);
+      patches.push(patch);
+    }
+    const summary = normalizeProposalSummary(p.summary, id, patches);
+    proposals.push({
+      id,
+      summary,
+      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
+  };
+}
+
+function normalizeNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeProposalSummary(
+  value: unknown,
+  id: string,
+  patches: readonly ImproverPatch[]
+): string {
+  const explicit = normalizeNonEmptyString(value);
+  if (explicit) return explicit;
+  const fromId = humanizeProposalId(id);
+  if (fromId) return fromId;
+  return summarizeProposalPatches(patches);
+}
+
+function humanizeProposalId(id: string): string | undefined {
+  const trimmed = id.trim();
+  if (!trimmed || /^p\d+$/i.test(trimmed) || /^proposal-\d+$/i.test(trimmed)) {
+    return undefined;
+  }
+  const words = trimmed.replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!words) return undefined;
+  return `${words.slice(0, 1).toUpperCase()}${words.slice(1)}`;
+}
+
+function summarizeProposalPatches(patches: readonly ImproverPatch[]): string {
+  if (patches.length === 1) return summarizeSingleProposalPatch(patches[0]);
+  return `Apply ${patches.length} persona updates`;
+}
+
+function summarizeSingleProposalPatch(patch: ImproverPatch): string {
+  if (patch.op === 'append' && patch.path === 'skills') return 'Add skill';
+  if (patch.path.startsWith('inputs.')) {
+    return `Add ${patch.path.slice('inputs.'.length)} input`;
+  }
+  if (patch.path === 'description') return 'Update description';
+  if (patch.path === 'agentsMdContent') return 'Update AGENTS.md guidance';
+  if (patch.path === 'claudeMdContent') return 'Update CLAUDE.md guidance';
+  if (patch.path === 'tags') return 'Update tags';
+  if (patch.path === 'systemPrompt') return 'Update system prompt';
+  return patch.op === 'append' ? `Append to ${patch.path}` : `Update ${patch.path}`;
+}
+
+/**
+ * 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: ImproverProposalsFile): ImproverProposal[] {
+  if (!process.stdin.isTTY) return [];
+  const accepted: ImproverProposal[] = [];
+  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: ImproverPatch): string {
+  const op = patch.op === 'append' ? '+= ' : '= ';
+  const valueStr = formatPatchValue(patch.value);
+  return `${patch.path} ${op}${valueStr}`;
+}
+
+function formatPatchValue(value: unknown): string {
+  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: string,
+  valid: readonly string[],
+  opts: {
+    write?: (chunk: string) => void;
+    read?: () => string | undefined;
+  } = {}
+): string {
+  const write = opts.write ?? ((chunk: string) => {
+    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: string,
+  accepted: readonly ImproverProposal[]
+): void {
+  const raw = readFileSync(personaFilePath, 'utf8');
+  const json = JSON.parse(raw) as Record<string, unknown>;
+  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: Record<string, unknown>, patch: ImproverPatch): void {
+  // 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: Record<string, unknown> = 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: Record<string, unknown> = {};
+      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 as Record<string, unknown>;
+  }
+  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 personas for the interactive TUI. Source label mirrors the cascade
+ * shown by `agentworkforce list` so the picker tells the user *where* a
+ * persona is coming from (cwd, user, dir:n, library) without a separate
+ * lookup.
+ */
+export function buildTuiCandidates(): TuiCandidate[] {
+  const byId = new Map<string, TuiCandidate>();
+  for (const spec of listBuiltInPersonas()) {
+    byId.set(spec.id, {
+      id: spec.id,
+      description: spec.description,
+      source: formatPersonaSourceLabel('library')
+    });
+  }
+  for (const [id, spec] of local.byId.entries()) {
+    byId.set(id, {
+      id,
+      description: spec.description,
+      source: formatPersonaSourceLabel(local.sources.get(id) ?? 'library')
+    });
+  }
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Bare-invocation flow: open the interactive TUI, then hand the chosen
+ * persona to {@link runAgentSelector}. Quitting the picker (Esc / Ctrl-C)
+ * exits with conventional 130 so shell pipelines see SIGINT-style failure.
+ *
+ * runAgentSelector terminates the process via process.exit; this function
+ * only returns when the picker is dismissed without a selection.
+ */
+async function runInteractivePicker(): Promise<never> {
+  const candidates = buildTuiCandidates();
+  if (candidates.length === 0) {
+    process.stderr.write(
+      'No personas available. Try `agentworkforce install <pack>` or run with --help.\n'
+    );
+    process.exit(1);
+  }
+  const selected = await runPersonaPickerTui({
+    candidates,
+    recentIds: loadRecents()
+  });
+  if (!selected) {
+    process.exit(130);
+  }
+  await runAgentSelector(selected, {
+    installInRepo: false,
+    noLaunchMetadata: false,
+    dryRun: false,
+    noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
+    refreshSkills: false,
+    checkUpstream: false,
+    noCheckUpstream: false
+  });
+  // runAgentSelector has Promise<never> return type; this is unreachable.
+  process.exit(0);
+}
+
+/**
+ * Enumerate persona candidates for the picker. Local overrides win over the
+ * built-in catalog when ids collide; the picker only needs the projection
+ * fields ({@link PickCandidate}), not full specs.
+ */
+export function buildPickCandidates(): PickCandidate[] {
+  const byId = new Map<string, PickCandidate>();
+  for (const spec of listBuiltInPersonas()) {
+    byId.set(spec.id, {
+      id: spec.id,
+      intent: spec.intent,
+      tags: spec.tags ? [...spec.tags] : [],
+      description: spec.description
+    });
+  }
+  for (const [id, spec] of local.byId.entries()) {
+    byId.set(id, {
+      id,
+      intent: spec.intent,
+      tags: spec.tags ? [...spec.tags] : [],
+      description: spec.description
+    });
+  }
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Synchronous y/n prompt over /dev/tty-equivalent stdin. Default is "no" on
+ * empty input or non-y answer. Used by `pick` when the picker reports
+ * no-match in an interactive session.
+ *
+ * Test seam: callers can inject `read` so the prompt path is exercisable
+ * without a real TTY.
+ */
+export function promptYesNoSync(
+  question: string,
+  opts: {
+    isTTY?: boolean;
+    write?: (chunk: string) => void;
+    read?: () => string | undefined;
+  } = {}
+): boolean {
+  const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
+  if (!isTTY) return false;
+  const write = opts.write ?? ((chunk: string) => {
+    process.stderr.write(chunk);
+  });
+  write(question);
+  const answer = opts.read ? opts.read() : readLineFromStdinSync();
+  if (!answer) return false;
+  const normalized = answer.trim().toLowerCase();
+  return normalized === 'y' || normalized === 'yes';
+}
+
+function readLineFromStdinSync(): string | undefined {
+  const buf = Buffer.alloc(256);
+  let line = '';
+  for (;;) {
+    let n: number;
+    try {
+      n = readSync(0, buf, 0, buf.length, null);
+    } catch {
+      return line || undefined;
+    }
+    if (n <= 0) return line || undefined;
+    const chunk = buf.subarray(0, n).toString('utf8');
+    const newlineIdx = chunk.indexOf('\n');
+    if (newlineIdx === -1) {
+      line += chunk;
+      continue;
+    }
+    line += chunk.slice(0, newlineIdx);
+    return line;
+  }
+}
+
+async function runPick(args: readonly string[]): Promise<never> {
+  const positional: string[] = [];
+  for (const arg of args) {
+    if (arg === '-h' || arg === '--help') {
+      process.stdout.write(
+        'Usage: agentworkforce pick "<task description>"\n' +
+          '  Prints the best-fit persona id to stdout. On low confidence, prompts to\n' +
+          '  open persona-maker (TTY) or exits 2 (non-TTY). Exits 3 if `claude` is\n' +
+          '  not installed.\n'
+      );
+      process.exit(0);
+    }
+    positional.push(arg);
+  }
+  if (positional.length === 0) {
+    die('pick: missing task description. Usage: agentworkforce pick "<task>"');
+  }
+  if (positional.length > 1) {
+    die(
+      `pick: expected a single quoted task description, got ${positional.length} arguments. ` +
+        `Did you forget to quote the task? Try: agentworkforce pick "${positional.join(' ')}"`
+    );
+  }
+  const task = positional[0].trim();
+  if (!task) {
+    die('pick: task description is empty.');
+  }
+
+  const candidates = buildPickCandidates();
+  const result: PickResult = pickPersona(task, candidates);
+
+  if (result.kind === 'match') {
+    process.stderr.write(
+      `• picked ${result.personaId} (${result.confidence}): ${result.reason}\n`
+    );
+    process.stdout.write(`${result.personaId}\n`);
+    process.exit(0);
+  }
+
+  if (result.kind === 'picker-unavailable') {
+    process.stderr.write(`pick: ${result.message}\n`);
+    process.exit(3);
+  }
+
+  // no-match
+  process.stderr.write(`pick: no close persona match — ${result.reason}\n`);
+  const wantsCreate = promptYesNoSync(
+    'Open persona-maker to scaffold a new persona for this task? [y/N] '
+  );
+  if (!wantsCreate) {
+    process.stderr.write(
+      'Try: agentworkforce list   # to browse existing personas\n' +
+        '     agentworkforce create  # to author a new persona\n'
+    );
+    process.exit(2);
+  }
+
+  const target = resolveCreateTarget(undefined);
+  ensureCreateTargetDir(target);
+  const inputValues = {
+    ...buildCreateInputValues(target),
+    TASK_DESCRIPTION: task
+  };
+  await runAgentSelector(
+    CREATE_SELECTOR,
+    {
+      installInRepo: false,
+      noLaunchMetadata: false,
+      dryRun: false,
+      noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
+      refreshSkills: false,
+      checkUpstream: false,
+      noCheckUpstream: false
+    },
+    inputValues
+  );
+  // runAgentSelector terminates via process.exit; this satisfies TS's
+  // reachable-end-point check for the `Promise<never>` return type.
+  process.exit(0);
+}
+
+export async function main(): Promise<void> {
+  perfMark('main() entered (module graph loaded)');
+  const argv = process.argv.slice(2);
+  const [subcommand, ...rest] = argv;
+
+  if (subcommand === '-h' || subcommand === '--help') {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+
+  if (!subcommand) {
+    if (process.stdin.isTTY && process.stderr.isTTY) {
+      await runInteractivePicker();
+      // runInteractivePicker either runAgentSelector → process.exit, or
+      // exits itself on quit / no-match. Satisfy TS's unreachable check.
+      process.exit(0);
+    }
+    process.stdout.write(USAGE);
+    process.exit(1);
+  }
+
+  if (subcommand === '-v' || subcommand === '--version') {
+    process.stdout.write(`${CLI_VERSION}\n`);
+    process.exit(0);
+  }
+
+  if (subcommand === 'list') {
+    await runList(rest);
+    return;
+  }
+
+  if (subcommand === 'show') {
+    runShow(rest);
+  }
+
+  if (subcommand === 'persona') {
+    try {
+      await runPersonaCompileCommand(rest);
+      return;
+    } catch (err) {
+      die((err as Error)?.message ?? String(err), false);
+    }
+  }
+
+  if (subcommand === 'install') {
+    runPersonaInstall(rest);
+  }
+
+  if (subcommand === 'sources') {
+    runSources(rest);
+  }
+
+  if (subcommand === 'harness') {
+    const [action, ...extra] = rest;
+    if (!action || action === '-h' || action === '--help') {
+      die('harness: missing action. Expected: check');
+    }
+    if (action !== 'check') {
+      die(`harness: unknown action "${action}". Expected: check`);
+    }
+    if (extra.length > 0) {
+      die(`harness check: unexpected argument "${extra[0]}".`);
+    }
+    runHarnessCheck();
+  }
+
+  if (subcommand === 'create') {
+    const { flags, selector, inputValues } = parseCreateArgs(rest);
+    await runAgentSelector(selector, flags, inputValues);
+  }
+
+  if (subcommand === 'pick') {
+    await runPick(rest);
+  }
+
+  if (subcommand === 'deploy') {
+    const { runDeploy } = await import('./deploy-command.js');
+    await runDeploy(rest);
+    return;
+  }
+
+  if (subcommand === 'invoke') {
+    const { runInvoke } = await import('./invoke-command.js');
+    await runInvoke(rest);
+    return;
+  }
+
+  if (subcommand === 'runs') {
+    const { runRuns } = await import('./runs-command.js');
+    await runRuns(rest);
+    return;
+  }
+
+  if (subcommand === 'integrations') {
+    const { runIntegrationsCommand } = await import('./integrations-command.js');
+    await runIntegrationsCommand(rest);
+    return;
+  }
+
+  if (subcommand === 'trigger') {
+    await runTrigger(rest);
+    return;
+  }
+
+  if (subcommand === 'deployments') {
+    const [action, ...extra] = rest;
+    if (!action || action === '-h' || action === '--help') {
+      process.stdout.write('Usage: agentworkforce deployments <list|logs|trigger> [flags]\n');
+      process.exit(action ? 0 : 1);
+    }
+    if (action === 'list') {
+      const { runDeploymentList } = await import('./list-command.js');
+      await runDeploymentList(extra);
+      return;
+    }
+    if (action === 'logs') {
+      const { runDeploymentLogs } = await import('./list-command.js');
+      await runDeploymentLogs(extra);
+      return;
+    }
+    if (action === 'trigger') {
+      await runTrigger(extra);
+      return;
+    }
+    die(`deployments: unknown action "${action}". Expected: list, logs, trigger`);
+  }
+
+  if (subcommand === 'destroy') {
+    const { runDestroy } = await import('./destroy-command.js');
+    await runDestroy(rest);
+    return;
+  }
+
+  if (subcommand === 'login') {
+    const { runLogin } = await import('./deploy-command.js');
+    await runLogin(rest);
+    return;
+  }
+
+  if (subcommand === 'logout') {
+    const { runLogout } = await import('./deploy-command.js');
+    await runLogout(rest);
+    return;
+  }
+
+  if (subcommand !== 'agent') {
+    die(`Unknown subcommand "${subcommand}".`);
+  }
+
+  const { flags, positional } = parseAgentArgs(rest);
+  const [selector, ...extra] = positional;
+  if (!selector) die('agent: missing persona selector.');
+  if (extra.length > 0) {
+    die(`agent: unexpected argument "${extra[0]}". The agent subcommand only takes a persona selector.`);
+  }
+
+  await runAgentSelector(selector, flags);
+}
+
+export interface AgentFlags {
+  installInRepo: boolean;
+  noLaunchMetadata: boolean;
+  dryRun: boolean;
+  /** Bypass the persistent skill-install cache for this launch. */
+  noSkillCache: boolean;
+  /** Force a fresh install even if the cache entry exists (rebuilds it in place). */
+  refreshSkills: boolean;
+  /** Force an upstream drift check this launch regardless of the TTL. */
+  checkUpstream: boolean;
+  /** Skip the upstream drift check this launch regardless of the TTL. */
+  noCheckUpstream: boolean;
+}
+
+export interface CreateFlags extends AgentFlags {
+  saveInDirectory?: string;
+  saveDefault: boolean;
+}
+
+export function parseAgentArgs(args: readonly string[]): {
+  flags: AgentFlags;
+  positional: string[];
+} {
+  const flags: AgentFlags = {
+    installInRepo: false,
+    noLaunchMetadata: false,
+    dryRun: false,
+    noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
+    refreshSkills: false,
+    checkUpstream: false,
+    noCheckUpstream: false
+  };
+  const positional: string[] = [];
+  let seenDoubleDash = false;
+  for (const arg of args) {
+    if (seenDoubleDash) {
+      positional.push(arg);
+      continue;
+    }
+    if (arg === '--') {
+      seenDoubleDash = true;
+      continue;
+    }
+    if (arg === '--install-in-repo') {
+      flags.installInRepo = true;
+      continue;
+    }
+    if (arg === '--no-launch-metadata') {
+      flags.noLaunchMetadata = true;
+      continue;
+    }
+    if (arg === '--dry-run') {
+      flags.dryRun = true;
+      continue;
+    }
+    if (arg === '--no-skill-cache') {
+      flags.noSkillCache = true;
+      continue;
+    }
+    if (arg === '--refresh-skills') {
+      flags.refreshSkills = true;
+      continue;
+    }
+    if (arg === '--check-upstream') {
+      flags.checkUpstream = true;
+      continue;
+    }
+    if (arg === '--no-check-upstream') {
+      flags.noCheckUpstream = true;
+      continue;
+    }
+    if (arg === '-h' || arg === '--help') {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    positional.push(arg);
+  }
+  return { flags, positional };
+}
+
+export function parseCreateArgs(args: readonly string[]): {
+  flags: CreateFlags;
+  selector: string;
+  inputValues: Record<string, string>;
+} {
+  const flags: CreateFlags = {
+    installInRepo: false,
+    noLaunchMetadata: false,
+    dryRun: false,
+    noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
+    refreshSkills: false,
+    checkUpstream: false,
+    noCheckUpstream: false,
+    saveDefault: false
+  };
+  let seenDoubleDash = false;
+  const positional: string[] = [];
+  const valueOf = (i: number, flag: string): string => {
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      die(`create: ${flag} requires a value.`);
+    }
+    return v;
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (seenDoubleDash) {
+      positional.push(arg);
+      continue;
+    }
+    if (arg === '--') {
+      seenDoubleDash = true;
+      continue;
+    }
+    if (arg === '--install-in-repo') {
+      flags.installInRepo = true;
+      continue;
+    }
+    if (arg === '--no-launch-metadata') {
+      flags.noLaunchMetadata = true;
+      continue;
+    }
+    if (arg === '--save-in-directory') {
+      const value = valueOf(i, arg).trim();
+      if (!value) die('create: --save-in-directory requires a non-empty value.');
+      flags.saveInDirectory = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--save-in-directory=')) {
+      const value = arg.slice('--save-in-directory='.length).trim();
+      if (!value) die('create: --save-in-directory requires a non-empty value.');
+      flags.saveInDirectory = value;
+      continue;
+    }
+    if (arg === '--save-default') {
+      flags.saveDefault = true;
+      continue;
+    }
+    if (arg === '-h' || arg === '--help') {
+      process.stdout.write(
+        'Usage: agentworkforce create [--save-in-directory=<cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo] [--no-launch-metadata]\n'
+      );
+      process.exit(0);
+    }
+    positional.push(arg);
+  }
+
+  const [unexpected] = positional;
+  if (unexpected) {
+    die(
+      `create: unexpected argument "${unexpected}". The create command always runs ${CREATE_SELECTOR}; use "agentworkforce agent <persona>" to run another persona.`
+    );
+  }
+
+  const target = resolveCreateTarget(flags.saveInDirectory);
+  ensureCreateTargetDir(target);
+  if (flags.saveDefault) saveDefaultCreateTarget(target);
+
+  return {
+    flags,
+    selector: CREATE_SELECTOR,
+    inputValues: buildCreateInputValues(target)
+  };
+}
+
+// The CLI entry (self-run detection + fast-path dispatch) lives in cli.ts;
+// this module is imported by it and never self-runs.
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index 9108fc15..65e58458 100644
--- a/packages/cli/src/cli.test.ts
+++ b/packages/cli/src/cli.test.ts
@@ -32,7 +32,7 @@ import {
   stripAgentFlag,
   type ImproverProposal,
   type ResolvedSidecar
-} from './cli.js';
+} from './cli-impl.js';
 
 // The conflict-detection path inside parseAgentArgs uses the module-local
 // `die()` helper, which calls process.exit(1) after writing to stderr. Tests
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 7c1d1685..ff3f34f2 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -1,4745 +1,31 @@
 #!/usr/bin/env node
-import { spawn, spawnSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
-import {
-  appendFileSync,
-  closeSync,
-  cpSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  openSync,
-  readdirSync,
-  readFileSync,
-  readSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-  type Dirent
-} from 'node:fs';
-import { constants, homedir, tmpdir } from 'node:os';
-import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
+import { resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import {
-  buildCleanupArtifacts,
-  buildInstallArtifacts,
-  buildInteractiveSpec,
-  buildNonInteractiveSpec,
-  buildUpstreamRecordsFromCacheDir,
-  computeSkillCacheFingerprint,
-  detectHarnesses,
-  detectSkillUpstreamDrift,
-  formatDropWarnings,
-  HARNESS_VALUES,
-  isSkillCacheValid,
-  isUpstreamCheckDue,
-  materializeSkills,
-  MissingPersonaInputError,
-  parseCheckInterval,
-  PERSONA_TAGS,
-  readSkillCacheMarker,
-  renderPersonaInputs,
-  resolveAiMemory,
-  resolveMcpServersLenient,
-  resolvePersonaInputs,
-  resolveSidecar,
-  resolveSkillCacheDir,
-  resolveStringMapLenient,
-  updateSkillCacheMarkerUpstream,
-  writeSkillCacheMarker,
-  type Harness,
-  type HarnessAvailability,
-  type InteractiveSpec,
-  type NonInteractiveSpec,
-  type PersonaMount,
-  type AiHistMcpConfig,
-  type PersonaSelection,
-  type PersonaSpec,
-  type PersonaTag,
-  type RelayMcpConfig,
-  type SidecarMdMode,
-  type SkillMaterializationPlan
-} from '@agentworkforce/persona-kit';
-import {
-  claudeMcpConfigHasRelayOverride,
-  codexExistingArgs,
-  injectClaudeAgentRelayMcpConfig,
-  injectCodexSubcommandArgs,
-  resolveAgentRelayBrokerMcpArgs,
-  resolveRelayMcpFromEnv as resolveRelayMcpFromEnvShared
-} from '@agentworkforce/runtime';
-import {
-  listBuiltInPersonas,
-  personaCatalog,
-  routingProfiles
-} from '@agentworkforce/workload-router';
-import {
-  createMount,
-  readAgentDotfiles,
-  type AutoSyncHandle
-} from '@relayfile/local-mount';
-import ora, { type Ora } from 'ora';
-import { runDeploy, runLogin, runLogout } from './deploy-command.js';
-import { runInvoke } from './invoke-command.js';
-import { runRuns } from './runs-command.js';
-import { runDestroy } from './destroy-command.js';
-import { runIntegrationsCommand } from './integrations-command.js';
-import { runDeploymentList, runDeploymentLogs } from './list-command.js';
-import {
-  startLaunchMetadataRecording,
-  type LaunchMetadataRun
-} from './launch-metadata.js';
-import { createLogger } from './logger.js';
-import {
-  buildPersonaSourceDirectories,
-  defaultCwdPersonaDir,
-  formatPersonaSourceLabel,
-  loadLocalPersonas,
-  loadPersonaSourceConfig,
-  normalizePersonaDir,
-  savePersonaSourceConfig,
-  type PersonaSource
-} from './local-personas.js';
-import { installPersonas, type PersonaInstallResult } from './persona-install.js';
-import { runPersonaCompileCommand } from './persona-compile.js';
-import { pickPersona, type PickCandidate, type PickResult } from './persona-picker.js';
-import { recordRecent, loadRecents, runPersonaPickerTui, type TuiCandidate } from './persona-tui.js';
-import { runTrigger } from './trigger-command.js';
-
-const launchMetadataLog = createLogger('launch-metadata');
-
-const USAGE = `Usage: agentworkforce <command> [args...]
-
-Run with no arguments inside a TTY to open an interactive persona picker —
-the top 3 most recently used personas are shown first, and typing fuzzy-
-searches across persona names and descriptions. Each row's SOURCE column
-is one of: built-in (bundled), cwd (./.agentworkforce/workforce/personas),
-personal (~/.agentworkforce/workforce/personas), or dir:N (configured).
-
-Commands:
-  create [flags]     Opens persona-maker for creating a new
-                      persona, with target path passed as persona inputs.
-                      Flags:
-                        --save-in-directory=<target>
-                                            Storage target: cwd, user, dir:n,
-                                            library, or an explicit path.
-                                            Default: cwd
-                                            (<cwd>/.agentworkforce/workforce/personas);
-                                            the directory is created if missing.
-                                            Override via this flag, or pin a
-                                            different default with --save-default.
-                        --save-default      Persist --save-in-directory as
-                                            defaultCreateTarget in
-                                            ~/.agentworkforce/workforce/config.json.
-                        --install-in-repo   Same behavior as agent.
-                        --no-launch-metadata
-                                            Same behavior as agent.
-  agent [flags] <persona>
-                      Run a persona. Drops into an interactive harness session.
-
-                      Flags:
-                        --install-in-repo   Disengage the sandbox mount and
-                                            install skills into the repo's
-                                            harness-conventional directory
-                                            (.claude/skills, .opencode/skills,
-                                            .agents/skills, .grok/skills, etc.).
-                                            By default, interactive harness
-                                            sessions run inside a
-                                            @relayfile/local-mount sandbox so
-                                            npx prpm install / npx skills add
-                                            writes never touch the real repo
-                                            and CLAUDE.md / .claude / .mcp.json
-                                            (or AGENTS.md / skill roots for
-                                            non-claude harnesses) are hidden
-                                            from the session.
-                        --no-launch-metadata
-                                            Disable launch metadata recording.
-                                            Also disabled by
-                                            AGENTWORKFORCE_LAUNCH_METADATA=0.
-                        --no-skill-cache    Bypass the persistent skill-install
-                                            cache (under
-                                            ~/.agentworkforce/workforce/cache/plugins/)
-                                            and install fresh into a per-session
-                                            dir. Also disabled by
-                                            AGENTWORKFORCE_NO_SKILL_CACHE=1.
-                        --refresh-skills    Force a fresh install of the skill
-                                            cache entry for this persona,
-                                            overwriting any existing cache dir.
-                        --check-upstream    Force an upstream drift check this
-                                            launch (prpm version / GitHub blob
-                                            SHA) regardless of the TTL. A drifted
-                                            skill triggers a reinstall.
-                        --no-check-upstream Skip the upstream drift check this
-                                            launch regardless of the TTL.
-                                            Interval is otherwise 24h, tunable
-                                            via
-                                            AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL
-                                            (e.g. 24h, 30m, 0=always,
-                                            never=disable).
-                        --dry-run           Validate the persona without
-                                            spawning the harness or burning
-                                            tier-model tokens. Three checks:
-                                            (1) sidecar — claudeMd / agentsMd
-                                            filename refs are readable;
-                                            (2) harness spec — permissions /
-                                            mcpServers / harness-settings
-                                            shape is accepted by the harness
-                                            translator; (3) skills — each
-                                            \`skills[].source\` is run through
-                                            its real installer (npx skills
-                                            add / npx prpm install) inside a
-                                            fresh temp dir, with per-skill
-                                            pass/fail reporting. Use this in
-                                            the persona-author loop to catch
-                                            hallucinated skill names and
-                                            malformed config before a persona
-                                            ships. Temp dir is removed on
-                                            success, kept on failure for
-                                            inspection.
-  list [flags]        List available personas from the cascade (cwd →
-                      configured persona dirs → library). Flags:
-                        --deployments                 list deployed cloud agents
-                        --json                        emit JSON instead of a table
-                        --filter-harness <harness>    only show this harness
-                                                      (${HARNESS_VALUES.join(' | ')})
-                        --filter-tag <tag>            only show personas carrying this tag
-                                                      (free-form; common built-in tags: ${PERSONA_TAGS.join(' | ')})
-                        --no-display-description      hide the DESCRIPTION column
-  show <persona>      Print the fully-resolved spec for a single persona,
-                      including which cascade layer defined it (cwd, user,
-                      dir:<n>, library). Flags:
-                        --json        emit the resolved PersonaSpec as JSON
-  persona compile <path/to/persona.ts>
-                      Compile a typed persona.ts authoring file to sibling
-                      persona.json after validating it with persona-kit.
-  install [flags] <pkg|path>
-                      Copy persona JSON files from an npm package or local
-                      package directory into
-                      <cwd>/.agentworkforce/workforce/personas/. Flags:
-                        --persona <id>  install only the matching persona id;
-                                        repeat to install multiple
-                        --overwrite     replace existing target files
-  sources list [--json]
-                      List persona source directories in cascade order.
-  sources add <dir> [--position <n>]
-                      Add a configurable persona source directory. Position is
-                      1-based among configurable dirs after the fixed cwd dir.
-  sources remove <dir|n>
-                      Remove a configurable persona source directory by path or
-                      1-based configurable position.
-  integrations [provider] [--all] [--json]
-                      Discover workspace integrations, connection status, and
-                      known trigger events.
-  trigger <agent-name-or-id> [flags]
-                      Manually fire an active deployed persona for testing.
-                      The selector accepts agent id, compact agent id,
-                      deployed name, persona slug, or persona id. Flags:
-                        --workspace <name>  Workforce workspace; defaults to
-                                            the active workspace
-                        --cloud-url <url>   Override the cloud base URL
-                        --json              Emit JSON
-                        --no-prompt         Fail instead of prompting for login
-  harness check       Probe which harnesses (${HARNESS_VALUES.join(', ')}) are
-                      installed and runnable on this machine.
-  pick "<task>"       Pick the best-fit persona for a free-text task description
-                      using a cheap LLM call (Claude Haiku via the local
-                      \`claude\` CLI). Prints the matched persona id to stdout
-                      on success. On low confidence, prompts (TTY) to launch
-                      persona-maker with the task as input, or exits non-zero
-                      (non-TTY) with a hint.
-                      Exit codes: 0 match, 2 no match, 3 picker unavailable.
-  deploy <persona-path> [flags]
-                      Deploy a persona as a managed agent. <persona-path> may
-                      be prebuilt persona.json or authored persona.ts/js.
-                      Modes:
-                        --mode dev          run the persona locally (default if
-                                            no Daytona/workspace creds resolve)
-                        --mode sandbox      run inside a Daytona sandbox
-                                            (default when creds resolve)
-                        --mode cloud        POST persona + bundle to the
-                                            workforce cloud workspace
-                      Flags:
-                        --workspace <name>  pick a non-default workspace
-                        --no-connect        skip integration-connect prompts
-                                            (fail if any integration is missing)
-                        --byo-sandbox       force BYO Daytona auth
-                        --detach            background the runner instead of
-                                            streaming logs in the foreground
-                        --bundle-out <dir>  emit the bundle to <dir> and exit
-                                            without launching
-                        --dry-run           validate the persona; no side effects
-                        --cloud-url <url>   override the workforce cloud URL
-                        --input KEY=value   override a declared persona input
-                                            (repeat for multiple)
-  invoke <persona-path> --fixture <file> [flags]
-                      Simulate an invocation: run the persona's handler
-                      against fixture event envelope(s) with every external
-                      side effect recorded, NOT executed. Emits a
-                      Cloud-compatible run record (origin "local_dry_run")
-                      to stdout. Distinct from \`deploy --dry-run\`, which
-                      validates without invoking the handler.
-                      Flags:
-                        --fixture <file>    JSON envelope, JSON array, or
-                                            NDJSON of raw gateway envelopes
-                        --output <file>     write the run record to a file
-                        --input KEY=value   override a declared persona input
-                        --seed PATH=file    seed the simulated filesystem
-                        --workspace <id>    workspace id for the simulated ctx
-                        --scaffold <type>   emit a fixture skeleton for an
-                                            event type instead of running
-                                            (no persona needed)
-  runs export <runId> [flags]
-                      Export the gateway envelope cloud delivered to a run
-                      as a replayable invoke fixture. Flags:
-                        --agent <selector>  agentId/deployedName owning the
-                                            run (otherwise all are checked)
-                        --fixture <file>    write the fixture to a file
-  deployments list    List deployed cloud agents in the active workspace.
-  deployments logs    Show structured logs for a deployed cloud agent.
-  destroy <persona-or-agent-id> [flags]
-                      Tear down a deployed agent: cancel all schedules and
-                      mark the agent as destroyed in the workspace. Accepts
-                      either a persona JSON path (resolved to an agent id
-                      via the workspace's agents index) or a literal agent
-                      UUID.
-                      Flags:
-                        --workspace <id>    pick a non-default workspace
-                        --cloud-url <url>   override the workforce cloud URL
-                        --no-prompt         fail instead of opening the
-                                            browser login flow
-                      Exit codes: 0 destroyed, 2 not found / already
-                      destroyed, 1 any other error.
-  login               Connect this machine to a workforce workspace using
-                      browser OAuth and store a workspace token.
-  logout              Clear browser OAuth auth and the stored workspace token.
-
-Options:
-  -h, --help          Show this help text.
-  -v, --version       Print the agentworkforce version.
-
-Local personas cascade: <cwd>/.agentworkforce/workforce/personas/*.json → configured persona dirs → repo library.
-Each layer only needs to specify fields it overrides; everything else inherits
-from the next lower layer. "extends" explicitly names a base; omit it and the
-loader implicitly inherits from the same-id persona below. By default the only
-configured persona dir is ~/.agentworkforce/workforce/personas.
-
-Examples:
-  agentworkforce create
-  agentworkforce create --save-in-directory=user
-  agentworkforce install @agentworkforce/personas-core --persona code-reviewer
-  agentworkforce agent code-reviewer
-  agentworkforce agent my-reviewer
-  agentworkforce list
-  agentworkforce show code-reviewer
-  agentworkforce install @agentrelay/personas --persona relay-orchestrator
-  agentworkforce install ./local-personas --overwrite
-  agentworkforce sources list
-  agentworkforce sources add ../my-personas --position 1
-  agentworkforce integrations --all
-  agentworkforce harness check
-  agentworkforce pick "review this PR for security issues"
-  agentworkforce agent "$(agentworkforce pick "fix the flaky test in foo.test.ts")"
-  agentworkforce deploy ./personas/weekly-digest.json --mode cloud
-  agentworkforce deploy ./personas/weekly-digest.json --mode sandbox --input TOPIC="Deploy v1"
-  agentworkforce destroy ./personas/weekly-digest.json
-  agentworkforce destroy 11111111-2222-4333-8444-555555555555
-  agentworkforce login
-`;
-
-function die(msg: string, withUsage = true): never {
-  process.stderr.write(`${msg}\n`);
-  if (withUsage) process.stderr.write(`\n${USAGE}`);
-  process.exit(1);
-}
-
-function readPackageVersion(): string {
-  const pkg = JSON.parse(
-    readFileSync(new URL('../package.json', import.meta.url), 'utf8')
-  ) as { version?: unknown };
-  if (typeof pkg.version !== 'string' || !pkg.version) {
-    throw new Error('Could not read @agentworkforce/cli package version.');
-  }
-  return pkg.version;
-}
-
-export const CLI_VERSION = readPackageVersion();
-export const CREATE_SELECTOR = 'persona-maker';
-
-const CREATE_INPUT_TARGET_DIR = 'TARGET_DIR';
-const CREATE_INPUT_CREATE_MODE = 'CREATE_MODE';
-
-const local = loadLocalPersonas();
-for (const warning of local.warnings) {
-  process.stderr.write(`warning: ${warning}\n`);
-}
-
-type ResolvedTarget =
-  | { kind: 'repo'; source: 'library'; spec: PersonaSpec }
-  | { kind: 'local'; source: PersonaSource; spec: PersonaSpec };
-
-interface KnownPersonaRow {
-  name: string;
-  description: string;
-}
-
-function collectKnownPersonas(): KnownPersonaRow[] {
-  const byName = new Map<string, KnownPersonaRow>();
-  for (const spec of local.byId.values()) {
-    byName.set(spec.id, {
-      name: spec.id,
-      description: spec.description
-    });
-  }
-  for (const spec of listBuiltInPersonas()) {
-    if (byName.has(spec.id)) continue;
-    byName.set(spec.id, {
-      name: spec.id,
-      description: spec.description
-    });
-  }
-  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
-
-function formatNameDescriptionTable(rows: readonly KnownPersonaRow[]): string {
-  const headers: KnownPersonaRow = {
-    name: 'NAME',
-    description: 'DESCRIPTION'
-  };
-  const rendered = rows.map((r) => ({
-    name: r.name,
-    description: r.description.replace(/\s+/g, ' ').trim()
-  }));
-  const nameWidth = Math.max(
-    headers.name.length,
-    ...rendered.map((r) => r.name.length)
-  );
-  const termWidth =
-    process.stderr.isTTY && typeof process.stderr.columns === 'number'
-      ? process.stderr.columns
-      : 120;
-  const descBudget = Math.max(
-    headers.description.length,
-    Math.max(32, termWidth - nameWidth - 3)
-  );
-  const truncate = (text: string) =>
-    text.length <= descBudget
-      ? text
-      : `${text.slice(0, Math.max(1, descBudget - 3)).trimEnd()}...`;
-  const line = (row: KnownPersonaRow) =>
-    `${row.name.padEnd(nameWidth)} | ${truncate(row.description)}`.trimEnd();
-  return [line(headers), ...rendered.map(line)].join('\n');
-}
-
-function resolveSpec(key: string): ResolvedTarget['spec'] | { error: string } {
-  const localSpec = local.byId.get(key);
-  if (localSpec) return localSpec;
-  const catalogAsIntent = (personaCatalog as Record<string, PersonaSpec | undefined>)[key];
-  if (catalogAsIntent) return catalogAsIntent;
-  const byId = listBuiltInPersonas().find((p) => p.id === key);
-  if (byId) return byId;
-
-  const packHint =
-    'Optional first-party personas are installed from packs, for example:\n' +
-    '  agentworkforce install @agentworkforce/personas-core\n' +
-    '  agentworkforce install @agentrelay/personas';
-  return {
-    error: `Unknown persona "${key}". Known personas:\n${formatNameDescriptionTable(collectKnownPersonas())}\n\n${packHint}`
-  };
-}
-
-function parseSelector(sel: string): ResolvedTarget {
-  // Catch legacy `@<tier>` selectors and point users at the new selector form.
-  // Tiers were removed; a persona's runtime fields now live at the top level.
-  const at = sel.indexOf('@');
-  if (at !== -1) {
-    const suffix = sel.slice(at + 1);
-    die(
-      `@<tier> selectors were removed; tiers are no longer part of the persona shape. ` +
-        `Use 'agentworkforce agent ${sel.slice(0, at)}' instead (drop "@${suffix}").`,
-      false
-    );
-  }
-  const key = sel;
-  if (!key) die('Missing persona name');
-  const result = resolveSpec(key);
-  if ('error' in result) die(result.error, false);
-  const kind = local.byId.has(key) ? 'local' : 'repo';
-  if (kind === 'local') {
-    return { kind, source: local.sources.get(result.id) ?? 'cwd', spec: result };
-  }
-  return { kind, source: 'library', spec: result };
-}
-
-/**
- * Resolve the `<harness>` placeholder used in persona systemPrompts.
- * Personas embed `<harness>` inside example install commands (e.g.
- * `npx prpm install <ref> --as <harness>`) so the docstring stays
- * harness-agnostic in source. The active harness is known at selection
- * time, so swap it in here to give the model a concrete command.
- *
- * Exported for test coverage. Only `<harness>` is resolved today; other
- * angle-bracketed tokens in the prompt (e.g. `<ref>`, `<repo-url>`,
- * `<query>`) are deliberately left as LLM-facing placeholders.
- */
-export function resolveSystemPromptPlaceholders(prompt: string, harness: Harness): string {
-  return prompt.replaceAll('<harness>', harness);
-}
-
-function buildSelection(spec: PersonaSpec, kind: 'repo' | 'local'): PersonaSelection {
-  // An interactive `agentworkforce agent` run spawns a harness session, which
-  // requires harness/model/systemPrompt. These are optional on the spec only
-  // for handler-style (onEvent) personas, which are deployed — not run
-  // interactively — so reject them here with a pointed error.
-  if (!spec.harness || !spec.model || spec.systemPrompt === undefined) {
-    throw new Error(
-      `persona "${spec.id}" cannot be run interactively: it omits ${[
-        !spec.harness && 'harness',
-        !spec.model && 'model',
-        spec.systemPrompt === undefined && 'systemPrompt'
-      ]
-        .filter(Boolean)
-        .join(', ')}. Handler-style personas (onEvent) are deployed via \`agentworkforce deploy\`, not run with \`agentworkforce agent\`.`
-    );
-  }
-  const systemPrompt = resolveSystemPromptPlaceholders(spec.systemPrompt, spec.harness);
-  const sidecar = resolveSidecar(spec);
-  // Built-in personas: prefer the routing-profile rationale string so the
-  // selection carries the policy-explained "why" rather than a generic label.
-  const rationale =
-    kind === 'local'
-      ? `local-override: ${spec.id}`
-      : (
-          routingProfiles.default.intents as Partial<Record<string, { rationale: string }>>
-        )[spec.intent]?.rationale ?? `cli: ${spec.id}`;
-  return {
-    personaId: spec.id,
-    harness: spec.harness,
-    model: spec.model,
-    systemPrompt,
-    harnessSettings: spec.harnessSettings,
-    skills: spec.skills,
-    rationale,
-    ...(spec.inputs ? { inputs: spec.inputs } : {}),
-    ...(spec.env ? { env: spec.env } : {}),
-    ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
-    ...(spec.permissions ? { permissions: spec.permissions } : {}),
-    ...(spec.mount ? { mount: spec.mount } : {}),
-    ...(spec.memory !== undefined ? { memory: spec.memory } : {}),
-    ...(sidecar.claudeMd ? { claudeMd: sidecar.claudeMd } : {}),
-    ...(sidecar.claudeMdContent ? { claudeMdContent: sidecar.claudeMdContent } : {}),
-    ...(sidecar.claudeMd || sidecar.claudeMdContent
-      ? { claudeMdMode: sidecar.claudeMdMode }
-      : {}),
-    ...(sidecar.agentsMd ? { agentsMd: sidecar.agentsMd } : {}),
-    ...(sidecar.agentsMdContent ? { agentsMdContent: sidecar.agentsMdContent } : {}),
-    ...(sidecar.agentsMd || sidecar.agentsMdContent
-      ? { agentsMdMode: sidecar.agentsMdMode }
-      : {})
-  };
-}
-
-function emitDropWarnings(lines: string[]): void {
-  if (lines.length === 0) return;
-  for (const line of lines) process.stderr.write(`warning: ${line}\n`);
-  process.stderr.write(
-    `        (referenced env vars were not set — proceeding without those values; if the agent relies on them it may need to authenticate interactively, e.g. via OAuth.)\n`
-  );
-}
-
-/**
- * Detect that we're launching under an Agent Relay broker and, if so, build the
- * relaycast wiring to inject into the harness's MCP config so the persona can
- * message the team — the same capability a non-persona broker spawn gets.
- *
- * Delegates to the shared `resolveRelayMcpFromEnv` in `@agentworkforce/runtime`.
- */
-const resolveRelayMcpFromEnv = resolveRelayMcpFromEnvShared;
-
-/**
- * Build the `ai-hist` MCP config for a session. Only called when the persona
- * opts into recall via `memory.aiMemory` (off by default). `TRAJECTORY_ROOT`
- * (env) seeds the "why" read-root; `dbPathOverride` (from `memory.aiMemory.dbPath`)
- * else `AI_HIST_DB` env seeds the "how" history DB. Anything unset falls back to
- * the MCP's own discovery defaults.
- */
-function resolveAiHistConfig(
-  env: NodeJS.ProcessEnv,
-  dbPathOverride?: string
-): AiHistMcpConfig {
-  const trajectoryRoot = env.TRAJECTORY_ROOT?.trim();
-  const dbPath = dbPathOverride?.trim() || env.AI_HIST_DB?.trim();
-  return {
-    ...(trajectoryRoot ? { trajectoryRoot } : {}),
-    ...(dbPath ? { dbPath } : {})
-  };
-}
-
-function signalExitCode(signal: NodeJS.Signals | null): number {
-  if (!signal) return 0;
-  const num = (constants.signals as Record<string, number | undefined>)[signal];
-  return 128 + (num ?? 1);
-}
-
-/**
- * Derive a meaningful exit code from a `spawnSync` result. `spawnSync`
- * sets `status` to null and `signal` to the signal name (e.g. `SIGINT`)
- * when the child was killed before it could set its own exit code, so
- * a naive `res.status ?? 1` collapses Ctrl-C / SIGTERM onto generic
- * failure instead of the conventional 128+N.
- */
-function subprocessExitCode(res: ReturnType<typeof spawnSync>): number {
-  if (res.status !== null) return res.status;
-  if (res.signal) return signalExitCode(res.signal);
-  return 1;
-}
-
-/**
- * Run a skill-install subprocess behind an ora spinner. stdout and stderr are
- * captured so a successful install collapses to a single ✓ line; on failure,
- * 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.
- */
-async function runInstallWithSpinner(
-  command: readonly string[],
-  label: string,
-  cwd: string | undefined
-): Promise<{ code: number; output: string }> {
-  const [bin, ...args] = command;
-  if (!bin) return { code: 0, output: '' };
-  const spinner = ora({ text: 'Installing skills…', stream: process.stderr }).start();
-  // 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<{ code: number; output: string }>((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: string) => {
-      buffered += chunk;
-    });
-    child.stderr?.on('data', (chunk: string) => {
-      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 });
-    });
-  });
-  if (code === 0) {
-    spinner.succeed(label);
-  } else {
-    spinner.fail(`${label} failed (exit ${code})`);
-    if (output.trim()) process.stderr.write(output.endsWith('\n') ? output : `${output}\n`);
-  }
-  return { code, output };
-}
-
-async function runInstall(command: readonly string[], label: string, cwd?: string): Promise<void> {
-  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 } = await runInstallWithSpinner(command, label, cwd);
-  if (code !== 0) process.exit(code);
-}
-
-/**
- * Thrown by `runInstallOrThrow` when the install subprocess exits non-zero.
- * Carries the underlying exit code so the mount-branch catch can surface it
- * to the user instead of collapsing every failure onto 127.
- */
-class InstallCommandError extends Error {
-  readonly exitCode: number;
-  constructor(label: string, exitCode: number) {
-    super(`${label} failed (exit ${exitCode})`);
-    this.name = 'InstallCommandError';
-    this.exitCode = exitCode;
-  }
-}
-
-/**
- * Install variant that throws instead of calling `process.exit` on failure.
- * Used inside the mount branch's onBeforeLaunch step so mount teardown runs
- * before the error surfaces.
- */
-async function runInstallOrThrow(
-  command: readonly string[],
-  label: string,
-  cwd: string
-): Promise<void> {
-  const [bin] = command;
-  if (!bin) return;
-  const { code } = await runInstallWithSpinner(command, label, cwd);
-  if (code !== 0) {
-    throw new InstallCommandError(label, code);
-  }
-}
-
-/**
- * CLI-side install context shaped like workload-router's `useSelection().install`.
- * Built directly from persona-kit's pure helpers
- * ({@link materializeSkills}, {@link buildInstallArtifacts},
- * {@link buildCleanupArtifacts}) so the spawn flow can keep its own
- * spinner-driven install/cleanup orchestration without importing
- * `useSelection` from `@agentworkforce/workload-router`.
- */
-interface CliInstallContext {
-  plan: SkillMaterializationPlan;
-  command: readonly string[];
-  commandString: string;
-  cleanupCommand: readonly string[];
-  cleanupCommandString: string;
-}
-
-function buildInstallContext(
-  selection: PersonaSelection,
-  options: { installRoot?: string; repoRoot?: string } = {}
-): CliInstallContext {
-  const plan = materializeSkills(selection.skills, selection.harness, {
-    ...(options.installRoot !== undefined ? { installRoot: options.installRoot } : {}),
-    ...(options.repoRoot !== undefined ? { repoRoot: options.repoRoot } : {})
-  });
-  const { installCommand, installCommandString } = buildInstallArtifacts(plan);
-  const { cleanupCommand, cleanupCommandString } = buildCleanupArtifacts(plan);
-  return {
-    plan,
-    command: installCommand,
-    commandString: installCommandString,
-    cleanupCommand,
-    cleanupCommandString
-  };
-}
-
-function runCleanup(command: readonly string[], commandString: string): void {
-  if (commandString === ':') return;
-  const [bin, ...args] = command;
-  if (!bin) return;
-  spawnSync(bin, args, { stdio: 'inherit', shell: false });
-}
-
-/**
- * Remove the whole per-session directory after the run, including the
- * enclosing `<homedir>/.agentworkforce/workforce/sessions/<id>/` that the CLI
- * created. The workload-router cleanup only covers the install subtree
- * (`<root>/claude/plugin`), so without this step empty parent dirs
- * would accumulate under `~/.agentworkforce/workforce/sessions/`.
- *
- * Uses `fs.rmSync` rather than `spawnSync('rm', …)` so the teardown works
- * on Windows where `rm` isn't on PATH.
- */
-function removeSessionRoot(sessionRoot: string | undefined): void {
-  if (!sessionRoot) return;
-  try {
-    rmSync(sessionRoot, { recursive: true, force: true });
-  } catch {
-    /* best-effort — if teardown fails the dir is harmless under ~/.agentworkforce/workforce/sessions */
-  }
-}
-
-/**
- * Compute the absolute root directory for an interactive claude session.
- * Layout (under `root`):
- *
- *   ~/.agentworkforce/workforce/sessions/<personaId>-<timestamp>-<rand>/
- *     ├── claude/plugin/     ← skill install target + --plugin-dir
- *     └── mount/             ← @relayfile/local-mount mount
- *
- * The timestamp + random suffix keep concurrent sessions from colliding on
- * the same dir. Both the skill-install path and the mount path are derived
- * from the same `root` so a single session ID describes the whole run.
- */
-function generateSessionRoot(personaId: string): string {
-  const sessionId = `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
-  return join(homedir(), '.agentworkforce', 'workforce', 'sessions', `${personaId}-${sessionId}`);
-}
-
-function sessionInstallRoot(sessionRoot: string): string {
-  return join(sessionRoot, 'claude', 'plugin');
-}
-
-function sessionMountDir(sessionRoot: string): string {
-  return join(sessionRoot, 'mount');
-}
-
-/** Default upstream drift-check interval when neither flag nor env overrides. */
-const DEFAULT_SKILL_CACHE_CHECK_INTERVAL_MS = 24 * 3_600_000;
-
-/**
- * Resolve the env-configured drift-check interval.
- *
- * `parseCheckInterval` returns three things we must keep distinct:
- *   - a number  → an explicit interval (incl. `0` = always)
- *   - `null`    → the user explicitly disabled checks (`never`/`off`/`false`)
- *   - `undefined` → unset or unparseable → fall back to the 24h default
- *
- * A plain `?? DEFAULT` is wrong here because `??` also coalesces `null`,
- * silently re-enabling checks the user asked to turn off.
- */
-export function resolveEnvCheckIntervalMs(): number | null {
-  const parsed = parseCheckInterval(
-    process.env.AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL
-  );
-  return parsed === undefined ? DEFAULT_SKILL_CACHE_CHECK_INTERVAL_MS : parsed;
-}
-
-interface SkillCacheLockHandle {
-  release(): void;
-}
-
-// A lock is considered abandoned if its heartbeat timestamp is older than
-// this — covers a holder that was SIGKILLed without releasing.
-const SKILL_CACHE_LOCK_STALE_MS = 15 * 60_000;
-const SKILL_CACHE_LOCK_HEARTBEAT_MS = 60_000;
-// Upper bound on how long we'll wait for a peer's install before proceeding
-// best-effort (unlocked). A real skill install is seconds; this is generous.
-const SKILL_CACHE_LOCK_WAIT_MS = 10 * 60_000;
-const SKILL_CACHE_LOCK_POLL_MS = 250;
-
-function skillCachePidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    // EPERM => process exists but we can't signal it (still alive).
-    return (e as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
-function skillCacheLockIsStale(lockPath: string): boolean {
-  try {
-    const [pidRaw, tsRaw] = readFileSync(lockPath, 'utf8').split('\n');
-    const ts = Number(tsRaw);
-    if (Number.isFinite(ts) && Date.now() - ts > SKILL_CACHE_LOCK_STALE_MS) {
-      return true;
-    }
-    const pid = Number(pidRaw);
-    if (Number.isInteger(pid) && pid > 0 && !skillCachePidAlive(pid)) {
-      return true;
-    }
-    return false;
-  } catch {
-    // Unreadable (just removed by the holder?) — treat as stale so we retry
-    // the exclusive create rather than spin forever.
-    return true;
-  }
-}
-
-function writeSkillCacheLockFile(lockPath: string, token: string): void {
-  writeFileSync(lockPath, `${process.pid}\n${Date.now()}\n${token}\n`);
-}
-
-function skillCacheLockTokenMatches(lockPath: string, token: string): boolean {
-  try {
-    const [, , foundToken] = readFileSync(lockPath, 'utf8').split('\n');
-    return foundToken === token;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Acquire a per-fingerprint advisory lock so two concurrent
- * `agentworkforce agent <same-persona>` launches don't both miss the cache
- * and install into the same dir simultaneously (which can interleave
- * `prpm install` writes and corrupt the cache).
- *
- * The lock is a sibling file `<cacheDir>.lock` (NOT inside the cache dir, so
- * a `--refresh-skills` wipe of the dir can't delete a live lock). Created
- * with `wx` (O_EXCL) for atomicity. A held lock is stolen only if its holder
- * is dead or its heartbeat is stale. If we can't get it within the wait
- * budget we return null and the caller proceeds unlocked (best-effort —
- * never hang a launch on locking).
- */
-export async function acquireSkillCacheLock(
-  skillCacheDir: string
-): Promise<SkillCacheLockHandle | null> {
-  const lockPath = `${skillCacheDir}.lock`;
-  try {
-    mkdirSync(dirname(lockPath), { recursive: true });
-  } catch {
-    return null;
-  }
-  const deadline = Date.now() + SKILL_CACHE_LOCK_WAIT_MS;
-  for (;;) {
-    try {
-      const token = randomBytes(16).toString('hex');
-      writeFileSync(lockPath, `${process.pid}\n${Date.now()}\n${token}\n`, {
-        flag: 'wx'
-      });
-      const heartbeat = setInterval(() => {
-        if (!skillCacheLockTokenMatches(lockPath, token)) return;
-        try {
-          writeSkillCacheLockFile(lockPath, token);
-        } catch {
-          /* best-effort heartbeat */
-        }
-      }, SKILL_CACHE_LOCK_HEARTBEAT_MS);
-      heartbeat.unref?.();
-      let released = false;
-      return {
-        release() {
-          if (released) return;
-          released = true;
-          clearInterval(heartbeat);
-          try {
-            if (skillCacheLockTokenMatches(lockPath, token)) {
-              rmSync(lockPath, { force: true });
-            }
-          } catch {
-            /* best-effort — a stale-steal by another proc is harmless */
-          }
-        }
-      };
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') {
-        // Unexpected FS error: don't block the launch on locking.
-        return null;
-      }
-      if (skillCacheLockIsStale(lockPath)) {
-        try {
-          rmSync(lockPath, { force: true });
-        } catch {
-          /* lost the steal race — loop and re-evaluate */
-        }
-        continue;
-      }
-      if (Date.now() >= deadline) return null;
-      await new Promise((r) => setTimeout(r, SKILL_CACHE_LOCK_POLL_MS));
-    }
-  }
-}
-
-/**
- * Persist the cache marker after a successful install, folding in each
- * skill's upstream identity (prpm version / github blob SHA) read from the
- * lockfiles the installers just wrote into `cacheDir`. Sets
- * `lastUpstreamCheckAt` to now so the first launch within the TTL window
- * doesn't immediately re-probe what we just resolved.
- *
- * Best-effort on the upstream side: a probe failure for a given skill simply
- * omits its `upstream` record (the next drift pass will try again). The
- * marker itself is always written — its presence is what makes the cache
- * dir "valid".
- */
-async function writeMarkerWithUpstream(
-  cacheDir: string,
-  fingerprint: string,
-  harness: Harness,
-  skills: readonly { id: string; source: string }[]
-): Promise<void> {
-  let upstream: Map<string, { kind: string } | undefined> | undefined;
-  try {
-    upstream = (await buildUpstreamRecordsFromCacheDir(cacheDir, skills)) as Map<
-      string,
-      { kind: string } | undefined
-    >;
-  } catch {
-    upstream = undefined;
-  }
-  writeSkillCacheMarker(cacheDir, {
-    fingerprint,
-    harness,
-    lastUpstreamCheckAt: new Date().toISOString(),
-    skills: skills.map((s) => {
-      const rec = upstream?.get(s.id);
-      return {
-        id: s.id,
-        source: s.source,
-        ...(rec ? { upstream: rec as never } : {})
-      };
-    })
-  });
-}
-
-/**
- * Mirror the contents of a populated skill cache dir into a target dir
- * (typically a relayfile mount root). Skips the cache marker file so it
- * never lands inside the harness's view.
- *
- * Used by the mount-harness branch to give non-claude harnesses the same
- * "install once, reuse forever" behaviour that claude gets for free via
- * `--plugin-dir <cacheDir>`. The destination is expected to be the mount
- * root: skill artifacts under `.skills/`, `.opencode/`, `.agents/`, `.grok/skills`,
- * etc. are
- * declared as mount-ignored patterns so the mirror does not sync back to the
- * user's real repo on session exit.
- */
-function mirrorSkillCacheInto(cacheDir: string, targetDir: string): void {
-  if (!existsSync(cacheDir)) return;
-  for (const entry of readdirSync(cacheDir, { withFileTypes: true })) {
-    if (entry.name === '.aw-skill-cache.json') continue;
-    const from = join(cacheDir, entry.name);
-    const to = join(targetDir, entry.name);
-    cpSync(from, to, {
-      recursive: true,
-      // Don't overwrite a path the mount mirror or persona setup already
-      // created — surfacing the conflict as an error here would be loud and
-      // unactionable; the mount-ignored patterns guarantee any pre-existing
-      // entry under these names came from a prior cache mirror in this same
-      // session, which is fine to leave alone.
-      force: false,
-      errorOnExist: false
-    });
-  }
-}
-
-/**
- * Remove every `--agent <id>` pair from a harness argv. Used on the non-mount
- * opencode path where we cannot safely materialize the persona's
- * opencode.json (it would land in the user's real repo), so we fall back to
- * launching opencode without a persona-specific agent selection.
- *
- * Strips all occurrences rather than just the first — the current producer
- * (the opencode branch in persona-kit) emits exactly one pair, so both
- * behaviors are equivalent today, but "remove all" is idempotent and safer if
- * a future caller ever appends a second `--agent` for any reason. A trailing
- * `--agent` with no following value is preserved so the malformed argv
- * surfaces at the harness rather than getting silently swallowed here.
- */
-export function stripAgentFlag(args: readonly string[]): string[] {
-  const out: string[] = [];
-  for (let i = 0; i < args.length; i += 1) {
-    if (args[i] === '--agent' && i + 1 < args.length) {
-      i += 1;
-      continue;
-    }
-    out.push(args[i]);
-  }
-  return out;
-}
-
-/**
- * Validate that a configFile's relative path is safe to resolve under a
- * sandbox/session directory. Rejects absolute paths and any segment equal to
- * `..` so a malformed or adversarial persona cannot escape the mount via
- * `join()` and overwrite files elsewhere. Called at materialization time so
- * the failure surfaces with a clear path before any disk write happens.
- */
-export function assertSafeRelativePath(relPath: string): void {
-  if (!relPath) {
-    throw new Error('configFile path must be a non-empty relative path');
-  }
-  if (isAbsolute(relPath)) {
-    throw new Error(
-      `configFile path must be relative; got absolute path ${JSON.stringify(relPath)}`
-    );
-  }
-  const segments = relPath.split(/[\\/]+/);
-  if (segments.some((s) => s === '..')) {
-    throw new Error(
-      `configFile path must not contain ".." segments; got ${JSON.stringify(relPath)}`
-    );
-  }
-}
-
-/** Patterns hidden from an interactive claude session by the sandbox mount.
- * Applied by `@relayfile/local-mount` with gitignore semantics, so bare names
- * match at any depth in the project tree (e.g. `.claude` hides both
- * `./.claude/` and `./packages/foo/.claude/`). */
-export const CLEAN_IGNORED_PATTERNS = [
-  'CLAUDE.md',
-  'CLAUDE.local.md',
-  '.claude',
-  '.mcp.json',
-  // Per-persona AGENTS.md sidecars get materialized into the mount when
-  // running under a non-claude harness; without this the user's real-cwd AGENTS.md
-  // would copy in (masking the persona content) and writes from
-  // onBeforeLaunch would sync back out.
-  'AGENTS.md'
-] as const;
-
-/**
- * Skill-install artifacts that should never be copied into the mount nor
- * synced back to the real repo. Applied to non-claude interactive sessions
- * that rely on the mount to keep `npx skills add` / `npx prpm install`
- * writes out of the user's project tree. Covers every per-provider output
- * root that skill.sh / prpm scatter into on install — missing one here
- * re-introduces repo pollution, so this list is deliberately superset-y.
- * Claude sessions use `installRoot` for out-of-repo staging instead, so
- * these patterns don't apply there.
- */
-export const SKILL_INSTALL_IGNORED_PATTERNS = [
-  // skill.sh universal install root + per-harness symlink farms
-  '.agents',
-  '.claude/skills',
-  '.factory/skills',
-  '.grok/skills',
-  '.kiro/skills',
-  'skills',
-  // prpm `--as <harness>` output roots
-  '.opencode',
-  '.skills',
-  // provider lockfiles written at the repo root
-  'prpm.lock',
-  'skills-lock.json',
-  // Per-persona AGENTS.md sidecars (non-claude harnesses) get materialized
-  // into the mount; hide so the real-cwd AGENTS.md isn't copied in and
-  // the persona-written copy doesn't sync back out.
-  'AGENTS.md'
-] as const;
-
-export interface RelayfileMountPatterns {
-  ignoredPatterns: string[];
-  readonlyPatterns: string[];
-}
-
-export function buildRelayfileMountPatterns(input: {
-  projectDir: string;
-  personaId: string;
-  harness: Harness;
-  mount?: PersonaMount;
-  configFilePaths?: readonly string[];
-}): RelayfileMountPatterns {
-  const dotfiles = readAgentDotfiles(input.projectDir, {
-    agentName: input.personaId
-  });
-  const builtInIgnored =
-    input.harness === 'claude'
-      ? CLEAN_IGNORED_PATTERNS
-      : SKILL_INSTALL_IGNORED_PATTERNS;
-
-  return {
-    ignoredPatterns: [
-      ...dotfiles.ignoredPatterns,
-      ...(input.mount?.ignoredPatterns ?? []),
-      ...builtInIgnored,
-      ...(input.configFilePaths ?? [])
-    ],
-    readonlyPatterns: [
-      ...dotfiles.readonlyPatterns,
-      ...(input.mount?.readonlyPatterns ?? [])
-    ]
-  };
-}
-
-/**
- * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
- * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
- * `opencode.json` written by `onBeforeLaunch`) don't surface under
- * "Untracked files" in `git status` inside the mount.
- *
- * Exported pure helper for unit-testing the formatting separately from the
- * disk-writing wrapper below.
- */
-export function buildMountGitExcludeBlock(patterns: readonly string[]): string {
-  const lines = [
-    '',
-    '# agentworkforce: patterns hidden from this sandboxed session.',
-    '# Tracked paths matching these patterns are also marked skip-worktree',
-    '# so `git status` does not report them as deleted.',
-    ...patterns,
-    ''
-  ];
-  return lines.join('\n');
-}
-
-/**
- * Configure the mount's per-session `.git` so paths hidden by the relayfile
- * mount don't show as deleted/untracked inside the sandbox.
- *
- * - Appends `patterns` to `.git/info/exclude` so untracked-and-hidden files
- *   don't show up under "Untracked files".
- * - Marks every tracked file matching one of the patterns as skip-worktree
- *   so `git status` doesn't list it as deleted (the work tree omits it on
- *   purpose, not by user action).
- *
- * Best-effort: if the mount has no `.git` (project isn't a repo, or
- * `includeGit: false`) or any git command fails, returns silently. The
- * mount's `.git` is per-session and `noSyncBack` per relayfile 0.6+, so
- * writes here are sandboxed and never leak to the user's main checkout.
- */
-export function configureGitForMount(mountDir: string, patterns: readonly string[]): void {
-  if (patterns.length === 0) return;
-  const infoDir = join(mountDir, '.git', 'info');
-  if (!existsSync(infoDir)) return;
-
-  appendFileSync(join(infoDir, 'exclude'), buildMountGitExcludeBlock(patterns));
-
-  // Use git's own gitignore matcher to pick which tracked files to flag,
-  // keeping semantics aligned with relayfile's (gitignore-style, basename-
-  // anywhere) filter. `--cached -i --exclude-from=<file>` (without
-  // `--exclude-standard`) lists only tracked files matched by the supplied
-  // patterns — not the repo's own .gitignore.
-  const tmpExcludes = join(infoDir, '.aw-skip-list');
-  try {
-    writeFileSync(tmpExcludes, patterns.join('\n') + '\n');
-    const ls = spawnSync(
-      'git',
-      ['ls-files', '-z', '--cached', '-i', `--exclude-from=${tmpExcludes}`],
-      { cwd: mountDir }
-    );
-    if (ls.status !== 0) return;
-    const files = ls.stdout.toString('utf8').split('\0').filter(Boolean);
-    if (files.length === 0) return;
-    // Chunk to stay well under typical argv-length limits on huge repos.
-    const CHUNK = 200;
-    for (let i = 0; i < files.length; i += CHUNK) {
-      spawnSync(
-        'git',
-        ['update-index', '--skip-worktree', '--', ...files.slice(i, i + CHUNK)],
-        { cwd: mountDir }
-      );
-    }
-  } finally {
-    try {
-      rmSync(tmpExcludes, { force: true });
-    } catch {
-      /* best-effort */
-    }
-  }
-}
-
-/**
- * Persona-supplied sidecar markdown materialized into a sandbox mount.
- * Pure data carrier — `runInteractive` translates it into the on-disk
- * write inside `onBeforeLaunch` (mount path) and warns/skips when the
- * harness has no mount (`--install-in-repo`).
- */
-export interface ResolvedSidecar {
-  /** Filename inside the mount: `CLAUDE.md` (claude) or `AGENTS.md` (opencode/codex/grok). */
-  mountFile: 'CLAUDE.md' | 'AGENTS.md';
-  /** Persona-author content. Already inlined for built-ins; read from disk for local. */
-  personaContent: string;
-  mode: SidecarMdMode;
-}
-
-/**
- * Resolve the sidecar for a given selection + harness, returning the
- * persona-author content the runtime should materialize into the mount.
- * Returns `{}` when no sidecar applies (no path/content set, or harness
- * doesn't support sidecar files at all). Read errors surface as a warning
- * string so the caller can drop the sidecar gracefully rather than
- * failing the whole session.
- */
-export function loadSidecarForSelection(
-  selection: PersonaSelection
-): { sidecar?: ResolvedSidecar; warning?: string } {
-  const harness = selection.harness;
-  if (
-    harness !== 'claude' &&
-    harness !== 'opencode' &&
-    harness !== 'codex' &&
-    harness !== 'grok'
-  ) {
-    return {};
-  }
-  if (harness === 'claude') {
-    if (selection.claudeMdContent) {
-      return {
-        sidecar: {
-          mountFile: 'CLAUDE.md',
-          personaContent: selection.claudeMdContent,
-          mode: selection.claudeMdMode ?? 'overwrite'
-        }
-      };
-    }
-    if (selection.claudeMd) {
-      try {
-        const content = readFileSync(selection.claudeMd, 'utf8');
-        return {
-          sidecar: {
-            mountFile: 'CLAUDE.md',
-            personaContent: content,
-            mode: selection.claudeMdMode ?? 'overwrite'
-          }
-        };
-      } catch (err) {
-        return { warning: `claudeMd: could not read ${selection.claudeMd}: ${(err as Error).message}` };
-      }
-    }
-    return {};
-  }
-  // opencode, codex, and grok all read AGENTS.md from cwd. The resolution
-  // rule is identical for these harnesses here.
-  if (selection.agentsMdContent) {
-    return {
-      sidecar: {
-        mountFile: 'AGENTS.md',
-        personaContent: selection.agentsMdContent,
-        mode: selection.agentsMdMode ?? 'overwrite'
-      }
-    };
-  }
-  if (selection.agentsMd) {
-    try {
-      const content = readFileSync(selection.agentsMd, 'utf8');
-      return {
-        sidecar: {
-          mountFile: 'AGENTS.md',
-          personaContent: content,
-          mode: selection.agentsMdMode ?? 'overwrite'
-        }
-      };
-    } catch (err) {
-      return { warning: `agentsMd: could not read ${selection.agentsMd}: ${(err as Error).message}` };
-    }
-  }
-  return {};
-}
-
-/**
- * Compute the bytes to write into the mount for a sidecar. In `extend`
- * mode, prepends the user's real-cwd file (if any) joined to the persona
- * content with `\n\n---\n\n`. Pure — exposed for unit tests.
- */
-export function buildSidecarBody(
-  sidecar: ResolvedSidecar,
-  realCwdDir: string
-): string {
-  if (sidecar.mode === 'extend') {
-    const realPath = join(realCwdDir, sidecar.mountFile);
-    try {
-      const realContent = readFileSync(realPath, 'utf8');
-      return `${realContent}\n\n---\n\n${sidecar.personaContent}`;
-    } catch (err) {
-      // Only "missing path" errors degrade to overwrite. Real I/O
-      // problems (EACCES, EISDIR, …) propagate so callers see them
-      // instead of silently dropping the user's CLAUDE.md/AGENTS.md.
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === 'ENOENT' || code === 'ENOTDIR') {
-        return sidecar.personaContent;
-      }
-      throw err;
-    }
-  }
-  return sidecar.personaContent;
-}
-
-/**
- * Decide whether to run the interactive session inside a
- * `@relayfile/local-mount` sandbox.
- *
- * All interactive harnesses default to the mount.
- * The mount hides CLAUDE.md / .claude / .mcp.json (claude) or the
- * skill-install patterns + AGENTS.md (codex / opencode / grok) so
- * persona-supplied sidecars and any per-session writes stay sandboxed and
- * don't leak into the user's real repo. `--install-in-repo` is the single
- * opt-out that disengages the mount across all harnesses.
- *
- * Pure — no side effects, trivially testable.
- */
-export function decideCleanMode(
-  harness: Harness,
-  installInRepo = false
-): { useClean: boolean } {
-  if (harness === 'claude' || harness === 'opencode' || harness === 'codex' || harness === 'grok') {
-    return { useClean: !installInRepo };
-  }
-  return { useClean: false };
-}
-
-export function formatSandboxMountReadyMessage(
-  mountDir: string,
-  handle: { initialMountDurationMs?: number; initialFileCount?: number }
-): string {
-  const mountStats =
-    handle.initialMountDurationMs !== undefined && handle.initialFileCount !== undefined
-      ? ` (${handle.initialMountDurationMs}ms, ${handle.initialFileCount} files)`
-      : '';
-  return `Sandbox mount ready${mountStats} → ${mountDir}`;
-}
-
-export function buildSpawnSummary(input: {
-  harness: Harness;
-  model: string;
-  spec: Pick<InteractiveSpec, 'initialPrompt' | 'mcpServers'>;
-  permissions?: PersonaSelection['permissions'];
-  useClean?: boolean;
-}): string[] {
-  const summary: string[] = [`model=${input.model}`];
-  if (input.harness === 'claude') {
-    const servers = Object.keys(input.spec.mcpServers ?? {});
-    summary.push(`mcp-strict=${servers.length ? servers.join(',') : '(none)'}`);
-  }
-  if (input.harness === 'claude') {
-    if (input.permissions?.allow?.length) {
-      summary.push(`allow=${input.permissions.allow.length} rule(s)`);
-    }
-    if (input.permissions?.deny?.length) {
-      summary.push(`deny=${input.permissions.deny.length} rule(s)`);
-    }
-  }
-  if (input.harness === 'claude') {
-    if (input.permissions?.mode) {
-      summary.push(`mode=${input.permissions.mode}`);
-    }
-  }
-  if (input.spec.initialPrompt) summary.push('initial-prompt=<systemPrompt>');
-  if (input.useClean) summary.push('mount=on');
-  return summary;
-}
-
-/**
- * Persona authoring dry-run. Used by persona authors to verify a persona
- * actually launches before it ships, without spawning the harness or
- * running the agent's tier model. Three checks, in order:
- *
- *   1. Sidecar resolution — `claudeMd` / `agentsMd` filename references
- *      that point at unreadable files would brick the launch silently
- *      today (lenient warning); dry-run promotes them to failures.
- *   2. Interactive spec build — runs `buildInteractiveSpec` on the
- *      resolved selection. Catches malformed `permissions` patterns,
- *      `mcpServers` shape errors, and missing required harness fields.
- *      Pure / no side effects.
- *   3. Skill install — runs each `skills[].source` through its real
- *      installer (`npx skills add` / `npx prpm install`) inside a fresh
- *      temp dir and reports per-skill pass/fail.
- *
- * Temp dir is deleted on success so dry-run leaves no trace; on a skill
- * failure it is left in place and its path printed so the author can
- * inspect the installer's output. Checks 1 and 2 run before any temp
- * dir is created so an early failure doesn't litter `/tmp`.
- */
-function runDryRun(selection: PersonaSelection): number {
-  const inputResolution = resolvePersonaInputs(
-    selection.inputs,
-    selection.inputValues,
-    process.env
-  );
-  const renderedSystemPrompt = renderPersonaInputs(
-    selection.systemPrompt,
-    inputResolution.values
-  );
-  const renderedClaudeContent =
-    selection.claudeMdContent !== undefined
-      ? renderPersonaInputs(selection.claudeMdContent, inputResolution.values)
-      : undefined;
-  const renderedAgentsContent =
-    selection.agentsMdContent !== undefined
-      ? renderPersonaInputs(selection.agentsMdContent, inputResolution.values)
-      : undefined;
-  const effectiveSelection: PersonaSelection = {
-    ...selection,
-    systemPrompt: renderedSystemPrompt,
-    ...(renderedClaudeContent !== undefined ? { claudeMdContent: renderedClaudeContent } : {}),
-    ...(renderedAgentsContent !== undefined ? { agentsMdContent: renderedAgentsContent } : {})
-  };
-  const { personaId, harness, model, harnessSettings, systemPrompt } = effectiveSelection;
-
-  process.stderr.write(
-    `→ ${personaId} via ${harness} (${model}) [DRY-RUN]\n`
-  );
-
-  // Check 1: sidecar resolution. A loadSidecarForSelection warning means
-  // the persona points `claudeMd` / `agentsMd` at a file we couldn't
-  // read; the launch path degrades to a warning today, which silently
-  // drops the persona's operating spec. In dry-run that's a failure.
-  const sidecarLookup = loadSidecarForSelection(effectiveSelection);
-  if (sidecarLookup.warning) {
-    process.stderr.write(`✗ sidecar: ${sidecarLookup.warning}\n`);
-    return 1;
-  }
-  process.stderr.write(
-    `✓ sidecar: ${sidecarLookup.sidecar ? sidecarLookup.sidecar.mountFile : '(none)'}\n`
-  );
-
-  // Check 2: persona-kit translation. buildInteractiveSpec validates
-  // permissions shape, mcpServers shape, and required runtime fields.
-  // We resolve env + mcp leniently (same as the live launch path) so
-  // the spec call sees the same inputs it would at runtime.
-  const callerEnv = { ...process.env, ...inputResolution.values };
-  const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
-  const mcpResolution = resolveMcpServersLenient(effectiveSelection.mcpServers, callerEnv);
-  emitDropWarnings(
-    formatDropWarnings(envResolution.dropped, mcpResolution.dropped, mcpResolution.droppedServers)
-  );
-  let spec: InteractiveSpec;
-  try {
-    const relayMcp = resolveRelayMcpFromEnv(process.env);
-    const aiMemory = resolveAiMemory(effectiveSelection.memory);
-    const aiHist = aiMemory.enabled
-      ? resolveAiHistConfig(process.env, aiMemory.dbPath)
-      : undefined;
-    spec = buildInteractiveSpec({
-      harness,
-      personaId,
-      model,
-      systemPrompt,
-      harnessSettings,
-      mcpServers: mcpResolution.servers,
-      ...(relayMcp ? { relayMcp } : {}),
-      ...(aiHist ? { aiHist } : {}),
-      permissions: effectiveSelection.permissions
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`✗ harness spec: ${msg}\n`);
-    return 1;
-  }
-  for (const w of spec.warnings) process.stderr.write(`warning: ${w}\n`);
-  process.stderr.write(`✓ harness spec: ${spec.bin} (${spec.args.length} args)\n`);
-
-  // Check 3: skill installs.
-  // Dry-run runs each install inside a fresh tempDir (see `cwd: tempDir` on
-  // the spawnSync below). Pass repoRoot=process.cwd() so `local`-kind skills
-  // resolve their relative source paths against the real repo, not the tmp.
-  const plan = materializeSkills(effectiveSelection.skills, harness, {
-    repoRoot: process.cwd()
-  });
-  if (plan.installs.length === 0) {
-    process.stderr.write('✓ skills: (none declared)\n');
-    process.stderr.write('✓ dry-run ok\n');
-    return 0;
-  }
-
-  const tempDir = mkdtempSync(join(tmpdir(), `agentworkforce-dryrun-${personaId}-`));
-  process.stderr.write(`• temp dir: ${tempDir}\n`);
-  process.stderr.write(`• installing ${plan.installs.length} skill(s)\n`);
-
-  const failures: { skillId: string; exitCode: number }[] = [];
-  for (const inst of plan.installs) {
-    const [bin, ...args] = inst.installCommand;
-    if (!bin) {
-      process.stderr.write(`  skipped ${inst.skillId}: empty install command\n`);
-      continue;
-    }
-    process.stderr.write(`• ${inst.skillId} (${inst.sourceKind}) → ${inst.packageRef}\n`);
-    const res = spawnSync(bin, args, { stdio: 'inherit', shell: false, cwd: tempDir });
-    const code = subprocessExitCode(res);
-    if (code === 0) {
-      process.stderr.write(`  ✓ ${inst.skillId}\n`);
-    } else {
-      process.stderr.write(`  ✗ ${inst.skillId} (exit ${code})\n`);
-      failures.push({ skillId: inst.skillId, exitCode: code });
-    }
-  }
-
-  if (failures.length === 0) {
-    try {
-      rmSync(tempDir, { recursive: true, force: true });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`warning: failed to clean up ${tempDir}: ${msg}\n`);
-    }
-    process.stderr.write(
-      `✓ dry-run ok: ${plan.installs.length} skill(s) installed cleanly\n`
-    );
-    return 0;
-  }
-
-  process.stderr.write(
-    `✗ dry-run failed: ${failures.length} of ${plan.installs.length} skill(s) failed\n`
-  );
-  process.stderr.write(`  inspect ${tempDir} for installer output\n`);
-  for (const f of failures) {
-    process.stderr.write(`  - ${f.skillId} (exit ${f.exitCode})\n`);
-  }
-  return failures[0]?.exitCode || 1;
-}
-
-/**
- * Optional out-parameter populated by `runInteractive` so the caller can
- * locate the just-ended session for follow-up tooling (e.g. the
- * persona-improver post-session prompt). Populated regardless of exit
- * status so failure paths are still inspectable.
- */
-interface RunInteractiveCapture {
-  /** Cwd the harness child saw — mount dir for sandboxed sessions, real cwd otherwise. */
-  sessionCwd?: string;
-  /** Harness binary that was spawned. */
-  harness?: Harness;
-  /** Wallclock (ms) right before the harness child was spawned. Used to filter newer transcript files. */
-  startedAt?: number;
-  /**
-   * Burn-stamp enrichment written by launch-metadata (`agentworkforce`,
-   * `persona`, `personaVersion`, `personaTier`, `personaSource`). Empty
-   * `{}` when launch-metadata is disabled (opt-out via env or backend
-   * doesn't support stamps). Lets the post-session lookup match the
-   * just-ended session to its harness sessionId via `exportStamps`.
-   */
-  stampEnrichment?: Record<string, string>;
-  /** Whether burn stamping was actually wired this run (false → exportStamps lookup is moot). */
-  stampingEnabled?: boolean;
-}
-
-async function runInteractive(
-  selection: PersonaSelection,
-  options: {
-    installInRepo?: boolean;
-    noLaunchMetadata?: boolean;
-    /** Bypass the persistent skill cache for this run (install fresh into a session dir). */
-    noSkillCache?: boolean;
-    /** Force reinstall into the cache dir, replacing any existing entry. */
-    refreshSkills?: boolean;
-    /** Force an upstream drift check this launch regardless of the TTL. */
-    checkUpstream?: boolean;
-    /** Skip the upstream drift check this launch regardless of the TTL. */
-    noCheckUpstream?: boolean;
-    personaSpec: PersonaSpec;
-    personaSource: PersonaSource;
-    capture?: RunInteractiveCapture;
-  }
-): Promise<number> {
-  const inputResolution = resolvePersonaInputs(
-    selection.inputs,
-    selection.inputValues,
-    process.env
-  );
-  const renderedSystemPrompt = renderPersonaInputs(
-    selection.systemPrompt,
-    inputResolution.values
-  );
-  // Render input placeholders ($TARGET_DIR, ${CREATE_MODE}, …) inside the
-  // sidecar Content fields too. Personas that move heavy authoring guidance
-  // out of the systemPrompt and into AGENTS.md / CLAUDE.md still want
-  // their declared inputs interpolated; without this the materialized
-  // sidecar would carry literal `$TARGET_DIR` strings.
-  const renderedClaudeContent =
-    selection.claudeMdContent !== undefined
-      ? renderPersonaInputs(selection.claudeMdContent, inputResolution.values)
-      : undefined;
-  const renderedAgentsContent =
-    selection.agentsMdContent !== undefined
-      ? renderPersonaInputs(selection.agentsMdContent, inputResolution.values)
-      : undefined;
-  const effectiveSelection: PersonaSelection = {
-    ...selection,
-    systemPrompt: renderedSystemPrompt,
-    ...(renderedClaudeContent !== undefined ? { claudeMdContent: renderedClaudeContent } : {}),
-    ...(renderedAgentsContent !== undefined ? { agentsMdContent: renderedAgentsContent } : {})
-  };
-  const { personaId, harness, model, harnessSettings, systemPrompt } = effectiveSelection;
-  // `installRoot` (out-of-repo skill staging via `--plugin-dir`) is currently
-  // claude-only; the workload-router SDK throws if it's set for other
-  // harnesses. For other harnesses, we instead keep installs out of the repo by
-  // running them inside a @relayfile/local-mount sandbox (see `useClean`
-  // below). The --install-in-repo flag forces legacy in-repo installs
-  // across the board.
-  const useClean = decideCleanMode(
-    harness,
-    options.installInRepo === true
-  ).useClean;
-  // Per-persona CLAUDE.md / AGENTS.md: load the author content if any. The
-  // file is materialized into the mount inside onBeforeLaunch. Without a
-  // mount (--install-in-repo) we skip-and-warn — writing into the real cwd
-  // would pollute the user's repo and is explicitly out of scope.
-  const sidecarLookup = loadSidecarForSelection(effectiveSelection);
-  if (sidecarLookup.warning) {
-    process.stderr.write(`warning: ${sidecarLookup.warning}\n`);
-  }
-  const resolvedSidecar = useClean ? sidecarLookup.sidecar : undefined;
-  if (sidecarLookup.sidecar && !useClean) {
-    process.stderr.write(
-      `warning: persona declares ${sidecarLookup.sidecar.mountFile} but no sandbox mount is available ` +
-        `(--install-in-repo disengages the mount); skipping sidecar materialization to avoid writing into your repo.\n`
-    );
-  }
-  // A session dir is needed whenever we either (a) stage skills out-of-repo
-  // via claude's installRoot, or (b) open a mount. Both engage by default;
-  // --install-in-repo disengages both.
-  const useSessionDir =
-    !options.installInRepo && (harness === 'claude' || useClean);
-  const sessionRoot = useSessionDir ? generateSessionRoot(personaId) : undefined;
-
-  // Persistent skill-install cache. Keyed by a content-addressed fingerprint
-  // of (harness, sorted skill sources, local file contents). On a hit we reuse
-  // the dir directly — for claude as `--plugin-dir`, for mount harnesses by
-  // mirroring its contents into the mount before launch. Disabled when the
-  // user opts into in-repo installs (the cache lives outside the repo, so
-  // mirroring it back would re-introduce the very leakage `--install-in-repo`
-  // is designed to surface to the user explicitly).
-  const skillCachingEnabled = !options.installInRepo && options.noSkillCache !== true;
-  const skillCacheFingerprint = skillCachingEnabled
-    ? computeSkillCacheFingerprint({
-        harness,
-        skills: effectiveSelection.skills,
-        repoRoot: process.cwd()
-      })
-    : undefined;
-  const skillCacheDir = skillCacheFingerprint
-    ? resolveSkillCacheDir(skillCacheFingerprint)
-    : undefined;
-  // Source-key hit: marker present and fingerprint matches. The upstream
-  // drift check below may still flip this to a miss.
-  const skillCacheSourceHit =
-    skillCacheDir !== undefined &&
-    skillCacheFingerprint !== undefined &&
-    !options.refreshSkills &&
-    isSkillCacheValid(skillCacheDir, skillCacheFingerprint);
-  // Mutable: a detected upstream drift downgrades the hit into a miss so the
-  // install path reruns and rebuilds the cache dir in place.
-  let skillCacheHit = skillCacheSourceHit;
-
-  // installRoot: for claude this is the dir passed to `--plugin-dir`. With
-  // caching enabled it points at the persistent cache; without, at the
-  // ephemeral session dir (pre-cache behavior). Other harnesses do not use
-  // claude's plugin-dir flag — for them the cache (if any) is mirrored into
-  // the mount in `onBeforeLaunch`, not surfaced as an installRoot.
-  const installRoot =
-    harness === 'claude' && !options.installInRepo
-      ? skillCacheDir ?? (sessionRoot ? sessionInstallRoot(sessionRoot) : undefined)
-      : undefined;
-  // `repoRoot` lets the local skill provider (kind: 'local') resolve
-  // relative source paths like `.agentworkforce/workforce/skills/foo.md` to
-  // absolute paths before the install command runs. Critical for claude's
-  // installRoot mode, where the install runs `cd <installRoot> && cp ...`
-  // and a relative source would otherwise resolve against the wrong dir.
-  const install = buildInstallContext(effectiveSelection, {
-    ...(installRoot !== undefined ? { installRoot } : {}),
-    repoRoot: process.cwd()
-  });
-  process.stderr.write(`→ ${personaId} via ${harness} (${model})\n`);
-
-  // Upstream drift check (opt-in, TTL-gated). Only meaningful on a
-  // source-key hit — a miss reinstalls anyway, and a refresh is
-  // unconditional. Resolve the interval: --check-upstream forces (0 = always
-  // this launch), --no-check-upstream disables (null = never), otherwise the
-  // env var, otherwise the 24h default.
-  if (skillCacheSourceHit && skillCacheDir && skillCacheFingerprint) {
-    const intervalMs = options.checkUpstream
-      ? 0
-      : options.noCheckUpstream
-        ? null
-        : resolveEnvCheckIntervalMs();
-    const marker = readSkillCacheMarker(skillCacheDir);
-    if (marker && isUpstreamCheckDue(marker, intervalMs)) {
-      const spinner = ora({
-        text: 'Checking skills for upstream updates…',
-        stream: process.stderr
-      }).start();
-      try {
-        const { drifted, details } = await detectSkillUpstreamDrift(marker);
-        const moved = details.filter((d) => d.drifted);
-        if (drifted) {
-          spinner.warn(
-            `Upstream changed for ${moved.length} skill(s): ${moved
-              .map((d) => `${d.skillId} (${d.note})`)
-              .join(', ')}`
-          );
-          skillCacheHit = false;
-        } else {
-          spinner.succeed(
-            `Skills up to date (${details.length} checked) — reusing cache`
-          );
-          // Record the clean check so we don't re-probe until the TTL lapses.
-          updateSkillCacheMarkerUpstream(skillCacheDir, {
-            lastUpstreamCheckAt: new Date().toISOString()
-          });
-        }
-      } catch (err) {
-        // Fail-open: a probe-layer crash must never block the launch.
-        spinner.warn(
-          `Upstream check failed (${(err as Error).message}); using cached skills`
-        );
-      }
-    }
-  }
-
-  if (skillCacheFingerprint && skillCacheDir) {
-    if (skillCacheHit) {
-      process.stderr.write(
-        `• skill cache hit (${skillCacheFingerprint.slice(0, 12)}) → reusing ${skillCacheDir}\n`
-      );
-    } else if (options.refreshSkills) {
-      process.stderr.write(
-        `• skill cache refresh requested (${skillCacheFingerprint.slice(0, 12)}) → reinstalling into ${skillCacheDir}\n`
-      );
-    } else if (skillCacheSourceHit) {
-      process.stderr.write(
-        `• skill cache stale (${skillCacheFingerprint.slice(0, 12)}) → upstream drift, reinstalling into ${skillCacheDir}\n`
-      );
-    } else {
-      process.stderr.write(
-        `• skill cache miss (${skillCacheFingerprint.slice(0, 12)}) → installing into ${skillCacheDir}\n`
-      );
-    }
-  }
-
-  const startLaunchMetadataForLaunch = (cwd = process.cwd()) =>
-    startLaunchMetadataRecording({
-      selection: effectiveSelection,
-      personaSpec: options.personaSpec,
-      personaSource: options.personaSource,
-      cwd,
-      noLaunchMetadata: options.noLaunchMetadata,
-      env: process.env,
-      // Launch metadata ingest runs in the background while the user is reading
-      // persona output; route its warnings to the CLI log file rather than the
-      // terminal so a transient backend hiccup doesn't surface as scary noise.
-      onWarn: (msg) => launchMetadataLog.warn(msg)
-    });
-
-  const inputEnv = inputResolution.values;
-  const callerEnv = { ...process.env, ...inputEnv };
-  const envResolution = resolveStringMapLenient(effectiveSelection.env, callerEnv, 'env');
-  const mcpResolution = resolveMcpServersLenient(effectiveSelection.mcpServers, callerEnv);
-  emitDropWarnings(
-    formatDropWarnings(envResolution.dropped, mcpResolution.dropped, mcpResolution.droppedServers)
-  );
-  const resolvedEnv =
-    Object.keys(inputEnv).length > 0 || envResolution.value
-      ? { ...(envResolution.value ?? {}), ...inputEnv }
-      : undefined;
-  const resolvedMcp = mcpResolution.servers;
-
-  // In session mode the install command is never `:` — it at minimum runs
-  // the plugin scaffold (mkdir + manifest + symlink) so `--plugin-dir` has a
-  // valid target even for skill-less local personas. Gate on the
-  // command string rather than `installs.length` so we don't skip that.
-  const skillIds = install.plan.installs.map((i) => i.skillId).join(', ');
-  const installLabel =
-    install.plan.installs.length === 0
-      ? `Staging session plugin dir${installRoot ? ` → ${installRoot}` : ''}`
-      : `Installing skills: ${skillIds}${installRoot ? ` → ${installRoot}` : ''}`;
-  // When useClean engages on a non-claude harness, the install must run
-  // INSIDE the mount so harness skill roots, prpm.lock, etc. land in the
-  // sandbox rather than the real repo. We defer it to `onBeforeLaunch`
-  // below instead of pre-running here.
-  const deferInstallToMount =
-    useClean && harness !== 'claude' && install.commandString !== ':';
-  if (
-    install.commandString !== ':' &&
-    !deferInstallToMount &&
-    !skillCacheHit
-  ) {
-    const cacheable = skillCachingEnabled && !!skillCacheDir && !!skillCacheFingerprint;
-    const lock =
-      cacheable && skillCacheDir ? await acquireSkillCacheLock(skillCacheDir) : null;
-    try {
-      // Re-check under the lock: a concurrent launch may have populated the
-      // cache while we waited. (Not on refresh — that's an explicit rebuild.)
-      const peerPopulated =
-        cacheable &&
-        !options.refreshSkills &&
-        skillCacheDir !== undefined &&
-        skillCacheFingerprint !== undefined &&
-        isSkillCacheValid(skillCacheDir, skillCacheFingerprint);
-      if (peerPopulated) {
-        process.stderr.write(
-          `• skill cache populated by a concurrent launch → reusing ${skillCacheDir}\n`
-        );
-      } else {
-        // `--refresh-skills`: wipe the entry first so the reinstall is a true
-        // rebuild — no stale files from a prior version, and a partial
-        // failure can't leave the old marker behind to fake a later hit.
-        // Done under the lock so a peer's in-progress install isn't clobbered.
-        if (options.refreshSkills && cacheable && skillCacheDir) {
-          rmSync(skillCacheDir, { recursive: true, force: true });
-        }
-        await runInstall(install.command, installLabel);
-        if (skillCacheFingerprint && skillCacheDir) {
-          await writeMarkerWithUpstream(
-            skillCacheDir,
-            skillCacheFingerprint,
-            harness,
-            effectiveSelection.skills.map((s) => ({ id: s.id, source: s.source }))
-          );
-        }
-      }
-    } finally {
-      lock?.release();
-    }
-  }
-
-  const relayMcp = resolveRelayMcpFromEnv(process.env);
-  const aiMemory = resolveAiMemory(effectiveSelection.memory);
-  const aiHist = aiMemory.enabled
-    ? resolveAiHistConfig(process.env, aiMemory.dbPath)
-    : undefined;
-  const brokerRelayHarness = relayMcp && (harness === 'claude' || harness === 'codex');
-  const specInput = {
-    harness,
-    personaId,
-    model,
-    systemPrompt,
-    harnessSettings,
-    mcpServers: resolvedMcp,
-    ...(aiHist ? { aiHist } : {}),
-    permissions: effectiveSelection.permissions,
-    ...(installRoot !== undefined ? { pluginDirs: [installRoot] } : {})
-  };
-  const spec = buildInteractiveSpec({
-    ...specInput,
-    ...(relayMcp && !brokerRelayHarness ? { relayMcp } : {})
-  });
-  for (const w of spec.warnings) process.stderr.write(`warning: ${w}\n`);
-  let spawnArgs = [...spec.args];
-
-  // Broker-aware relay MCP injection: prefer the broker binary's `mcp-args
-  // --register` subcommand (pre-mints RELAY_AGENT_TOKEN, sets
-  // RELAY_SKIP_BOOTSTRAP=1) over the legacy `@relaycast/mcp` self-registration
-  // path. Falls back to @relaycast/mcp when the broker binary is unavailable.
-  const cliRelayLog = (level: 'debug' | 'info' | 'warn' | 'error', message: string, attrs?: Record<string, unknown>) => {
-    if (level === 'warn' || level === 'error') {
-      process.stderr.write(`warning: ${message}${attrs ? ` ${JSON.stringify(attrs)}` : ''}\n`);
-    }
-  };
-  if (relayMcp && harness === 'claude') {
-    if (claudeMcpConfigHasRelayOverride(spawnArgs)) {
-      process.stderr.write('• relay: persona overrides relay MCP config\n');
-    } else {
-      const brokerMcpArgs = await resolveAgentRelayBrokerMcpArgs({
-        cli: 'claude',
-        env: process.env,
-        relayMcp,
-        cwd: process.cwd(),
-        existingArgs: [],
-        log: cliRelayLog
-      });
-      const mergedArgs = brokerMcpArgs
-        ? injectClaudeAgentRelayMcpConfig(spawnArgs, brokerMcpArgs, cliRelayLog)
-        : undefined;
-      if (mergedArgs) {
-        spawnArgs = mergedArgs;
-        process.stderr.write('• relay: agent-relay (broker pre-registered)\n');
-      } else {
-        const fallbackSpec = buildInteractiveSpec({ ...specInput, relayMcp });
-        spawnArgs = [...fallbackSpec.args];
-        process.stderr.write('• relay: @relaycast/mcp (fallback)\n');
-      }
-    }
-  } else if (relayMcp && harness === 'codex') {
-    const brokerMcpArgs = await resolveAgentRelayBrokerMcpArgs({
-      cli: 'codex',
-      env: process.env,
-      relayMcp,
-      cwd: process.cwd(),
-      existingArgs: codexExistingArgs(spawnArgs),
-      log: cliRelayLog
-    });
-    if (brokerMcpArgs) {
-      spawnArgs = injectCodexSubcommandArgs(spawnArgs, brokerMcpArgs);
-      process.stderr.write('• relay: agent-relay (broker pre-registered)\n');
-    } else {
-      const fallbackSpec = buildInteractiveSpec({ ...specInput, relayMcp });
-      spawnArgs = [...fallbackSpec.args];
-      process.stderr.write('• relay: @relaycast/mcp (fallback)\n');
-    }
-  }
-
-  // Config-file materialization strategy:
-  //  - Mount path (default): write each configFile into the
-  //    mount dir via onBeforeLaunch, so it lives only in the sandbox and is
-  //    torn down with the session.
-  //  - Non-mount path: today the only configFile producer is opencode
-  //    (opencode.json for the --agent wiring), and the non-mount opencode
-  //    path only engages under --install-in-repo. Writing opencode.json
-  //    into the user's real repo would pollute the working tree, so we
-  //    degrade: drop --agent from the argv, warn, and launch opencode with
-  //    its default agent. The persona's prompt will not be applied in that
-  //    mode; users who want it should drop --install-in-repo (the mount
-  //    default handles this cleanly).
-  const hasConfigFiles = spec.configFiles.length > 0;
-  const degradeConfigFiles = hasConfigFiles && !useClean;
-  let effectiveArgs: readonly string[] = spawnArgs;
-  if (degradeConfigFiles) {
-    process.stderr.write(
-      'warning: --install-in-repo cannot safely materialize the persona agent config (would write opencode.json into your repo); launching without --agent. Drop --install-in-repo to apply the persona prompt.\n'
-    );
-    effectiveArgs = stripAgentFlag(spawnArgs);
-  }
-  const finalArgs = spec.initialPrompt ? [...effectiveArgs, spec.initialPrompt] : [...effectiveArgs];
-
-  // Print a sanitized summary rather than raw argv: spec.args for the claude
-  // harness contains the resolved --mcp-config JSON and the full system
-  // prompt, either of which can carry secrets (Bearer tokens, API keys) once
-  // env refs are interpolated. We show the bin, model, and the *names* of
-  // the servers / permission fields so the user can verify the shape without
-  // leaking credentials to stderr or CI logs.
-  const summary = buildSpawnSummary({
-    harness,
-    model,
-    spec,
-    permissions: effectiveSelection.permissions,
-    useClean
-  });
-  process.stderr.write(`• spawning ${spec.bin} (${summary.join(', ')})\n`);
-
-  // Mount branch: delegate process lifecycle (spawn, signal forwarding,
-  // syncback, cleanup) to @relayfile/local-mount.
-  //
-  // For interactive harnesses: mount engages by default (unless
-  // `--install-in-repo`). For claude this hides CLAUDE.md / .claude /
-  // .mcp.json; for non-claude harnesses it routes `npx prpm install` /
-  // `npx skills add` writes into the sandbox (skill plugin dir for claude
-  // lives outside the mount at an absolute path, so claude still resolves
-  // `--plugin-dir` normally).
-  //
-  // The install itself runs inside the mount via `onBeforeLaunch` so that
-  // `npx prpm install` / `npx skills add` writes land in the sandbox. The
-  // skill-install paths are added to `ignoredPatterns` so they are neither
-  // copied in from the real repo nor synced back on exit.
-  if (useClean && sessionRoot) {
-    const mountDir = sessionMountDir(sessionRoot);
-    let launchMetadata: LaunchMetadataRun | undefined;
-    // Anything we materialize into the mount via onBeforeLaunch must be
-    // hidden from the mount-mirror in both directions: without this, any
-    // opencode.json already present in the real repo would be copied into
-    // the mount (masking the per-session agent config we write), and the
-    // fresh write from onBeforeLaunch would sync back out on exit and
-    // pollute the user's working tree. Added dynamically so this stays
-    // generic for any future configFile producer.
-    const { ignoredPatterns, readonlyPatterns } = buildRelayfileMountPatterns({
-      projectDir: process.cwd(),
-      personaId,
-      harness,
-      mount: effectiveSelection.mount,
-      configFilePaths: spec.configFiles.map((file) => file.path)
-    });
-    // 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 | undefined = 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 — 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: Ora | undefined;
-    let isSyncing = false;
-    let childSpawned = false;
-    let abortPresses = 0;
-    const sigintHandler = () => {
-      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) {
-          syncSpinner.text =
-            'Aborting sync — partial changes will be propagated. (Ctrl-C again to force quit)';
-        }
-        shutdownController.abort();
-        return;
-      }
-      if (syncSpinner) {
-        syncSpinner.fail('Force-quit: mount teardown skipped. Session dir may be left behind.');
-        syncSpinner = undefined;
-      } else {
-        process.stderr.write(
-          '\n✗ Force-quit: mount teardown skipped. Session dir may be left behind.\n'
-        );
-      }
-      try {
-        rmSync(sessionRoot, { recursive: true, force: true });
-      } catch {
-        /* swallow — we're exiting anyway */
-      }
-      process.exit(130);
-    };
-    process.on('SIGINT', sigintHandler);
-
-    let handle: Awaited<ReturnType<typeof createMount>> | undefined;
-    let autoSync: AutoSyncHandle | undefined;
-    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) {
-        // Cache-aware mount install:
-        //   - If we have a cache hit, skip the install and just mirror the
-        //     pre-populated cache dir into the mount. `npx prpm install`
-        //     never runs and no install spinner is needed.
-        //   - On miss (or `--refresh-skills`), run the install once with
-        //     cwd set to the cache dir so artifacts land in the persistent
-        //     location, then mirror into the mount and write the marker.
-        //   - With caching disabled (`--install-in-repo` or
-        //     `--no-skill-cache`), fall back to the legacy in-mount install.
-        //
-        // The setup spinner is only stopped around branches that print their
-        // own spinner (install) so the two don't fight for the same stream.
-        // The pure cache-hit path is a near-instant cpSync — leaving the
-        // setup spinner running avoids a redundant "Setting up sandbox
-        // mount…" redraw in the user-visible output.
-        if (skillCacheHit && skillCacheDir) {
-          mirrorSkillCacheInto(skillCacheDir, handle.mountDir);
-        } else if (skillCachingEnabled && skillCacheDir && skillCacheFingerprint) {
-          const lock = await acquireSkillCacheLock(skillCacheDir);
-          try {
-            // A concurrent launch may have populated the cache while we
-            // waited for the lock — mirror it instead of reinstalling.
-            // (Skipped on refresh, which is an explicit rebuild.)
-            if (
-              !options.refreshSkills &&
-              isSkillCacheValid(skillCacheDir, skillCacheFingerprint)
-            ) {
-              mirrorSkillCacheInto(skillCacheDir, handle.mountDir);
-            } else {
-              setupSpinner?.stop();
-              // `--refresh-skills`: wipe first so the reinstall is a true
-              // rebuild and a partial failure can't leave a stale marker.
-              if (options.refreshSkills) {
-                rmSync(skillCacheDir, { recursive: true, force: true });
-              }
-              mkdirSync(skillCacheDir, { recursive: true });
-              await runInstallOrThrow(install.command, installLabel, skillCacheDir);
-              await writeMarkerWithUpstream(
-                skillCacheDir,
-                skillCacheFingerprint,
-                harness,
-                effectiveSelection.skills.map((s) => ({ id: s.id, source: s.source }))
-              );
-              mirrorSkillCacheInto(skillCacheDir, handle.mountDir);
-              setupSpinner?.start();
-            }
-          } finally {
-            lock?.release();
-          }
-        } else {
-          setupSpinner?.stop();
-          await runInstallOrThrow(install.command, installLabel, handle.mountDir);
-          setupSpinner?.start();
-        }
-      }
-      for (const file of spec.configFiles) {
-        assertSafeRelativePath(file.path);
-        const target = join(handle.mountDir, file.path);
-        mkdirSync(dirname(target), { recursive: true });
-        writeFileSync(target, file.contents, 'utf8');
-      }
-      if (resolvedSidecar) {
-        const body = buildSidecarBody(resolvedSidecar, process.cwd());
-        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(formatSandboxMountReadyMessage(mountDir, handle));
-      setupSpinner = undefined;
-
-      const childEnv = resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env;
-      const childCwd = handle.mountDir;
-      if (options.capture) {
-        options.capture.sessionCwd = childCwd;
-        options.capture.harness = 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<number>((resolve, reject) => {
-        const child = spawn(spec.bin, finalArgs, {
-          cwd: childCwd,
-          stdio: 'inherit',
-          env: childEnv
-        });
-        child.on('error', reject);
-        child.on('close', (code, signal) => {
-          if (typeof code === 'number') resolve(code);
-          else if (signal) resolve(signalExitCode(signal));
-          else resolve(1);
-        });
-      });
-
-      // Child exited — start the spinner immediately so the sync-back is
-      // visibly live rather than a silent pause.
-      isSyncing = true;
-      syncSpinner = ora({
-        text: 'Syncing session changes back to the repo… (Ctrl-C to skip)',
-        stream: process.stderr
-      }).start();
-
-      let count = 0;
-      if (autoSync) {
-        await autoSync.stop({ signal: shutdownController.signal });
-        count += autoSync.totalChanges();
-        autoSync = undefined;
-      }
-      // NOTE: `count` is bidirectional — it sums autosync activity in both
-      // directions (inbound project→mount and outbound mount→project,
-      // including deletes) plus the final mount→project syncBack. Phrase as
-      // "file events during session" so we don't overclaim direction.
-      count += await handle.syncBack({ signal: shutdownController.signal });
-
-      const aborted = shutdownController.signal.aborted;
-      const qualifier = aborted ? ' (partial)' : '';
-      const message =
-        count > 0
-          ? `Session complete — ${count} file event${count === 1 ? '' : 's'} during session${qualifier}.`
-          : 'Session complete — no file events.';
-      syncSpinner.succeed(message);
-      syncSpinner = undefined;
-      return exitCode;
-    } catch (err) {
-      if (setupSpinner) {
-        setupSpinner.fail('Sandbox mount setup failed');
-        setupSpinner = undefined;
-      }
-      if (syncSpinner) {
-        syncSpinner.fail('Sync did not complete');
-        syncSpinner = undefined;
-      }
-      // InstallCommandError carries the real install exit code — surfacing
-      // it (rather than collapsing onto 127) lets callers distinguish a
-      // failed `npx prpm install` from a missing harness binary. The message
-      // itself was already shown via spinner.fail inside runInstallWithSpinner,
-      // so we just return the code here.
-      if (err instanceof InstallCommandError) {
-        return err.exitCode;
-      }
-      const e = err as NodeJS.ErrnoException;
-      if (e.code === 'ENOENT') {
-        process.stderr.write(
-          `Failed to spawn "${spec.bin}" inside sandbox mount: binary not found on PATH. Install the ${harness} CLI and retry.\n`
-        );
-        return 127;
-      }
-      process.stderr.write(`Failed to launch sandbox mount: ${e.message}\n`);
-      return 1;
-    } finally {
-      if (setupSpinner) {
-        setupSpinner.stop();
-        setupSpinner = undefined;
-      }
-      if (syncSpinner) {
-        syncSpinner.stop();
-        syncSpinner = undefined;
-      }
-      // Best-effort: stop autosync if we errored out before the success path
-      // already cleared it.
-      if (autoSync) {
-        try {
-          await autoSync.stop({ signal: shutdownController.signal });
-        } catch {
-          /* ignore — we're tearing down anyway */
-        }
-      }
-      handle?.cleanup();
-      await launchMetadata?.stop();
-      process.removeListener('SIGINT', sigintHandler);
-      // When the install ran inside the mount, its cleanup paths are
-      // mount-relative (e.g. `.skills/<name>`, `skills/<name>`) and running
-      // cleanup here would resolve them against the real repo cwd —
-      // potentially `rm -rf`ing pre-existing user content. The mount dir is
-      // removed wholesale by `removeSessionRoot` below, so the install's
-      // cleanup is redundant anyway in that case.
-      //
-      // Skill caching also suppresses the cleanup: the cache dir IS the
-      // persistence layer, so the rm command (which targets the
-      // sessionInstallRoot — now pointing at the cache dir for claude) would
-      // wipe the very thing we want to keep across launches.
-      if (!deferInstallToMount && !skillCachingEnabled) {
-        runCleanup(install.cleanupCommand, install.cleanupCommandString);
-      }
-      removeSessionRoot(sessionRoot);
-    }
-  }
-
-  const launchMetadata = await startLaunchMetadataForLaunch();
-  if (options.capture) {
-    options.capture.sessionCwd = process.cwd();
-    options.capture.harness = 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: number) => {
-      if (settled) return;
-      settled = true;
-      // Skill caching takes ownership of the install dir; running cleanup
-      // here would `rm -rf` the persistent cache. Skip in that case and
-      // rely on the cache marker as the source of truth for "valid install".
-      if (!skillCachingEnabled) {
-        runCleanup(install.cleanupCommand, install.cleanupCommandString);
-      }
-      removeSessionRoot(sessionRoot);
-      void launchMetadata.stop().finally(() => resolve(code));
-    };
-
-    const child = spawn(spec.bin, finalArgs, {
-      stdio: 'inherit',
-      env: resolvedEnv ? { ...process.env, ...resolvedEnv } : process.env
-    });
-
-    const forward = (signal: NodeJS.Signals) => {
-      if (!child.killed) child.kill(signal);
-    };
-    process.on('SIGINT', () => forward('SIGINT'));
-    process.on('SIGTERM', () => forward('SIGTERM'));
-
-    child.on('exit', (code, signal) => {
-      finish(code ?? signalExitCode(signal));
-    });
-    child.on('error', (err: NodeJS.ErrnoException) => {
-      if (err.code === 'ENOENT') {
-        process.stderr.write(
-          `Failed to spawn "${spec.bin}": binary not found on PATH. Install the ${harness} CLI and retry.\n`
-        );
-      } else {
-        process.stderr.write(`Failed to spawn "${spec.bin}": ${err.message}\n`);
-      }
-      finish(127);
-    });
-  });
-}
-
-function formatAvailabilityTable(results: readonly HarnessAvailability[]): string {
-  const rows = results.map((r) => ({
-    harness: r.harness,
-    status: r.available ? 'ok' : 'missing',
-    version: r.available ? (r.version ?? '') : '',
-    detail: r.available ? (r.path ?? '') : (r.error ?? '')
-  }));
-  const headers = { harness: 'HARNESS', status: 'STATUS', version: 'VERSION', detail: 'DETAIL' };
-  const cols = ['harness', 'status', 'version', 'detail'] as const;
-  const widths = Object.fromEntries(
-    cols.map((c) => [c, Math.max(headers[c].length, ...rows.map((r) => r[c].length))])
-  ) as Record<(typeof cols)[number], number>;
-  const line = (row: Record<(typeof cols)[number], string>) =>
-    cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
-  return [line(headers), ...rows.map(line)].join('\n') + '\n';
-}
-
-interface SourceDirRow {
-  cascade: string;
-  config: string;
-  source: string;
-  exists: string;
-  dir: string;
-}
-
-function collectSourceDirRows(): {
-  configPath: string;
-  personaDirs: string[];
-  defaultCreateTarget?: string;
-  rows: SourceDirRow[];
-} {
-  const { directories, config } = buildPersonaSourceDirectories();
-  const rows: SourceDirRow[] = directories.map((sourceDir, idx) => ({
-    cascade: String(idx + 1),
-    config: sourceDir.configurable ? String(config.personaDirs.indexOf(sourceDir.dir) + 1) : '-',
-    source: sourceDir.source,
-    exists: existsSync(sourceDir.dir) ? 'yes' : 'no',
-    dir: sourceDir.dir
-  }));
-  rows.push({
-    cascade: String(rows.length + 1),
-    config: '-',
-    source: 'library',
-    exists: 'yes',
-    dir: '(built-in)'
-  });
-  return {
-    configPath: config.configPath,
-    personaDirs: config.personaDirs,
-    ...(config.defaultCreateTarget ? { defaultCreateTarget: config.defaultCreateTarget } : {}),
-    rows
-  };
-}
-
-function formatSourcesTable(
-  rows: readonly SourceDirRow[],
-  configPath: string,
-  defaultCreateTarget: string | undefined
-): string {
-  const headers: SourceDirRow = {
-    cascade: 'CASCADE',
-    config: 'CONFIG',
-    source: 'SOURCE',
-    exists: 'EXISTS',
-    dir: 'DIR'
-  };
-  const cols = ['cascade', 'config', 'source', 'exists', 'dir'] as const;
-  // Display label only — the underlying `source` literal flows through to
-  // --json so tooling that pins on `'cwd'` / `'user'` / `'library'` is fine.
-  const display: readonly SourceDirRow[] = rows.map((r) => ({
-    ...r,
-    source: formatPersonaSourceLabel(r.source)
-  }));
-  const widths = Object.fromEntries(
-    cols.map((c) => [c, Math.max(headers[c].length, ...display.map((r) => r[c].length))])
-  ) as Record<(typeof cols)[number], number>;
-  const line = (row: SourceDirRow) =>
-    cols.map((c) => row[c].padEnd(widths[c])).join('  ').trimEnd();
-  return [
-    `Config: ${configPath}`,
-    `Default create target: ${defaultCreateTarget ?? '(auto)'}`,
-    [line(headers), ...display.map(line)].join('\n'),
-    ''
-  ].join('\n');
-}
-
-function parseSourcesListArgs(args: readonly string[]): { json: boolean } {
-  let json = false;
-  for (const arg of args) {
-    if (arg === '--json') {
-      json = true;
-    } else if (arg === '-h' || arg === '--help') {
-      process.stdout.write('Usage: agentworkforce sources list [--json]\n');
-      process.exit(0);
-    } else {
-      die(`sources list: unexpected argument "${arg}".`);
-    }
-  }
-  return { json };
-}
-
-function runSourcesList(args: readonly string[]): never {
-  const { json } = parseSourcesListArgs(args);
-  const { configPath, personaDirs, defaultCreateTarget, rows } = collectSourceDirRows();
-  if (json) {
-    process.stdout.write(
-      JSON.stringify({ configPath, personaDirs, defaultCreateTarget, sources: rows }, null, 2) + '\n'
-    );
-  } else {
-    process.stdout.write(formatSourcesTable(rows, configPath, defaultCreateTarget));
-  }
-  process.exit(0);
-}
-
-function assertDirectoryForAdd(dir: string): void {
-  try {
-    if (!existsSync(dir)) {
-      die(`sources add: directory does not exist: ${dir}`);
-    }
-    if (!statSync(dir).isDirectory()) {
-      die(`sources add: path is not a directory: ${dir}`);
-    }
-  } catch (err) {
-    if ((err as Error).message.startsWith('sources add:')) throw err;
-    die(`sources add: could not inspect ${dir}: ${(err as Error).message}`);
-  }
-}
-
-function parseSourcesAddArgs(args: readonly string[]): { dir: string; position?: number } {
-  let dir: string | undefined;
-  let position: number | undefined;
-  const valueOf = (i: number, flag: string): string => {
-    const v = args[i + 1];
-    if (v === undefined || v.startsWith('--')) {
-      die(`sources add: ${flag} requires a value.`);
-    }
-    return v;
-  };
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '-h' || arg === '--help') {
-      process.stdout.write('Usage: agentworkforce sources add <dir> [--position <n>]\n');
-      process.exit(0);
-    } else if (arg === '--position') {
-      const raw = valueOf(i++, arg);
-      const parsed = Number(raw);
-      if (!Number.isInteger(parsed) || parsed < 1) {
-        die(`sources add: --position must be a positive integer.`);
-      }
-      position = parsed;
-    } else if (arg.startsWith('--')) {
-      die(`sources add: unexpected flag "${arg}".`);
-    } else if (dir === undefined) {
-      dir = arg;
-    } else {
-      die(`sources add: unexpected argument "${arg}".`);
-    }
-  }
-  if (!dir) die('sources add: missing directory.');
-  return { dir, position };
-}
-
-function runSourcesAdd(args: readonly string[]): never {
-  const { dir: rawDir, position } = parseSourcesAddArgs(args);
-  const dir = normalizePersonaDir(rawDir);
-  assertDirectoryForAdd(dir);
-
-  const config = loadPersonaSourceConfig();
-  if (config.personaDirs.includes(dir)) {
-    die(`sources add: directory is already configured: ${dir}`);
-  }
-  const insertAt = position === undefined ? config.personaDirs.length : position - 1;
-  if (insertAt < 0 || insertAt > config.personaDirs.length) {
-    die(
-      `sources add: --position must be between 1 and ${config.personaDirs.length + 1}.`
-    );
-  }
-  const nextDirs = [...config.personaDirs];
-  nextDirs.splice(insertAt, 0, dir);
-  const saved = savePersonaSourceConfig(nextDirs);
-  process.stdout.write(
-    `Added persona source directory at configurable position ${insertAt + 1}: ${dir}\nConfig: ${saved.configPath}\n`
-  );
-  process.exit(0);
-}
-
-function parseSourcesRemoveArgs(args: readonly string[]): { target: string } {
-  let target: string | undefined;
-  for (const arg of args) {
-    if (arg === '-h' || arg === '--help') {
-      process.stdout.write('Usage: agentworkforce sources remove <dir|config-position>\n');
-      process.exit(0);
-    } else if (arg.startsWith('--')) {
-      die(`sources remove: unexpected flag "${arg}".`);
-    } else if (target === undefined) {
-      target = arg;
-    } else {
-      die(`sources remove: unexpected argument "${arg}".`);
-    }
-  }
-  if (!target) die('sources remove: missing directory or config-position.');
-  return { target };
-}
-
-function runSourcesRemove(args: readonly string[]): never {
-  const { target } = parseSourcesRemoveArgs(args);
-  const config = loadPersonaSourceConfig();
-  let idx: number;
-  if (/^[1-9]\d*$/.test(target)) {
-    idx = Number(target) - 1;
-  } else {
-    const dir = normalizePersonaDir(target);
-    idx = config.personaDirs.indexOf(dir);
-  }
-  if (idx < 0 || idx >= config.personaDirs.length) {
-    die(`sources remove: no configurable persona source matched "${target}".`);
-  }
-  const nextDirs = [...config.personaDirs];
-  const [removed] = nextDirs.splice(idx, 1);
-  const saved = savePersonaSourceConfig(nextDirs);
-  process.stdout.write(
-    `Removed persona source directory from configurable position ${idx + 1}: ${removed}\nConfig: ${saved.configPath}\n`
-  );
-  process.exit(0);
-}
-
-function runSources(args: readonly string[]): never {
-  const [action, ...rest] = args;
-  if (!action || action === '-h' || action === '--help') {
-    process.stdout.write(
-      'Usage: agentworkforce sources <list|add|remove> [args...]\n' +
-        '  agentworkforce sources list [--json]\n' +
-        '  agentworkforce sources add <dir> [--position <n>]\n' +
-        '  agentworkforce sources remove <dir|config-position>\n'
-    );
-    process.exit(action ? 0 : 1);
-  }
-  if (action === 'list') runSourcesList(rest);
-  if (action === 'add') runSourcesAdd(rest);
-  if (action === 'remove') runSourcesRemove(rest);
-  die(`sources: unknown action "${action}". Expected: list, add, remove.`);
-}
-
-export interface PersonaInstallArgs {
-  source: string;
-  personaIds: string[];
-  overwrite: boolean;
-}
-
-export function parseInstallArgs(args: readonly string[]): PersonaInstallArgs {
-  let source: string | undefined;
-  const personaIds: string[] = [];
-  let overwrite = false;
-  const valueOf = (i: number, flag: string): string => {
-    const v = args[i + 1];
-    if (v === undefined || v.startsWith('--')) {
-      throw new Error(`install: ${flag} requires a value.`);
-    }
-    return v;
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--overwrite') {
-      overwrite = true;
-    } else if (arg === '--persona') {
-      const value = valueOf(i++, arg);
-      if (!value.trim()) throw new Error('install: --persona requires a non-empty value.');
-      personaIds.push(value);
-    } else if (arg.startsWith('--')) {
-      throw new Error(`install: unexpected flag "${arg}".`);
-    } else if (source === undefined) {
-      source = arg;
-    } else {
-      throw new Error(`install: unexpected argument "${arg}".`);
-    }
-  }
-
-  if (!source) throw new Error('install: missing package or local path.');
-  return { source, personaIds, overwrite };
-}
-
-function formatPersonaInstallSummary(result: PersonaInstallResult): string {
-  const lines: string[] = [];
-  for (const persona of result.installed) {
-    lines.push(`installed ${persona.id} -> ${persona.targetPath}`);
-  }
-  if (result.installed.length > 0) {
-    lines.push(
-      `Installed ${result.installed.length} persona(s) into ${result.targetDir}.`
-    );
-  }
-  return lines.length > 0 ? lines.join('\n') + '\n' : '';
-}
-
-function formatPersonaInstallConflicts(result: PersonaInstallResult): string {
-  if (result.conflicts.length === 0) return '';
-  const lines = result.conflicts.map(
-    (conflict) =>
-      `conflict ${conflict.id}: ${conflict.targetPath} already exists (use --overwrite to replace it)`
-  );
-  lines.push(
-    `Skipped ${result.conflicts.length} existing persona file(s); re-run with --overwrite to replace.`
-  );
-  return lines.join('\n') + '\n';
-}
-
-function runPersonaInstall(args: readonly string[]): never {
-  if (args.includes('-h') || args.includes('--help')) {
-    process.stdout.write(
-      'Usage: agentworkforce install <pkg|path> [--persona <id> ...] [--overwrite]\n'
-    );
-    process.exit(0);
-  }
-  let parsed: PersonaInstallArgs;
-  try {
-    parsed = parseInstallArgs(args);
-  } catch (err) {
-    die((err as Error).message);
-  }
-
-  let result: PersonaInstallResult;
-  try {
-    result = installPersonas({
-      source: parsed.source,
-      personaIds: parsed.personaIds,
-      overwrite: parsed.overwrite
-    });
-  } catch (err) {
-    die((err as Error).message, false);
-  }
-
-  process.stdout.write(formatPersonaInstallSummary(result));
-  process.stderr.write(formatPersonaInstallConflicts(result));
-  process.exit(result.conflicts.length > 0 ? 1 : 0);
-}
-
-interface PersonaListRow {
-  persona: string;
-  source: PersonaSource;
-  harness: string;
-  model: string;
-  intent: string;
-  tags: readonly PersonaTag[];
-  description: string;
-}
-
-function collectPersonaRows(): PersonaListRow[] {
-  const rows: PersonaListRow[] = [];
-  const pushSpec = (spec: PersonaSpec, source: PersonaSource): void => {
-    rows.push({
-      persona: spec.id,
-      source,
-      harness: spec.harness ?? '—',
-      model: spec.model ?? '—',
-      intent: spec.intent,
-      tags: spec.tags ?? [],
-      description: spec.description
-    });
-  };
-  const seen = new Set<string>();
-  for (const [id, spec] of local.byId) {
-    pushSpec(spec, local.sources.get(id) ?? 'library');
-    seen.add(id);
-  }
-  for (const spec of listBuiltInPersonas()) {
-    if (seen.has(spec.id)) continue;
-    pushSpec(spec, 'library');
-  }
-  return rows.sort((a, b) => a.persona.localeCompare(b.persona));
-}
-
-interface ListDisplayOptions {
-  description: boolean;
-}
-
-function formatPersonaTable(
-  rows: readonly PersonaListRow[],
-  display: ListDisplayOptions
-): string {
-  interface RenderRow {
-    persona: string;
-    source: string;
-    harness: string;
-    model: string;
-    tags: string;
-    description: string;
-  }
-  const headers: RenderRow = {
-    persona: 'PERSONA',
-    source: 'SOURCE',
-    harness: 'HARNESS',
-    model: 'MODEL',
-    tags: 'TAGS',
-    description: 'DESCRIPTION'
-  };
-  const rendered: RenderRow[] = rows.map((r) => ({
-    persona: r.persona,
-    source: formatPersonaSourceLabel(r.source),
-    harness: r.harness,
-    model: r.model,
-    tags: r.tags.join(','),
-    description: r.description
-  }));
-  const widths = {
-    persona: Math.max(headers.persona.length, ...rendered.map((r) => r.persona.length)),
-    source: Math.max(headers.source.length, ...rendered.map((r) => r.source.length)),
-    harness: Math.max(headers.harness.length, ...rendered.map((r) => r.harness.length)),
-    model: Math.max(headers.model.length, ...rendered.map((r) => r.model.length)),
-    tags: Math.max(headers.tags.length, ...rendered.map((r) => r.tags.length)),
-    description: headers.description.length
-  };
-  const termWidth =
-    process.stdout.isTTY && typeof process.stdout.columns === 'number' ? process.stdout.columns : 140;
-  const fixed =
-    widths.persona +
-    widths.source +
-    widths.harness +
-    widths.model +
-    widths.tags +
-    (5 + (display.description ? 1 : 0) - 1) * 2;
-  const descBudget = Math.max(20, termWidth - fixed - 1);
-  const truncate = (s: string, n: number) => (s.length <= n ? s : s.slice(0, Math.max(1, n - 1)) + '…');
-  const line = (row: RenderRow) => {
-    const parts = [
-      row.persona.padEnd(widths.persona),
-      row.source.padEnd(widths.source),
-      row.harness.padEnd(widths.harness),
-      row.model.padEnd(widths.model),
-      row.tags.padEnd(widths.tags)
-    ];
-    if (display.description) {
-      parts.push(truncate(row.description.replace(/\s+/g, ' ').trim(), descBudget));
-    }
-    return parts.join('  ').trimEnd();
-  };
-  return [line(headers), ...rendered.map(line)].join('\n') + '\n';
-}
-
-function parseListArgs(args: readonly string[]): {
-  json: boolean;
-  filterHarness?: Harness;
-  filterTag?: PersonaTag;
-  display: ListDisplayOptions;
-  deployments: boolean;
-} {
-  let json = false;
-  let filterHarness: Harness | undefined;
-  let filterTag: PersonaTag | undefined;
-  const display: ListDisplayOptions = { description: true };
-  let deployments = false;
-
-  const valueOf = (i: number, flag: string): string => {
-    const v = args[i + 1];
-    if (v === undefined || v.startsWith('--')) {
-      die(`list: ${flag} requires a value.`);
-    }
-    return v;
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--json') {
-      json = true;
-    } else if (arg === '--deployments') {
-      deployments = true;
-    } else if (arg === '-h' || arg === '--help') {
-      process.stdout.write(
-        'Usage: agentworkforce list [--deployments] [--status <status>] [--persona <slug>] [--json] [--filter-harness <harness>] [--filter-tag <tag>] [--no-display-description]\n'
-      );
-      process.exit(0);
-    } else if (arg === '--filter-harness') {
-      const v = valueOf(i++, arg);
-      if (!(HARNESS_VALUES as readonly string[]).includes(v)) {
-        die(`list: invalid --filter-harness "${v}". Must be one of: ${HARNESS_VALUES.join(', ')}`);
-      }
-      filterHarness = v as Harness;
-    } else if (arg === '--filter-tag') {
-      const v = valueOf(i++, arg);
-      const trimmed = v.trim();
-      if (!trimmed) {
-        die('list: --filter-tag requires a non-empty value.');
-      }
-      filterTag = trimmed as PersonaTag;
-    } else if (arg === '--display-description') {
-      display.description = true;
-    } else if (arg === '--no-display-description') {
-      display.description = false;
-    } else {
-      die(`list: unexpected argument "${arg}".`);
-    }
-  }
-  return { json, filterHarness, filterTag, display, deployments };
-}
-
-async function runList(args: readonly string[]): Promise<never> {
-  if (args.includes('--deployments')) {
-    await runDeploymentList(args.filter((arg) => arg !== '--deployments'));
-    process.exit(0);
-  }
-
-  const { json, filterHarness, filterTag, display } = parseListArgs(args);
-
-  const rows = collectPersonaRows().filter((r) => {
-    if (filterHarness && r.harness !== filterHarness) return false;
-    if (filterTag && !r.tags.includes(filterTag)) return false;
-    return true;
-  });
-
-  if (json) {
-    process.stdout.write(JSON.stringify({ personas: rows }, null, 2) + '\n');
-  } else {
-    process.stdout.write(formatPersonaTable(rows, display));
-    process.stdout.write(`\n${rows.length} persona(s).\n`);
-  }
-  process.exit(0);
-}
-
-function parseShowArgs(args: readonly string[]): {
-  selector: string;
-  json: boolean;
-} {
-  let json = false;
-  let selector: string | undefined;
-  for (const arg of args) {
-    if (arg === '--json') {
-      json = true;
-    } else if (arg === '-h' || arg === '--help') {
-      process.stdout.write('Usage: agentworkforce show <persona> [--json]\n');
-      process.exit(0);
-    } else if (arg.startsWith('--')) {
-      die(`show: unexpected flag "${arg}".`);
-    } else if (selector === undefined) {
-      selector = arg;
-    } else {
-      die(`show: unexpected argument "${arg}".`);
-    }
-  }
-  if (!selector) die('show: missing persona name.');
-  return { selector, json };
-}
-
-function resolveShowTarget(selector: string): { spec: PersonaSpec; source: PersonaSource } {
-  if (selector.includes('@')) {
-    die(
-      'show: @<tier> selectors were removed; tiers are no longer part of the persona shape. ' +
-        `Use 'agentworkforce show ${selector.slice(0, selector.indexOf('@'))}' instead.`,
-      false
-    );
-  }
-  const key = selector;
-  if (!key) die('show: missing persona name.');
-
-  const localSpec = local.byId.get(key);
-  let spec: PersonaSpec | undefined;
-  let source: PersonaSource = 'library';
-  if (localSpec) {
-    spec = localSpec;
-    source = local.sources.get(key) ?? 'cwd';
-  } else {
-    const byIntent = (personaCatalog as Record<string, PersonaSpec | undefined>)[key];
-    if (byIntent) {
-      spec = byIntent;
-    } else {
-      const byId = listBuiltInPersonas().find((p) => p.id === key);
-      if (byId) spec = byId;
-    }
-  }
-  if (!spec) {
-    const result = resolveSpec(key);
-    if ('error' in result) die(result.error, false);
-    spec = result;
-  }
-  return { spec, source };
-}
-
-function indent(text: string, prefix: string): string {
-  return text
-    .split('\n')
-    .map((line) => (line.length > 0 ? prefix + line : line))
-    .join('\n');
-}
-
-function formatPersonaShow(spec: PersonaSpec, source: PersonaSource): string {
-  const lines: string[] = [];
-  lines.push(`PERSONA      ${spec.id}`);
-  lines.push(`SOURCE       ${source}`);
-  lines.push(`INTENT       ${spec.intent}`);
-  lines.push(`TAGS         ${spec.tags && spec.tags.length ? spec.tags.join(', ') : '(none)'}`);
-  lines.push(`DESCRIPTION  ${spec.description}`);
-
-  lines.push('');
-  lines.push('SKILLS');
-  if (spec.skills.length === 0) {
-    lines.push('  (none)');
-  } else {
-    for (const s of spec.skills) {
-      lines.push(`  - ${s.id}`);
-      lines.push(`      source:      ${s.source}`);
-      lines.push(`      description: ${s.description}`);
-    }
-  }
-
-  lines.push('');
-  lines.push('INPUTS');
-  const inputs = Object.entries(spec.inputs ?? {});
-  if (inputs.length === 0) {
-    lines.push('  (none)');
-  } else {
-    for (const [name, input] of inputs) {
-      lines.push(`  - ${name}`);
-      if (input.description) lines.push(`      description: ${input.description}`);
-      lines.push(`      env:         ${input.env ?? name}`);
-      lines.push(`      default:     ${input.default ?? '(required)'}`);
-    }
-  }
-
-  lines.push('');
-  lines.push('MCP SERVERS');
-  const servers = Object.entries(spec.mcpServers ?? {});
-  if (servers.length === 0) {
-    lines.push('  (none)');
-  } else {
-    for (const [name, server] of servers) {
-      lines.push(`  - ${name} (${server.type})`);
-      if (server.type === 'stdio') {
-        lines.push(`      command: ${server.command}${server.args?.length ? ' ' + server.args.join(' ') : ''}`);
-        if (server.env && Object.keys(server.env).length > 0) {
-          lines.push(`      env:     ${Object.keys(server.env).join(', ')}`);
-        }
-      } else {
-        lines.push(`      url:     ${server.url}`);
-        if (server.headers && Object.keys(server.headers).length > 0) {
-          lines.push(`      headers: ${Object.keys(server.headers).join(', ')}`);
-        }
-      }
-    }
-  }
-
-  lines.push('');
-  lines.push('PERMISSIONS');
-  const perms = spec.permissions;
-  if (!perms || (!perms.allow?.length && !perms.deny?.length && !perms.mode)) {
-    lines.push('  (none)');
-  } else {
-    if (perms.mode) lines.push(`  mode:  ${perms.mode}`);
-    if (perms.allow?.length) lines.push(`  allow: ${perms.allow.join(', ')}`);
-    if (perms.deny?.length) lines.push(`  deny:  ${perms.deny.join(', ')}`);
-  }
-
-  lines.push('');
-  lines.push('MOUNT');
-  const mount = spec.mount;
-  if (!mount || (!mount.ignoredPatterns?.length && !mount.readonlyPatterns?.length)) {
-    lines.push('  (none)');
-  } else {
-    if (mount.ignoredPatterns?.length) {
-      lines.push(`  ignored:  ${mount.ignoredPatterns.join(', ')}`);
-    }
-    if (mount.readonlyPatterns?.length) {
-      lines.push(`  readonly: ${mount.readonlyPatterns.join(', ')}`);
-    }
-  }
-
-  lines.push('');
-  lines.push('ENV');
-  const envKeys = Object.keys(spec.env ?? {});
-  if (envKeys.length === 0) {
-    lines.push('  (none)');
-  } else {
-    for (const k of envKeys) lines.push(`  ${k}=${spec.env![k]}`);
-  }
-
-  lines.push('');
-  lines.push('RUNTIME');
-  lines.push(`  harness:  ${spec.harness ?? '— (handler-style persona)'}`);
-  lines.push(`  model:    ${spec.model ?? '—'}`);
-  lines.push(`  reasoning: ${spec.harnessSettings.reasoning}`);
-  lines.push(`  timeout:  ${spec.harnessSettings.timeoutSeconds}s`);
-  if (spec.harnessSettings.sandboxMode) {
-    lines.push(`  sandbox:  ${spec.harnessSettings.sandboxMode}`);
-  }
-  if (spec.harnessSettings.approvalPolicy) {
-    lines.push(`  approvals: ${spec.harnessSettings.approvalPolicy}`);
-  }
-  if (spec.harnessSettings.workspaceWriteNetworkAccess !== undefined) {
-    lines.push(`  network:  ${spec.harnessSettings.workspaceWriteNetworkAccess}`);
-  }
-  if (spec.harnessSettings.webSearch !== undefined) {
-    lines.push(`  webSearch: ${spec.harnessSettings.webSearch}`);
-  }
-  lines.push('  systemPrompt:');
-  lines.push(indent(spec.systemPrompt ?? '(none — handler-style persona)', '    '));
-
-  return lines.join('\n') + '\n';
-}
-
-function runShow(args: readonly string[]): never {
-  const { selector, json } = parseShowArgs(args);
-  const { spec, source } = resolveShowTarget(selector);
-  if (json) {
-    process.stdout.write(JSON.stringify({ source, spec }, null, 2) + '\n');
-  } else {
-    process.stdout.write(formatPersonaShow(spec, source));
-  }
-  process.exit(0);
-}
-
-function runHarnessCheck(): never {
-  const results = detectHarnesses();
-  process.stdout.write(formatAvailabilityTable(results));
-  const available = results.filter((r) => r.available).length;
-  process.stdout.write(`\n${available}/${results.length} harness(es) available.\n`);
-  process.exit(0);
-}
-
-interface CreateTarget {
-  raw: string;
-  kind: string;
-  dir: string;
-  createMode: 'local' | 'built-in';
-}
-
-function defaultCreateTargetSelector(): string {
-  return loadPersonaSourceConfig().defaultCreateTarget ?? 'cwd';
-}
-
-function resolveCreateTarget(rawTarget: string | undefined): CreateTarget {
-  const raw = rawTarget?.trim() || defaultCreateTargetSelector();
-  const config = loadPersonaSourceConfig();
-
-  if (raw === 'cwd') {
-    return {
-      raw,
-      kind: 'cwd',
-      dir: defaultCwdPersonaDir(process.cwd()),
-      createMode: 'local'
-    };
-  }
-  if (raw === 'user') {
-    return {
-      raw,
-      kind: 'user',
-      dir: config.userPersonaDir,
-      createMode: 'local'
-    };
-  }
-  if (raw === 'library') {
-    const dir = resolvePath(process.cwd(), 'personas');
-    if (!existsSync(dir)) {
-      die(
-        'create: --save-in-directory=library requires running from the AgentWorkforce repo root, where ./personas exists.'
-      );
-    }
-    return {
-      raw,
-      kind: 'library',
-      dir,
-      createMode: 'built-in'
-    };
-  }
-  const dirMatch = /^dir:([1-9]\d*)$/.exec(raw);
-  if (dirMatch) {
-    const idx = Number(dirMatch[1]) - 1;
-    const dir = config.personaDirs[idx];
-    if (!dir) {
-      die(`create: ${raw} does not exist. Run "agentworkforce sources list" to see configured dirs.`);
-    }
-    return {
-      raw,
-      kind: raw,
-      dir,
-      createMode: 'local'
-    };
-  }
-
-  return {
-    raw: normalizePersonaDir(raw),
-    kind: 'path',
-    dir: normalizePersonaDir(raw),
-    createMode: 'local'
-  };
-}
-
-function buildCreateInputValues(target: CreateTarget): Record<string, string> {
-  return {
-    [CREATE_INPUT_TARGET_DIR]: target.dir,
-    [CREATE_INPUT_CREATE_MODE]: target.createMode
-  };
-}
-
-function ensureCreateTargetDir(target: CreateTarget): void {
-  if (target.createMode === 'built-in') return;
-  mkdirSync(target.dir, { recursive: true });
-}
-
-function saveDefaultCreateTarget(target: CreateTarget): void {
-  const config = loadPersonaSourceConfig();
-  const raw = target.kind === 'path' ? target.dir : target.raw;
-  const saved = savePersonaSourceConfig(config.personaDirs, { defaultCreateTarget: raw });
-  process.stderr.write(`• default create target saved: ${raw}\n`);
-  process.stderr.write(`• config: ${saved.configPath}\n`);
-}
-
-async function runAgentSelector(
-  selector: string,
-  flags: AgentFlags,
-  inputValues?: Record<string, string>
-): Promise<never> {
-  const target = parseSelector(selector);
-  const selection = {
-    ...buildSelection(target.spec, target.kind),
-    ...(inputValues ? { inputValues } : {})
-  };
-
-  if (flags.dryRun) {
-    const code = runDryRun(selection);
-    process.exit(code);
-  }
-
-  // Record only on real launches so `--dry-run` validations don't pollute the
-  // MRU list used by the bare-invocation picker.
-  recordRecent(target.spec.id);
-  const capture: RunInteractiveCapture = {};
-  const code = await runInteractive(selection, {
-    installInRepo: flags.installInRepo,
-    noLaunchMetadata: flags.noLaunchMetadata,
-    noSkillCache: flags.noSkillCache,
-    refreshSkills: flags.refreshSkills,
-    checkUpstream: flags.checkUpstream,
-    noCheckUpstream: flags.noCheckUpstream,
-    personaSpec: target.spec,
-    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);
-}
-
-interface LocalPersonaImproverContext {
-  target: ResolvedTarget;
-  capture: RunInteractiveCapture;
-  flags: AgentFlags;
-}
-
-/**
- * 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: LocalPersonaImproverContext): Promise<void> {
-  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 as Error).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: ImproverProposalsFile | undefined;
-  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 as Error).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 as Error).message}\n`
-    );
-  }
-}
-
-export interface ImproverPatch {
-  path: string;
-  op: 'set' | 'append';
-  value: unknown;
-}
-
-/**
- * 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: readonly string[] = [
-  'description',
-  'agentsMdContent',
-  'claudeMdContent',
-  'tags',
-  '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: readonly string[] = ['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: string, context: string): readonly string[] {
-  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: ImproverPatch, context: string): void {
-  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 as { op: string }).op}"`);
-}
-
-export interface ImproverProposal {
-  id: string;
-  summary: string;
-  rationale: string;
-  patches: ImproverPatch[];
-}
-
-export interface ImproverProposalsFile {
-  personaId: string;
-  personaFilePath: string;
-  transcriptPath: string;
-  proposals: ImproverProposal[];
-}
-
-/**
- * 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: {
-  harness?: Harness;
-  sessionCwd?: string;
-  enrichment: Record<string, string>;
-  startedAt?: number;
-}): Promise<string | undefined> {
-  if (!input.harness || !input.sessionCwd) return undefined;
-  const persona = input.enrichment.persona;
-  const personaVersion = input.enrichment.personaVersion;
-  if (!persona || !personaVersion) return undefined;
-  let sdk: typeof import('@relayburn/sdk');
-  try {
-    sdk = await import('@relayburn/sdk');
-  } catch {
-    return undefined;
-  }
-  if (typeof sdk.exportStamps !== 'function') return undefined;
-  let rows: unknown[];
-  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: string | undefined;
-  // 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 as {
-      ts?: unknown;
-      selector?: { sessionId?: unknown };
-      enrichment?: Record<string, unknown>;
-    };
-    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: Harness,
-  sessionCwd: string,
-  sessionId: string
-): string | undefined {
-  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: string,
-  needle: string,
-  extensions: readonly string[]
-): string | undefined {
-  const wantsExt = (name: string) => extensions.some((ext) => name.endsWith(ext));
-  const visit = (cur: string, depth: number): string | undefined => {
-    let entries: Dirent[];
-    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: {
-  harness?: Harness;
-  sessionCwd?: string;
-  startedAt?: number;
-}): string | undefined {
-  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;
-}
-
-interface FindMatchingOptions {
-  dir: string;
-  /** Whether to walk subdirectories (codex date-grouped, opencode project-hash-grouped). */
-  recursive: boolean;
-  extensions: readonly string[];
-  sinceMs: number;
-  sessionCwd: string;
-  /**
-   * Extract the embedded cwd from the candidate file. Returns undefined
-   * when the file has no parseable cwd (skip rather than match).
-   */
-  readCwd: (path: string) => string | 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: FindMatchingOptions): string | undefined {
-  const wantsExt = (name: string) => opts.extensions.some((ext) => name.endsWith(ext));
-  let bestPath: string | undefined;
-  let bestMtime = -1;
-  const visit = (cur: string, depth: number) => {
-    let entries: Dirent[];
-    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 ~64KB from `path` (enough for a JSONL header line plus
- * margin) and return it as a string. Used by the per-harness cwd
- * extractors so we don't slurp multi-megabyte transcripts to find a
- * field on line 1.
- */
-interface TranscriptHeader {
-  text: string;
-  /** True if the file was longer than `maxBytes` and we only read the prefix. */
-  truncated: boolean;
-}
-
-/**
- * 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: string,
-  maxBytes = 65536
-): TranscriptHeader | undefined {
-  let fd: number | undefined;
-  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: string): string | undefined {
-  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) as { cwd?: unknown };
-      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: string): string | undefined {
-  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) as { payload?: { cwd?: unknown } };
-    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: string): string | undefined {
-  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) as { directory?: unknown };
-    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: {
-  personaFilePath: string;
-  transcriptPath: string;
-  proposalsOutputPath: string;
-}): Promise<ImproverProposalsFile> {
-  const improverSpec = personaCatalog['persona-improvement' as const];
-  if (!improverSpec) {
-    throw new Error('built-in persona "persona-improver" is not registered in the catalog');
-  }
-  const selection = buildSelection(improverSpec, 'repo');
-  const inputValues: Record<string, string> = {
-    PERSONA_FILE_PATH: args.personaFilePath,
-    SESSION_TRANSCRIPT_PATH: args.transcriptPath,
-    PROPOSALS_OUTPUT_PATH: args.proposalsOutputPath
-  };
-  const inputResolution = resolvePersonaInputs(
-    selection.inputs,
-    inputValues,
-    process.env
-  );
-  const renderedSystemPrompt = renderPersonaInputs(
-    selection.systemPrompt,
-    inputResolution.values
-  );
-  const callerEnv = { ...process.env, ...inputResolution.values };
-  const envResolution = resolveStringMapLenient(selection.env, callerEnv, 'env');
-  const mcpResolution = resolveMcpServersLenient(selection.mcpServers, callerEnv);
-  const taskBody = [
-    '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}`
-  ].join('\n');
-  const task = `${taskBody}\n\nRun inputs:\n${JSON.stringify(inputValues, null, 2)}`;
-  const spec = buildNonInteractiveSpec({
-    harness: selection.harness,
-    personaId: selection.personaId,
-    model: selection.model,
-    systemPrompt: renderedSystemPrompt,
-    harnessSettings: selection.harnessSettings,
-    mcpServers: mcpResolution.servers,
-    permissions: selection.permissions,
-    task
-  });
-  const childEnv = { ...callerEnv, ...(envResolution.value ?? {}), ...inputResolution.values };
-  const cwd = process.cwd();
-  const configWrites: { path: string; existed: boolean; previous?: string }[] = [];
-  for (const file of spec.configFiles) {
-    assertSafeRelativePath(file.path);
-    const target = join(cwd, file.path);
-    const existed = existsSync(target);
-    const previous = existed ? readFileSync(target, 'utf8') : undefined;
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, file.contents, 'utf8');
-    configWrites.push({ path: target, existed, ...(previous !== undefined ? { previous } : {}) });
-  }
-  const restoreConfigWrites = () => {
-    for (const write of [...configWrites].reverse()) {
-      if (write.existed) {
-        writeFileSync(write.path, write.previous ?? '', 'utf8');
-      } else {
-        rmSync(write.path, { force: true });
-      }
-    }
-  };
-  const timeoutMs = selection.harnessSettings.timeoutSeconds
-    ? selection.harnessSettings.timeoutSeconds * 1000
-    : undefined;
-  let captureResult: { exitCode: number | null; stderr: string };
-  try {
-    captureResult = await new Promise<{ exitCode: number | null; stderr: string }>(
-      (resolveResult) => {
-        const child = spawn(spec.bin, [...spec.args], {
-          cwd,
-          env: childEnv,
-          stdio: ['ignore', 'pipe', 'pipe'],
-          shell: false
-        });
-        let stderrBuf = '';
-        let forceKillTimeout: NodeJS.Timeout | undefined;
-        child.stdout?.setEncoding('utf8');
-        child.stderr?.setEncoding('utf8');
-        child.stderr?.on('data', (chunk: string) => {
-          stderrBuf += chunk;
-        });
-        // SIGTERM first; if the harness traps or ignores it, escalate to
-        // SIGKILL after a 1s grace so the timeout is actually enforced.
-        const timeout =
-          timeoutMs !== undefined
-            ? setTimeout(() => {
-                child.kill('SIGTERM');
-                forceKillTimeout = setTimeout(() => {
-                  if (!child.killed) child.kill('SIGKILL');
-                }, 1000);
-              }, timeoutMs)
-            : undefined;
-        const clearTimers = () => {
-          if (timeout) clearTimeout(timeout);
-          if (forceKillTimeout) clearTimeout(forceKillTimeout);
-        };
-        child.on('error', (err) => {
-          clearTimers();
-          resolveResult({ exitCode: 1, stderr: `${stderrBuf}${err.message}\n` });
-        });
-        child.on('close', (code, signal) => {
-          clearTimers();
-          const exitCode =
-            typeof code === 'number' ? code : signal ? signalExitCode(signal) : null;
-          resolveResult({ exitCode, stderr: stderrBuf });
-        });
-      }
-    );
-  } finally {
-    // Always restore — a synchronous spawn() throw or unexpected promise
-    // rejection must not leave orphaned `opencode.json` (or any other
-    // configFile) sitting in the user's working directory.
-    restoreConfigWrites();
-  }
-  if (captureResult.exitCode !== 0) {
-    throw new Error(
-      `improver exited with code=${captureResult.exitCode ?? 'null'}.${captureResult.stderr ? ` stderr: ${captureResult.stderr.slice(0, 400)}` : ''}`
-    );
-  }
-  let raw: string;
-  try {
-    raw = readFileSync(args.proposalsOutputPath, 'utf8');
-  } catch (err) {
-    throw new Error(
-      `improver did not write proposals file at ${args.proposalsOutputPath}: ${(err as Error).message}`
-    );
-  }
-  return parseProposals(raw);
-}
-
-export function parseProposals(raw: string): ImproverProposalsFile {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`proposals file is not valid JSON: ${(err as Error).message}`);
-  }
-  if (!parsed || typeof parsed !== 'object') {
-    throw new Error('proposals file must be a JSON object');
-  }
-  const obj = parsed as Record<string, unknown>;
-  const proposalsArr = Array.isArray(obj.proposals) ? obj.proposals : [];
-  const proposals: ImproverProposal[] = [];
-  for (const [idx, item] of proposalsArr.entries()) {
-    if (!item || typeof item !== 'object') {
-      throw new Error(`proposals[${idx}] must be an object`);
-    }
-    const p = item as Record<string, unknown>;
-    const id = normalizeNonEmptyString(p.id) ?? `proposal-${idx + 1}`;
-    const rationale = typeof p.rationale === 'string' ? p.rationale.trim() : '';
-    if (!Array.isArray(p.patches) || p.patches.length === 0) {
-      throw new Error(`proposals[${idx}].patches must be a non-empty array`);
-    }
-    const patches: ImproverPatch[] = [];
-    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 as Record<string, unknown>;
-      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: ImproverPatch = { path: rp.path, op: rp.op, value: rp.value };
-      assertAllowedImproverPatch(patch, `proposals[${idx}].patches[${pidx}]`);
-      patches.push(patch);
-    }
-    const summary = normalizeProposalSummary(p.summary, id, patches);
-    proposals.push({
-      id,
-      summary,
-      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
-  };
-}
-
-function normalizeNonEmptyString(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function normalizeProposalSummary(
-  value: unknown,
-  id: string,
-  patches: readonly ImproverPatch[]
-): string {
-  const explicit = normalizeNonEmptyString(value);
-  if (explicit) return explicit;
-  const fromId = humanizeProposalId(id);
-  if (fromId) return fromId;
-  return summarizeProposalPatches(patches);
-}
-
-function humanizeProposalId(id: string): string | undefined {
-  const trimmed = id.trim();
-  if (!trimmed || /^p\d+$/i.test(trimmed) || /^proposal-\d+$/i.test(trimmed)) {
-    return undefined;
-  }
-  const words = trimmed.replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
-  if (!words) return undefined;
-  return `${words.slice(0, 1).toUpperCase()}${words.slice(1)}`;
-}
-
-function summarizeProposalPatches(patches: readonly ImproverPatch[]): string {
-  if (patches.length === 1) return summarizeSingleProposalPatch(patches[0]);
-  return `Apply ${patches.length} persona updates`;
-}
-
-function summarizeSingleProposalPatch(patch: ImproverPatch): string {
-  if (patch.op === 'append' && patch.path === 'skills') return 'Add skill';
-  if (patch.path.startsWith('inputs.')) {
-    return `Add ${patch.path.slice('inputs.'.length)} input`;
-  }
-  if (patch.path === 'description') return 'Update description';
-  if (patch.path === 'agentsMdContent') return 'Update AGENTS.md guidance';
-  if (patch.path === 'claudeMdContent') return 'Update CLAUDE.md guidance';
-  if (patch.path === 'tags') return 'Update tags';
-  if (patch.path === 'systemPrompt') return 'Update system prompt';
-  return patch.op === 'append' ? `Append to ${patch.path}` : `Update ${patch.path}`;
-}
-
-/**
- * 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: ImproverProposalsFile): ImproverProposal[] {
-  if (!process.stdin.isTTY) return [];
-  const accepted: ImproverProposal[] = [];
-  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: ImproverPatch): string {
-  const op = patch.op === 'append' ? '+= ' : '= ';
-  const valueStr = formatPatchValue(patch.value);
-  return `${patch.path} ${op}${valueStr}`;
-}
-
-function formatPatchValue(value: unknown): string {
-  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: string,
-  valid: readonly string[],
-  opts: {
-    write?: (chunk: string) => void;
-    read?: () => string | undefined;
-  } = {}
-): string {
-  const write = opts.write ?? ((chunk: string) => {
-    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: string,
-  accepted: readonly ImproverProposal[]
-): void {
-  const raw = readFileSync(personaFilePath, 'utf8');
-  const json = JSON.parse(raw) as Record<string, unknown>;
-  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: Record<string, unknown>, patch: ImproverPatch): void {
-  // 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: Record<string, unknown> = 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: Record<string, unknown> = {};
-      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 as Record<string, unknown>;
-  }
-  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 personas for the interactive TUI. Source label mirrors the cascade
- * shown by `agentworkforce list` so the picker tells the user *where* a
- * persona is coming from (cwd, user, dir:n, library) without a separate
- * lookup.
- */
-export function buildTuiCandidates(): TuiCandidate[] {
-  const byId = new Map<string, TuiCandidate>();
-  for (const spec of listBuiltInPersonas()) {
-    byId.set(spec.id, {
-      id: spec.id,
-      description: spec.description,
-      source: formatPersonaSourceLabel('library')
-    });
-  }
-  for (const [id, spec] of local.byId.entries()) {
-    byId.set(id, {
-      id,
-      description: spec.description,
-      source: formatPersonaSourceLabel(local.sources.get(id) ?? 'library')
-    });
-  }
-  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
-}
-
-/**
- * Bare-invocation flow: open the interactive TUI, then hand the chosen
- * persona to {@link runAgentSelector}. Quitting the picker (Esc / Ctrl-C)
- * exits with conventional 130 so shell pipelines see SIGINT-style failure.
- *
- * runAgentSelector terminates the process via process.exit; this function
- * only returns when the picker is dismissed without a selection.
- */
-async function runInteractivePicker(): Promise<never> {
-  const candidates = buildTuiCandidates();
-  if (candidates.length === 0) {
-    process.stderr.write(
-      'No personas available. Try `agentworkforce install <pack>` or run with --help.\n'
-    );
-    process.exit(1);
-  }
-  const selected = await runPersonaPickerTui({
-    candidates,
-    recentIds: loadRecents()
-  });
-  if (!selected) {
-    process.exit(130);
-  }
-  await runAgentSelector(selected, {
-    installInRepo: false,
-    noLaunchMetadata: false,
-    dryRun: false,
-    noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
-    refreshSkills: false,
-    checkUpstream: false,
-    noCheckUpstream: false
-  });
-  // runAgentSelector has Promise<never> return type; this is unreachable.
-  process.exit(0);
-}
-
-/**
- * Enumerate persona candidates for the picker. Local overrides win over the
- * built-in catalog when ids collide; the picker only needs the projection
- * fields ({@link PickCandidate}), not full specs.
- */
-export function buildPickCandidates(): PickCandidate[] {
-  const byId = new Map<string, PickCandidate>();
-  for (const spec of listBuiltInPersonas()) {
-    byId.set(spec.id, {
-      id: spec.id,
-      intent: spec.intent,
-      tags: spec.tags ? [...spec.tags] : [],
-      description: spec.description
-    });
-  }
-  for (const [id, spec] of local.byId.entries()) {
-    byId.set(id, {
-      id,
-      intent: spec.intent,
-      tags: spec.tags ? [...spec.tags] : [],
-      description: spec.description
-    });
-  }
-  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
-}
-
 /**
- * Synchronous y/n prompt over /dev/tty-equivalent stdin. Default is "no" on
- * empty input or non-y answer. Used by `pick` when the picker reports
- * no-match in an interactive session.
+ * Thin CLI entry. Loading the full CLI module graph costs hundreds of
+ * milliseconds, so `agent <persona>` first tries the warm fast path — plan
+ * validation + warm-mount claim + harness spawn via `fast-launch.js` (node
+ * builtins only) — and only then imports the heavy implementation, either to
+ * manage the already-running fast session or to run the full launch.
  *
- * Test seam: callers can inject `read` so the prompt path is exercisable
- * without a real TTY.
+ * Everything that used to live in this file is in `cli-impl.js`; this entry
+ * must stay import-free apart from node builtins or the fast path is
+ * pointless.
  */
-export function promptYesNoSync(
-  question: string,
-  opts: {
-    isTTY?: boolean;
-    write?: (chunk: string) => void;
-    read?: () => string | undefined;
-  } = {}
-): boolean {
-  const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
-  if (!isTTY) return false;
-  const write = opts.write ?? ((chunk: string) => {
-    process.stderr.write(chunk);
-  });
-  write(question);
-  const answer = opts.read ? opts.read() : readLineFromStdinSync();
-  if (!answer) return false;
-  const normalized = answer.trim().toLowerCase();
-  return normalized === 'y' || normalized === 'yes';
-}
-
-function readLineFromStdinSync(): string | undefined {
-  const buf = Buffer.alloc(256);
-  let line = '';
-  for (;;) {
-    let n: number;
-    try {
-      n = readSync(0, buf, 0, buf.length, null);
-    } catch {
-      return line || undefined;
-    }
-    if (n <= 0) return line || undefined;
-    const chunk = buf.subarray(0, n).toString('utf8');
-    const newlineIdx = chunk.indexOf('\n');
-    if (newlineIdx === -1) {
-      line += chunk;
-      continue;
-    }
-    line += chunk.slice(0, newlineIdx);
-    return line;
-  }
-}
-
-async function runPick(args: readonly string[]): Promise<never> {
-  const positional: string[] = [];
-  for (const arg of args) {
-    if (arg === '-h' || arg === '--help') {
-      process.stdout.write(
-        'Usage: agentworkforce pick "<task description>"\n' +
-          '  Prints the best-fit persona id to stdout. On low confidence, prompts to\n' +
-          '  open persona-maker (TTY) or exits 2 (non-TTY). Exits 3 if `claude` is\n' +
-          '  not installed.\n'
-      );
-      process.exit(0);
-    }
-    positional.push(arg);
-  }
-  if (positional.length === 0) {
-    die('pick: missing task description. Usage: agentworkforce pick "<task>"');
-  }
-  if (positional.length > 1) {
-    die(
-      `pick: expected a single quoted task description, got ${positional.length} arguments. ` +
-        `Did you forget to quote the task? Try: agentworkforce pick "${positional.join(' ')}"`
-    );
-  }
-  const task = positional[0].trim();
-  if (!task) {
-    die('pick: task description is empty.');
-  }
-
-  const candidates = buildPickCandidates();
-  const result: PickResult = pickPersona(task, candidates);
-
-  if (result.kind === 'match') {
-    process.stderr.write(
-      `• picked ${result.personaId} (${result.confidence}): ${result.reason}\n`
-    );
-    process.stdout.write(`${result.personaId}\n`);
-    process.exit(0);
-  }
-
-  if (result.kind === 'picker-unavailable') {
-    process.stderr.write(`pick: ${result.message}\n`);
-    process.exit(3);
-  }
-
-  // no-match
-  process.stderr.write(`pick: no close persona match — ${result.reason}\n`);
-  const wantsCreate = promptYesNoSync(
-    'Open persona-maker to scaffold a new persona for this task? [y/N] '
-  );
-  if (!wantsCreate) {
-    process.stderr.write(
-      'Try: agentworkforce list   # to browse existing personas\n' +
-        '     agentworkforce create  # to author a new persona\n'
-    );
-    process.exit(2);
-  }
-
-  const target = resolveCreateTarget(undefined);
-  ensureCreateTargetDir(target);
-  const inputValues = {
-    ...buildCreateInputValues(target),
-    TASK_DESCRIPTION: task
-  };
-  await runAgentSelector(
-    CREATE_SELECTOR,
-    {
-      installInRepo: false,
-      noLaunchMetadata: false,
-      dryRun: false,
-      noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
-      refreshSkills: false,
-      checkUpstream: false,
-      noCheckUpstream: false
-    },
-    inputValues
-  );
-  // runAgentSelector terminates via process.exit; this satisfies TS's
-  // reachable-end-point check for the `Promise<never>` return type.
-  process.exit(0);
-}
-
 export async function main(): Promise<void> {
   const argv = process.argv.slice(2);
-  const [subcommand, ...rest] = argv;
-
-  if (subcommand === '-h' || subcommand === '--help') {
-    process.stdout.write(USAGE);
-    process.exit(0);
-  }
-
-  if (!subcommand) {
-    if (process.stdin.isTTY && process.stderr.isTTY) {
-      await runInteractivePicker();
-      // runInteractivePicker either runAgentSelector → process.exit, or
-      // exits itself on quit / no-match. Satisfy TS's unreachable check.
-      process.exit(0);
-    }
-    process.stdout.write(USAGE);
-    process.exit(1);
-  }
-
-  if (subcommand === '-v' || subcommand === '--version') {
-    process.stdout.write(`${CLI_VERSION}\n`);
-    process.exit(0);
-  }
-
-  if (subcommand === 'list') {
-    await runList(rest);
-    return;
-  }
-
-  if (subcommand === 'show') {
-    runShow(rest);
-  }
-
-  if (subcommand === 'persona') {
-    try {
-      await runPersonaCompileCommand(rest);
-      return;
-    } catch (err) {
-      die((err as Error)?.message ?? String(err), false);
-    }
-  }
-
-  if (subcommand === 'install') {
-    runPersonaInstall(rest);
-  }
-
-  if (subcommand === 'sources') {
-    runSources(rest);
-  }
-
-  if (subcommand === 'harness') {
-    const [action, ...extra] = rest;
-    if (!action || action === '-h' || action === '--help') {
-      die('harness: missing action. Expected: check');
-    }
-    if (action !== 'check') {
-      die(`harness: unknown action "${action}". Expected: check`);
-    }
-    if (extra.length > 0) {
-      die(`harness check: unexpected argument "${extra[0]}".`);
-    }
-    runHarnessCheck();
-  }
-
-  if (subcommand === 'create') {
-    const { flags, selector, inputValues } = parseCreateArgs(rest);
-    await runAgentSelector(selector, flags, inputValues);
-  }
-
-  if (subcommand === 'pick') {
-    await runPick(rest);
-  }
-
-  if (subcommand === 'deploy') {
-    await runDeploy(rest);
-    return;
-  }
-
-  if (subcommand === 'invoke') {
-    await runInvoke(rest);
-    return;
-  }
-
-  if (subcommand === 'runs') {
-    await runRuns(rest);
-    return;
-  }
-
-  if (subcommand === 'integrations') {
-    await runIntegrationsCommand(rest);
-    return;
-  }
-
-  if (subcommand === 'trigger') {
-    await runTrigger(rest);
-    return;
-  }
-
-  if (subcommand === 'deployments') {
-    const [action, ...extra] = rest;
-    if (!action || action === '-h' || action === '--help') {
-      process.stdout.write('Usage: agentworkforce deployments <list|logs|trigger> [flags]\n');
-      process.exit(action ? 0 : 1);
-    }
-    if (action === 'list') {
-      await runDeploymentList(extra);
-      return;
-    }
-    if (action === 'logs') {
-      await runDeploymentLogs(extra);
-      return;
-    }
-    if (action === 'trigger') {
-      await runTrigger(extra);
+  if (argv[0] === 'agent' && process.env.AGENTWORKFORCE_NO_FAST !== '1') {
+    const { tryFastAgentLaunch } = await import('./fast-launch.js');
+    const fast = tryFastAgentLaunch(argv.slice(1));
+    if (fast) {
+      const { resumeFastSession } = await import('./cli-impl.js');
+      await resumeFastSession(fast);
       return;
     }
-    die(`deployments: unknown action "${action}". Expected: list, logs, trigger`);
-  }
-
-  if (subcommand === 'destroy') {
-    await runDestroy(rest);
-    return;
-  }
-
-  if (subcommand === 'login') {
-    await runLogin(rest);
-    return;
-  }
-
-  if (subcommand === 'logout') {
-    await runLogout(rest);
-    return;
-  }
-
-  if (subcommand !== 'agent') {
-    die(`Unknown subcommand "${subcommand}".`);
-  }
-
-  const { flags, positional } = parseAgentArgs(rest);
-  const [selector, ...extra] = positional;
-  if (!selector) die('agent: missing persona selector.');
-  if (extra.length > 0) {
-    die(`agent: unexpected argument "${extra[0]}". The agent subcommand only takes a persona selector.`);
-  }
-
-  await runAgentSelector(selector, flags);
-}
-
-export interface AgentFlags {
-  installInRepo: boolean;
-  noLaunchMetadata: boolean;
-  dryRun: boolean;
-  /** Bypass the persistent skill-install cache for this launch. */
-  noSkillCache: boolean;
-  /** Force a fresh install even if the cache entry exists (rebuilds it in place). */
-  refreshSkills: boolean;
-  /** Force an upstream drift check this launch regardless of the TTL. */
-  checkUpstream: boolean;
-  /** Skip the upstream drift check this launch regardless of the TTL. */
-  noCheckUpstream: boolean;
-}
-
-export interface CreateFlags extends AgentFlags {
-  saveInDirectory?: string;
-  saveDefault: boolean;
-}
-
-export function parseAgentArgs(args: readonly string[]): {
-  flags: AgentFlags;
-  positional: string[];
-} {
-  const flags: AgentFlags = {
-    installInRepo: false,
-    noLaunchMetadata: false,
-    dryRun: false,
-    noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
-    refreshSkills: false,
-    checkUpstream: false,
-    noCheckUpstream: false
-  };
-  const positional: string[] = [];
-  let seenDoubleDash = false;
-  for (const arg of args) {
-    if (seenDoubleDash) {
-      positional.push(arg);
-      continue;
-    }
-    if (arg === '--') {
-      seenDoubleDash = true;
-      continue;
-    }
-    if (arg === '--install-in-repo') {
-      flags.installInRepo = true;
-      continue;
-    }
-    if (arg === '--no-launch-metadata') {
-      flags.noLaunchMetadata = true;
-      continue;
-    }
-    if (arg === '--dry-run') {
-      flags.dryRun = true;
-      continue;
-    }
-    if (arg === '--no-skill-cache') {
-      flags.noSkillCache = true;
-      continue;
-    }
-    if (arg === '--refresh-skills') {
-      flags.refreshSkills = true;
-      continue;
-    }
-    if (arg === '--check-upstream') {
-      flags.checkUpstream = true;
-      continue;
-    }
-    if (arg === '--no-check-upstream') {
-      flags.noCheckUpstream = true;
-      continue;
-    }
-    if (arg === '-h' || arg === '--help') {
-      process.stdout.write(USAGE);
-      process.exit(0);
-    }
-    positional.push(arg);
-  }
-  return { flags, positional };
-}
-
-export function parseCreateArgs(args: readonly string[]): {
-  flags: CreateFlags;
-  selector: string;
-  inputValues: Record<string, string>;
-} {
-  const flags: CreateFlags = {
-    installInRepo: false,
-    noLaunchMetadata: false,
-    dryRun: false,
-    noSkillCache: process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1',
-    refreshSkills: false,
-    checkUpstream: false,
-    noCheckUpstream: false,
-    saveDefault: false
-  };
-  let seenDoubleDash = false;
-  const positional: string[] = [];
-  const valueOf = (i: number, flag: string): string => {
-    const v = args[i + 1];
-    if (v === undefined || v.startsWith('--')) {
-      die(`create: ${flag} requires a value.`);
-    }
-    return v;
-  };
-
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (seenDoubleDash) {
-      positional.push(arg);
-      continue;
-    }
-    if (arg === '--') {
-      seenDoubleDash = true;
-      continue;
-    }
-    if (arg === '--install-in-repo') {
-      flags.installInRepo = true;
-      continue;
-    }
-    if (arg === '--no-launch-metadata') {
-      flags.noLaunchMetadata = true;
-      continue;
-    }
-    if (arg === '--save-in-directory') {
-      const value = valueOf(i, arg).trim();
-      if (!value) die('create: --save-in-directory requires a non-empty value.');
-      flags.saveInDirectory = value;
-      i += 1;
-      continue;
-    }
-    if (arg.startsWith('--save-in-directory=')) {
-      const value = arg.slice('--save-in-directory='.length).trim();
-      if (!value) die('create: --save-in-directory requires a non-empty value.');
-      flags.saveInDirectory = value;
-      continue;
-    }
-    if (arg === '--save-default') {
-      flags.saveDefault = true;
-      continue;
-    }
-    if (arg === '-h' || arg === '--help') {
-      process.stdout.write(
-        'Usage: agentworkforce create [--save-in-directory=<cwd|user|dir:n|library|path>] [--save-default] [--install-in-repo] [--no-launch-metadata]\n'
-      );
-      process.exit(0);
-    }
-    positional.push(arg);
   }
-
-  const [unexpected] = positional;
-  if (unexpected) {
-    die(
-      `create: unexpected argument "${unexpected}". The create command always runs ${CREATE_SELECTOR}; use "agentworkforce agent <persona>" to run another persona.`
-    );
-  }
-
-  const target = resolveCreateTarget(flags.saveInDirectory);
-  ensureCreateTargetDir(target);
-  if (flags.saveDefault) saveDefaultCreateTarget(target);
-
-  return {
-    flags,
-    selector: CREATE_SELECTOR,
-    inputValues: buildCreateInputValues(target)
-  };
+  const { main: fullMain } = await import('./cli-impl.js');
+  await fullMain();
 }
 
 // Only run main when invoked as the CLI entry, not when imported by tests.
@@ -4757,7 +43,8 @@ const isCliEntry = (() => {
 })();
 
 if (isCliEntry) {
-  main().catch((err) => {
+  main().catch(async (err) => {
+    const { MissingPersonaInputError } = await import('@agentworkforce/persona-kit');
     if (err instanceof MissingPersonaInputError) {
       process.stderr.write(`${err.message}\n`);
       process.exit(1);
diff --git a/packages/cli/src/fast-launch.test.ts b/packages/cli/src/fast-launch.test.ts
new file mode 100644
index 00000000..81ff1284
--- /dev/null
+++ b/packages/cli/src/fast-launch.test.ts
@@ -0,0 +1,169 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  launchPlanKey,
+  launchPlanPath,
+  statDigestOf,
+  tryFastAgentLaunch,
+  warmMountDir,
+  writeLaunchPlan,
+  deleteLaunchPlan,
+  LAUNCH_PLAN_SCHEMA_VERSION,
+  type LaunchPlan
+} from './fast-launch.js';
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), 'aw-fast-launch-test-'));
+}
+
+test('launchPlanKey: stable per (cwd, selector), distinct across either', () => {
+  const a = launchPlanKey('/repo/one', 'persona-maker');
+  assert.equal(a, launchPlanKey('/repo/one', 'persona-maker'));
+  assert.notEqual(a, launchPlanKey('/repo/two', 'persona-maker'));
+  assert.notEqual(a, launchPlanKey('/repo/one', 'other-persona'));
+  assert.match(a, /^[0-9a-f]{32}$/);
+});
+
+test('launchPlanPath and warmMountDir share the plan key', () => {
+  const key = launchPlanKey('/repo/one', 'persona-maker');
+  assert.ok(launchPlanPath('/repo/one', 'persona-maker').includes(key));
+  assert.ok(warmMountDir('/repo/one', 'persona-maker').endsWith(key));
+});
+
+test('statDigestOf: existing file captures size+mtime, missing file is all-null', () => {
+  const dir = tempDir();
+  try {
+    const file = join(dir, 'f.txt');
+    writeFileSync(file, 'hello');
+    const digest = statDigestOf(file);
+    const st = statSync(file);
+    assert.equal(digest.size, st.size);
+    assert.equal(digest.mtimeMs, st.mtimeMs);
+
+    const missing = statDigestOf(join(dir, 'nope.txt'));
+    assert.equal(missing.size, null);
+    assert.equal(missing.mtimeMs, null);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('tryFastAgentLaunch: refuses flags, multiple args, and missing plans', () => {
+  assert.equal(tryFastAgentLaunch([]), null);
+  assert.equal(tryFastAgentLaunch(['--dry-run']), null);
+  assert.equal(tryFastAgentLaunch(['persona-maker', 'extra']), null);
+  // No plan exists for this selector in this cwd.
+  assert.equal(tryFastAgentLaunch(['no-such-persona-for-fast-launch-test']), null);
+});
+
+function planFixture(overrides: Partial<LaunchPlan> = {}): LaunchPlan {
+  const cwd = process.cwd();
+  return {
+    schemaVersion: LAUNCH_PLAN_SCHEMA_VERSION,
+    cliVersion: 'not-the-real-version',
+    cwd,
+    selector: 'fast-launch-test-persona',
+    personaId: 'fast-launch-test-persona',
+    harness: 'opencode',
+    model: 'opencode/test',
+    digests: [],
+    envExact: {},
+    skillCache: {
+      dir: '/nonexistent',
+      fingerprint: 'f'.repeat(32),
+      upstreamIntervalRaw: null,
+      upstreamIntervalMs: null
+    },
+    spawn: { binPath: '/nonexistent/bin', args: [], envAdditions: {} },
+    mount: { warmDir: '/nonexistent', ignoredPatterns: [], readonlyPatterns: [] },
+    ...overrides
+  };
+}
+
+test('tryFastAgentLaunch: version, env pin, and digest mismatches all fall back', () => {
+  const selector = 'fast-launch-test-persona';
+  try {
+    // Wrong CLI version → refused before anything else is touched.
+    writeLaunchPlan(planFixture());
+    assert.equal(tryFastAgentLaunch([selector]), null);
+
+    // Note: a plan with the real CLI version would next fail on env pins /
+    // digests; exercise the env pin gate explicitly.
+    const pkg = statDigestOf(new URL('../package.json', import.meta.url).pathname);
+    assert.ok(pkg.size !== null, 'test sanity: package.json digest');
+    writeLaunchPlan(
+      planFixture({
+        cliVersion: (JSON.parse(
+          readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+        ) as { version: string }).version,
+        envExact: { AW_FAST_LAUNCH_TEST_PIN: 'expected-value' }
+      })
+    );
+    assert.equal(process.env.AW_FAST_LAUNCH_TEST_PIN, undefined);
+    assert.equal(tryFastAgentLaunch([selector]), null);
+  } finally {
+    deleteLaunchPlan(process.cwd(), selector);
+  }
+});
+
+test('writeLaunchPlan/deleteLaunchPlan round trip', () => {
+  const selector = 'fast-launch-roundtrip-persona';
+  const plan = planFixture({ selector, personaId: selector });
+  try {
+    writeLaunchPlan(plan);
+    const onDisk = JSON.parse(
+      readFileSync(launchPlanPath(process.cwd(), selector), 'utf8')
+    ) as LaunchPlan;
+    assert.equal(onDisk.selector, selector);
+    assert.equal(onDisk.schemaVersion, LAUNCH_PLAN_SCHEMA_VERSION);
+  } finally {
+    deleteLaunchPlan(process.cwd(), selector);
+  }
+  assert.equal(tryFastAgentLaunch([selector]), null);
+});
+
+test('tryFastAgentLaunch: valid-looking plan still refuses without a warm mount', () => {
+  const selector = 'fast-launch-no-warm-mount-persona';
+  const dir = tempDir();
+  try {
+    const bin = join(dir, 'bin.sh');
+    writeFileSync(bin, '#!/bin/sh\nexit 0\n');
+    const cacheDir = join(dir, 'skill-cache');
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(
+      join(cacheDir, '.aw-skill-cache.json'),
+      JSON.stringify({
+        fingerprint: 'f'.repeat(32),
+        lastUpstreamCheckAt: new Date().toISOString()
+      })
+    );
+    const version = (JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+    ) as { version: string }).version;
+    writeLaunchPlan(
+      planFixture({
+        selector,
+        personaId: selector,
+        cliVersion: version,
+        skillCache: {
+          dir: cacheDir,
+          fingerprint: 'f'.repeat(32),
+          upstreamIntervalRaw: null,
+          // Interval null = drift checks disabled → marker age irrelevant.
+          upstreamIntervalMs: null
+        },
+        spawn: { binPath: bin, args: [], envAdditions: {} },
+        mount: { warmDir: join(dir, 'warm'), ignoredPatterns: [], readonlyPatterns: [] }
+      })
+    );
+    // Everything validates except the warm mount (missing marker/state).
+    assert.equal(tryFastAgentLaunch([selector]), null);
+  } finally {
+    deleteLaunchPlan(process.cwd(), selector);
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/packages/cli/src/fast-launch.ts b/packages/cli/src/fast-launch.ts
new file mode 100644
index 00000000..f587730c
--- /dev/null
+++ b/packages/cli/src/fast-launch.ts
@@ -0,0 +1,313 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * Warm-launch fast path.
+ *
+ * This module is the only code that runs before the harness child is spawned
+ * on a warm launch, so it must stay dependency-light: node builtins only, no
+ * workspace packages, no npm deps. The heavy CLI module graph
+ * (`cli-impl.js`) is imported by the thin entry *after* the child is already
+ * running.
+ *
+ * The contract: a prior full launch wrote a {@link LaunchPlan} recording the
+ * exact spawn (bin + argv), the warm mount location, and stat-level digests
+ * of every input that fed persona resolution. `tryFastAgentLaunch` re-checks
+ * those digests, atomically claims the warm mount via rename, and spawns.
+ * Any doubt — missing plan, changed digest, set env var, claimed mount —
+ * returns null and the caller takes the full launch path, which rebuilds
+ * both the plan and the warm mount at exit. Correctness never depends on the
+ * fast path engaging; it only depends on the digests being strict enough to
+ * refuse when the slow path would have produced different session inputs.
+ */
+
+export const LAUNCH_PLAN_SCHEMA_VERSION = 1;
+
+/** Mirrors persona-kit's skill-cache marker filename (see skill-cache.ts). */
+const SKILL_CACHE_MARKER_FILENAME = '.aw-skill-cache.json';
+/** Mirrors @relayfile/local-mount's mount marker filename. */
+const MOUNT_MARKER_FILENAME = '.relayfile-local-mount';
+
+export interface StatDigest {
+  path: string;
+  /** null = the path did not exist at plan time (and must still not exist). */
+  size: number | null;
+  mtimeMs: number | null;
+}
+
+export interface LaunchPlan {
+  schemaVersion: number;
+  cliVersion: string;
+  cwd: string;
+  selector: string;
+  personaId: string;
+  harness: string;
+  model: string;
+  /**
+   * Stat digests of every file/dir that feeds persona resolution or mount
+   * pattern construction. All must match exactly for the plan to be trusted.
+   */
+  digests: StatDigest[];
+  /**
+   * Env vars that fed resolution, pinned to their plan-time values
+   * (null = unset). Persona input names, workforce-home overrides, and — for
+   * harnesses where relay MCP injection applies — the RELAY_* config. Any
+   * difference at fast-launch time means the resolved spec could differ, so
+   * the fast path refuses.
+   */
+  envExact: Record<string, string | null>;
+  skillCache: {
+    dir: string;
+    fingerprint: string;
+    /** Raw AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL at plan time (null = unset). */
+    upstreamIntervalRaw: string | null;
+    /** Parsed interval; null = checks disabled. */
+    upstreamIntervalMs: number | null;
+  };
+  spawn: {
+    /** Absolute path resolved at plan time; must still exist. */
+    binPath: string;
+    args: string[];
+    /**
+     * Env vars layered over process.env for the child. Only persona-input
+     * values resolved from declared defaults land here — literal strings
+     * from the digest-pinned persona spec, never values sourced from the
+     * caller's environment.
+     */
+    envAdditions: Record<string, string>;
+  };
+  mount: {
+    warmDir: string;
+    ignoredPatterns: string[];
+    readonlyPatterns: string[];
+  };
+}
+
+export interface FastLaunch {
+  plan: LaunchPlan;
+  child: ChildProcess;
+  sessionRoot: string;
+  mountDir: string;
+  /** Path to the claimed autosync state snapshot from the previous session. */
+  statePath: string;
+  startedAt: number;
+}
+
+function agentworkforceCacheRoot(): string {
+  return join(homedir(), '.agentworkforce', 'workforce', 'cache');
+}
+
+export function launchPlanKey(cwd: string, selector: string): string {
+  return createHash('sha256').update(`${cwd}\0${selector}`).digest('hex').slice(0, 32);
+}
+
+export function launchPlanPath(cwd: string, selector: string): string {
+  return join(agentworkforceCacheRoot(), 'launch-plans', `${launchPlanKey(cwd, selector)}.json`);
+}
+
+export function warmMountDir(cwd: string, selector: string): string {
+  return join(agentworkforceCacheRoot(), 'warm-mounts', launchPlanKey(cwd, selector));
+}
+
+export function statDigestOf(path: string): StatDigest {
+  try {
+    const st = statSync(path);
+    return { path, size: st.size, mtimeMs: st.mtimeMs };
+  } catch {
+    return { path, size: null, mtimeMs: null };
+  }
+}
+
+function statDigestStillHolds(digest: StatDigest): boolean {
+  const current = statDigestOf(digest.path);
+  return current.size === digest.size && current.mtimeMs === digest.mtimeMs;
+}
+
+function readCliVersion(): string | null {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+    ) as { version?: unknown };
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Cheap re-validation of the persisted skill cache: the marker must carry the
+ * same fingerprint the plan was built against, and the TTL'd upstream drift
+ * check must not be due (running it needs the network and the full CLI).
+ */
+function skillCacheStillValid(plan: LaunchPlan): boolean {
+  const rawInterval = process.env.AGENTWORKFORCE_SKILL_CACHE_CHECK_INTERVAL ?? null;
+  if (rawInterval !== plan.skillCache.upstreamIntervalRaw) return false;
+  const marker = readJsonFile(join(plan.skillCache.dir, SKILL_CACHE_MARKER_FILENAME)) as {
+    fingerprint?: unknown;
+    lastUpstreamCheckAt?: unknown;
+    installedAt?: unknown;
+  } | null;
+  if (!marker || marker.fingerprint !== plan.skillCache.fingerprint) return false;
+  const intervalMs = plan.skillCache.upstreamIntervalMs;
+  if (intervalMs === null) return true;
+  const reference =
+    typeof marker.lastUpstreamCheckAt === 'string'
+      ? Date.parse(marker.lastUpstreamCheckAt)
+      : typeof marker.installedAt === 'string'
+        ? Date.parse(marker.installedAt)
+        : NaN;
+  if (!Number.isFinite(reference)) return false;
+  return Date.now() - reference < intervalMs;
+}
+
+function generateFastSessionRoot(personaId: string): string {
+  const sessionId = `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+  return join(homedir(), '.agentworkforce', 'workforce', 'sessions', `${personaId}-${sessionId}`);
+}
+
+function perfMark(label: string): void {
+  if (process.env.AGENTWORKFORCE_PERF !== '1') return;
+  process.stderr.write(`[perf] +${performance.now().toFixed(1)}ms ${label}\n`);
+}
+
+/**
+ * Attempt the warm fast launch for `agentworkforce agent <selector>`.
+ *
+ * Returns the spawned child (plus everything the post-spawn bookkeeping
+ * needs) when every validation held and the warm mount was claimed, or null
+ * when the caller must run the full launch path. Never throws for "plan is
+ * stale" conditions — only for programmer errors.
+ */
+export function tryFastAgentLaunch(rest: readonly string[]): FastLaunch | null {
+  // Any flag beyond a bare selector changes launch semantics → full path.
+  if (rest.length !== 1 || rest[0].startsWith('-')) return null;
+  const selector = rest[0];
+  const cwd = process.cwd();
+
+  const plan = readJsonFile(launchPlanPath(cwd, selector)) as LaunchPlan | null;
+  if (!plan || plan.schemaVersion !== LAUNCH_PLAN_SCHEMA_VERSION) return null;
+  if (plan.cwd !== cwd || plan.selector !== selector) return null;
+  const cliVersion = readCliVersion();
+  if (!cliVersion || plan.cliVersion !== cliVersion) return null;
+  if (process.env.AGENTWORKFORCE_NO_SKILL_CACHE === '1') return null;
+
+  for (const [name, pinned] of Object.entries(plan.envExact)) {
+    if ((process.env[name] ?? null) !== pinned) return null;
+  }
+  for (const digest of plan.digests) {
+    if (!statDigestStillHolds(digest)) return null;
+  }
+  if (!skillCacheStillValid(plan)) return null;
+  if (!existsSync(plan.spawn.binPath)) return null;
+
+  const warmDir = plan.mount.warmDir;
+  const warmMount = join(warmDir, 'mount');
+  const warmState = join(warmDir, 'state.json');
+  if (!existsSync(join(warmMount, MOUNT_MARKER_FILENAME))) return null;
+  if (!existsSync(warmState)) return null;
+
+  perfMark('fast-launch: plan validated');
+
+  // Claim the warm mount by renaming it into a fresh session root. rename is
+  // atomic on the same volume, so a concurrent launch of the same persona
+  // loses the race cleanly (ENOENT) and takes the full path instead.
+  const sessionRoot = generateFastSessionRoot(plan.personaId);
+  const mountDir = join(sessionRoot, 'mount');
+  const statePath = join(sessionRoot, 'warm-state.json');
+  try {
+    mkdirSync(sessionRoot, { recursive: true });
+    renameSync(warmMount, mountDir);
+  } catch {
+    try {
+      rmSync(sessionRoot, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+    return null;
+  }
+  try {
+    renameSync(warmState, statePath);
+  } catch {
+    // Without the state snapshot a reattach could resurrect files deleted
+    // from the project while the mount sat warm. Give the mount back and
+    // take the full path.
+    try {
+      renameSync(mountDir, warmMount);
+      rmSync(sessionRoot, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+    return null;
+  }
+
+  perfMark('fast-launch: warm mount claimed');
+
+  try {
+    const child = spawn(plan.spawn.binPath, plan.spawn.args, {
+      cwd: mountDir,
+      stdio: 'inherit',
+      env: Object.keys(plan.spawn.envAdditions).length > 0
+        ? { ...process.env, ...plan.spawn.envAdditions }
+        : process.env
+    });
+    perfMark('fast-launch: harness child spawning');
+    return {
+      plan,
+      child,
+      sessionRoot,
+      mountDir,
+      statePath,
+      startedAt: Date.now()
+    };
+  } catch {
+    // Spawn failed synchronously — return the mount so the warm cache
+    // survives, then fall back to the full path.
+    try {
+      renameSync(statePath, warmState);
+      renameSync(mountDir, warmMount);
+      rmSync(sessionRoot, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+    return null;
+  }
+}
+
+/**
+ * Persist a launch plan (0600 — it holds no secrets by construction, but
+ * there's no reason to share it either). Written by the full launch path
+ * after a successful session.
+ */
+export function writeLaunchPlan(plan: LaunchPlan): void {
+  const path = launchPlanPath(plan.cwd, plan.selector);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`, { mode: 0o600 });
+}
+
+/** Remove a stale plan so the next launch takes the full path. */
+export function deleteLaunchPlan(cwd: string, selector: string): void {
+  try {
+    rmSync(launchPlanPath(cwd, selector), { force: true });
+  } catch {
+    /* best effort */
+  }
+}

From 4da394988c0ab0566cf4a5f54911ac6c556bef69 Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Sun, 12 Jul 2026 21:49:24 -0400
Subject: [PATCH 2/5] fix(cli): resolve fast-session exit even when the child
 exits during module load

The harness child spawns before cli-impl loads; a child that exits
during that import has already emitted 'close', so the resume must read
the settled exitCode/signalCode instead of waiting forever for an event
that fired with no listener.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/cli/src/cli-impl.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/cli/src/cli-impl.ts b/packages/cli/src/cli-impl.ts
index 24650c1e..91391a1b 100644
--- a/packages/cli/src/cli-impl.ts
+++ b/packages/cli/src/cli-impl.ts
@@ -3564,6 +3564,18 @@ export async function resumeFastSession(fast: FastLaunch): Promise<never> {
   process.on('SIGINT', sigintHandler);
 
   const exitCodePromise = new Promise<number>((resolve) => {
+    // The child was spawned before this module even loaded; if it already
+    // exited (its 'close' fired while the import was in flight), the settled
+    // state is on the object — waiting for an event that already happened
+    // would hang the teardown forever.
+    if (child.exitCode !== null) {
+      resolve(child.exitCode);
+      return;
+    }
+    if (child.signalCode) {
+      resolve(signalExitCode(child.signalCode));
+      return;
+    }
     child.on('error', () => resolve(127));
     child.on('close', (code, signal) => {
       if (typeof code === 'number') resolve(code);

From ab26eb86459f609771402ab905e73917a3d3fd73 Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Sun, 12 Jul 2026 22:26:10 -0400
Subject: [PATCH 3/5] fix(cli): harden the warm fast path per review

- Corrupted/truncated launch plans fall back to the full launch instead
  of throwing (blanket guard in tryFastAgentLaunch)
- Digest every persona JSON in every source layer, not just the winning
  file: same-id layers merge, and in-place edits don't touch dir mtimes.
  Directory digests pin size to 0 (filesystem-dependent noise)
- Path-form sidecars (claudeMd/agentsMd file refs) make a launch
  ineligible for plan caching until those files join the digest set
- Park async child spawn errors in fast-launch so an early 'error' can't
  crash during the heavy import and the session manager resolves 127
- A failed drain/sync-back after a clean harness exit returns exit code
  1 instead of masquerading as success (matches the cold path)
- persona-kit: bump @relayfile/local-mount to ^0.11.0 so pnpm hoists a
  single copy alongside the CLI's

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/cli/src/cli-impl.ts         | 36 ++++++++++++++++--
 packages/cli/src/fast-launch.test.ts | 55 ++++++++++++++++++++++++++++
 packages/cli/src/fast-launch.ts      | 30 ++++++++++++++-
 packages/persona-kit/package.json    |  2 +-
 4 files changed, 117 insertions(+), 6 deletions(-)

diff --git a/packages/cli/src/cli-impl.ts b/packages/cli/src/cli-impl.ts
index 91391a1b..1c5d9dc6 100644
--- a/packages/cli/src/cli-impl.ts
+++ b/packages/cli/src/cli-impl.ts
@@ -1668,6 +1668,11 @@ function buildFastLaunchPlan(input: {
   if (input.selection.inputValues !== undefined) return null;
   if (input.selection.env !== undefined) return null;
   if (input.selection.mcpServers !== undefined) return null;
+  // Path-form sidecars are read from disk at materialization time; until
+  // those files are folded into the digest set, editing one must not be
+  // able to slip past a cached plan.
+  if (input.selection.claudeMd !== undefined) return null;
+  if (input.selection.agentsMd !== undefined) return null;
   if (!input.skillCacheDir || !input.skillCacheFingerprint) return null;
   // Opencode ignores relay MCP injection entirely; every other harness wires
   // it into argv (tokens included), so those are only eligible with relay
@@ -1703,7 +1708,20 @@ function buildFastLaunchPlan(input: {
   const { directories, config } = buildPersonaSourceDirectories();
   digests.push(statDigestOf(config.configPath));
   for (const dir of directories) {
+    // Dir mtime witnesses entry add/remove/rename; per-file digests below
+    // witness in-place edits, which don't touch the parent dir's stat.
     digests.push(statDigestOf(dir.dir));
+    let entries: string[];
+    try {
+      entries = readdirSync(dir.dir);
+    } catch {
+      continue;
+    }
+    // Persona ids live in file contents and same-id layers merge across
+    // dirs, so every persona JSON in every layer is a resolution input.
+    for (const name of entries) {
+      if (name.endsWith('.json')) digests.push(statDigestOf(join(dir.dir, name)));
+    }
   }
   // Dotfiles shape the mount patterns. Persona ids are kebab-case, so the
   // per-agent filenames need no sanitization here.
@@ -3565,9 +3583,14 @@ export async function resumeFastSession(fast: FastLaunch): Promise<never> {
 
   const exitCodePromise = new Promise<number>((resolve) => {
     // The child was spawned before this module even loaded; if it already
-    // exited (its 'close' fired while the import was in flight), the settled
-    // state is on the object — waiting for an event that already happened
-    // would hang the teardown forever.
+    // exited or failed (its 'close'/'error' fired while the import was in
+    // flight), the settled state is on the object / the fast-launch parking
+    // slot — waiting for an event that already happened would hang the
+    // teardown forever.
+    if (fast.spawnFailure.error) {
+      resolve(127);
+      return;
+    }
     if (child.exitCode !== null) {
       resolve(child.exitCode);
       return;
@@ -3701,6 +3724,7 @@ export async function resumeFastSession(fast: FastLaunch): Promise<never> {
   const exitCode = await exitCodePromise;
   perfMark('exit: harness child exited');
 
+  let teardownFailed = false;
   isSyncing = true;
   syncSpinner = ora({
     text: 'Syncing session changes back to the repo… (Ctrl-C to skip)',
@@ -3747,6 +3771,10 @@ export async function resumeFastSession(fast: FastLaunch): Promise<never> {
       syncSpinner.fail(`Sync did not complete: ${(err as Error).message}`);
       syncSpinner = undefined;
     }
+    // The harness may have succeeded, but its work didn't fully reach the
+    // repo — that must not read as a clean exit (the cold path returns
+    // non-zero for the same class of failure).
+    teardownFailed = true;
   } finally {
     process.removeListener('SIGINT', sigintHandler);
     if (handle) {
@@ -3771,7 +3799,7 @@ export async function resumeFastSession(fast: FastLaunch): Promise<never> {
       }
     });
   }
-  process.exit(exitCode);
+  process.exit(teardownFailed && exitCode === 0 ? 1 : exitCode);
 }
 
 interface LocalPersonaImproverContext {
diff --git a/packages/cli/src/fast-launch.test.ts b/packages/cli/src/fast-launch.test.ts
index 81ff1284..8f237aff 100644
--- a/packages/cli/src/fast-launch.test.ts
+++ b/packages/cli/src/fast-launch.test.ts
@@ -167,3 +167,58 @@ test('tryFastAgentLaunch: valid-looking plan still refuses without a warm mount'
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('tryFastAgentLaunch: corrupted or truncated plans fall back instead of throwing', () => {
+  const selector = 'fast-launch-corrupt-plan-persona';
+  const planPath = launchPlanPath(process.cwd(), selector);
+  const version = (JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+  ) as { version: string }).version;
+  try {
+    mkdirSync(join(planPath, '..'), { recursive: true });
+    // Not JSON at all.
+    writeFileSync(planPath, '{not json');
+    assert.equal(tryFastAgentLaunch([selector]), null);
+    // Valid JSON, right version/selector, but missing whole sections.
+    writeFileSync(
+      planPath,
+      JSON.stringify({
+        schemaVersion: LAUNCH_PLAN_SCHEMA_VERSION,
+        cliVersion: version,
+        cwd: process.cwd(),
+        selector
+      })
+    );
+    assert.equal(tryFastAgentLaunch([selector]), null);
+    // Sections present but null.
+    writeFileSync(
+      planPath,
+      JSON.stringify({
+        schemaVersion: LAUNCH_PLAN_SCHEMA_VERSION,
+        cliVersion: version,
+        cwd: process.cwd(),
+        selector,
+        digests: null,
+        envExact: null,
+        skillCache: null,
+        spawn: null,
+        mount: null
+      })
+    );
+    assert.equal(tryFastAgentLaunch([selector]), null);
+  } finally {
+    deleteLaunchPlan(process.cwd(), selector);
+  }
+});
+
+test('statDigestOf: directories digest with size pinned to 0', () => {
+  const dir = tempDir();
+  try {
+    writeFileSync(join(dir, 'entry.txt'), 'content');
+    const digest = statDigestOf(dir);
+    assert.equal(digest.size, 0);
+    assert.notEqual(digest.mtimeMs, null);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/packages/cli/src/fast-launch.ts b/packages/cli/src/fast-launch.ts
index f587730c..c0c23858 100644
--- a/packages/cli/src/fast-launch.ts
+++ b/packages/cli/src/fast-launch.ts
@@ -101,6 +101,12 @@ export interface FastLaunch {
   mountDir: string;
   /** Path to the claimed autosync state snapshot from the previous session. */
   statePath: string;
+  /**
+   * Set when the child emitted 'error' before the session manager attached
+   * its listeners (e.g. the recorded binary vanished between the existence
+   * check and the spawn). The session manager treats it as exit code 127.
+   */
+  spawnFailure: { error: Error | null };
   startedAt: number;
 }
 
@@ -123,7 +129,10 @@ export function warmMountDir(cwd: string, selector: string): string {
 export function statDigestOf(path: string): StatDigest {
   try {
     const st = statSync(path);
-    return { path, size: st.size, mtimeMs: st.mtimeMs };
+    // Directory digests only witness entry add/remove/rename via mtime —
+    // size is filesystem-dependent noise, so pin it. Content edits inside a
+    // directory are covered by per-file digests on the plan side.
+    return { path, size: st.isDirectory() ? 0 : st.size, mtimeMs: st.mtimeMs };
   } catch {
     return { path, size: null, mtimeMs: null };
   }
@@ -198,6 +207,17 @@ function perfMark(label: string): void {
  * stale" conditions — only for programmer errors.
  */
 export function tryFastAgentLaunch(rest: readonly string[]): FastLaunch | null {
+  // The contract is "never throw for stale-plan conditions" — and a
+  // corrupted or hand-edited plan file is exactly such a condition, so the
+  // whole validation runs under a blanket fallback.
+  try {
+    return tryFastAgentLaunchInner(rest);
+  } catch {
+    return null;
+  }
+}
+
+function tryFastAgentLaunchInner(rest: readonly string[]): FastLaunch | null {
   // Any flag beyond a bare selector changes launch semantics → full path.
   if (rest.length !== 1 || rest[0].startsWith('-')) return null;
   const selector = rest[0];
@@ -269,6 +289,13 @@ export function tryFastAgentLaunch(rest: readonly string[]): FastLaunch | null {
         ? { ...process.env, ...plan.spawn.envAdditions }
         : process.env
     });
+    // Park async spawn failures until resumeFastSession attaches its own
+    // listeners: an unhandled 'error' during the heavy import would crash
+    // the process, and the exit promise must be able to observe it later.
+    const spawnFailure: { error: Error | null } = { error: null };
+    child.once('error', (err) => {
+      spawnFailure.error = err;
+    });
     perfMark('fast-launch: harness child spawning');
     return {
       plan,
@@ -276,6 +303,7 @@ export function tryFastAgentLaunch(rest: readonly string[]): FastLaunch | null {
       sessionRoot,
       mountDir,
       statePath,
+      spawnFailure,
       startedAt: Date.now()
     };
   } catch {
diff --git a/packages/persona-kit/package.json b/packages/persona-kit/package.json
index 1b8faa56..c259d402 100644
--- a/packages/persona-kit/package.json
+++ b/packages/persona-kit/package.json
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@relayfile/adapter-core": "^0.3.60",
-    "@relayfile/local-mount": "^0.7.24"
+    "@relayfile/local-mount": "^0.11.0"
   },
   "devDependencies": {
     "ts-json-schema-generator": "^2.3.0"

From 3401fb24ef891d4c5226f043c86db6703e1456d3 Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Mon, 13 Jul 2026 06:59:37 -0400
Subject: [PATCH 4/5] chore(cli): consume published @relayfile/local-mount
 0.10.23

The relayfile release train shipped the fast-launch changes as 0.10.23
(lockstep patch), not the 0.11.0 this branch anticipated. Ranges in cli
and persona-kit now track ^0.10.23 and the lockfile resolves the
published package. Cold/warm E2E re-verified against the npm tarball:
2.8s cold, ~20ms warm to harness spawn in relay.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CHANGELOG.md                      |  2 +-
 packages/cli/package.json         |  2 +-
 packages/persona-kit/package.json |  2 +-
 pnpm-lock.yaml                    | 14 +++++++-------
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7e09704..377ee6ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   cache into the mount; and cloud subcommand handlers load lazily off the
   launch path. In the relay repo, launch-to-harness went from ~26s to ~2.5s
   cold and ~20ms warm, and session teardown from ~11s to under 1s.
-- `@agentworkforce/cli`: requires `@relayfile/local-mount` ^0.11.0
+- `@agentworkforce/cli`: requires `@relayfile/local-mount` ^0.10.23
   (git-list population, `attachMount`, exported autosync state, and the
   external-teardown safety guard).
diff --git a/packages/cli/package.json b/packages/cli/package.json
index bf73b6a1..7e1fd754 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -16,7 +16,7 @@
     "@agentworkforce/runtime": "workspace:*",
     "@agentworkforce/workload-router": "workspace:*",
     "@relayburn/sdk": "^2.5.2",
-    "@relayfile/local-mount": "^0.11.0",
+    "@relayfile/local-mount": "^0.10.23",
     "ora": "^9.4.0"
   },
   "repository": {
diff --git a/packages/persona-kit/package.json b/packages/persona-kit/package.json
index c259d402..0a4fab6a 100644
--- a/packages/persona-kit/package.json
+++ b/packages/persona-kit/package.json
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@relayfile/adapter-core": "^0.3.60",
-    "@relayfile/local-mount": "^0.11.0"
+    "@relayfile/local-mount": "^0.10.23"
   },
   "devDependencies": {
     "ts-json-schema-generator": "^2.3.0"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3d3ac4d2..0df7ef67 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -56,8 +56,8 @@ importers:
         specifier: ^2.5.2
         version: 2.5.2
       '@relayfile/local-mount':
-        specifier: ^0.7.24
-        version: 0.7.24
+        specifier: ^0.10.23
+        version: 0.10.23
       ora:
         specifier: ^9.4.0
         version: 9.4.0
@@ -121,8 +121,8 @@ importers:
         specifier: ^0.3.60
         version: 0.3.60(@relayfile/sdk@0.7.40)
       '@relayfile/local-mount':
-        specifier: ^0.7.24
-        version: 0.7.24
+        specifier: ^0.10.23
+        version: 0.10.23
     devDependencies:
       ts-json-schema-generator:
         specifier: ^2.3.0
@@ -987,8 +987,8 @@ packages:
     resolution: {integrity: sha512-vY48SxZgahnvE0CHDyy/iny17ypnfbX5myVPtocZVNpMiz4dS1iabO70WR+uYVgSiIZR7MpKTPFSs3SxEjQWag==}
     engines: {node: '>=18'}
 
-  '@relayfile/local-mount@0.7.24':
-    resolution: {integrity: sha512-h2ac/frfSFgjrKDSBCkmMHjphx19XZrHrSjaI29wlTzSblfiE65MQST47lS6Fm1+K9yap+W+msUi8JRIYYWFEw==}
+  '@relayfile/local-mount@0.10.23':
+    resolution: {integrity: sha512-eWy52O7Dt1Vwy162IJCbGAoSFFejNVVOy4eMrNEmIWld+YMdpR0hEvuplKP0O75xwD8be4PJcADoedi3X1R9Ng==}
     engines: {node: '>=18'}
 
   '@relayfile/relay-helpers@0.4.2':
@@ -3323,7 +3323,7 @@ snapshots:
 
   '@relayfile/core@0.7.40': {}
 
-  '@relayfile/local-mount@0.7.24':
+  '@relayfile/local-mount@0.10.23':
     dependencies:
       '@parcel/watcher': 2.5.6
       ignore: 7.0.5

From 6c6dc7e9390b64a36050420f741286c3322de316 Mon Sep 17 00:00:00 2001
From: Will Washburn <will.washburn@gmail.com>
Date: Mon, 13 Jul 2026 07:13:06 -0400
Subject: [PATCH 5/5] fix(cli): split PATH on the platform delimiter in
 resolveBinOnPath
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Windows PATHEXT shims stay unresolved by design — the warm fast path
simply never engages there and launches take the full path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/cli/src/cli-impl.ts | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/cli/src/cli-impl.ts b/packages/cli/src/cli-impl.ts
index 1c5d9dc6..0c4902e1 100644
--- a/packages/cli/src/cli-impl.ts
+++ b/packages/cli/src/cli-impl.ts
@@ -19,7 +19,7 @@ import {
   type Dirent
 } from 'node:fs';
 import { constants, homedir, tmpdir } from 'node:os';
-import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
+import { delimiter as pathDelimiter, dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import {
@@ -1613,10 +1613,14 @@ interface RunInteractiveCapture {
 const SKILL_LOCAL_MD_RE = /\.md$/i;
 const SKILL_URL_PREFIX_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 
-/** Resolve a bare binary name to its absolute PATH entry, or null. */
+/**
+ * Resolve a bare binary name to its absolute PATH entry, or null. No PATHEXT
+ * handling: on Windows this returns null for `.cmd`/`.exe` shims, which just
+ * means the warm fast path never engages there — launches take the full path.
+ */
 function resolveBinOnPath(bin: string): string | null {
   if (isAbsolute(bin)) return existsSync(bin) ? bin : null;
-  for (const dir of (process.env.PATH ?? '').split(':')) {
+  for (const dir of (process.env.PATH ?? '').split(pathDelimiter)) {
     if (!dir) continue;
     const candidate = join(dir, bin);
     try {