prizmkit 1.1.107 → 1.1.108

package/bundled/skills/refactor-workflow/SKILL.md

@@ -1,61 +1,90 @@
 ---
 name: "refactor-workflow"
-description: "One-stop entry point for code refactoring. Brainstorms refactoring goals with the user until fully clarified, then orchestrates refactor-planner → refactor-pipeline-launcher → execution. Handles multi-refactor batch development from a single request. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'."
+description: "Triage-based refactor workflow. Clarifies behavior-preserving refactoring goals, then lets the user choose Fast Path for simple current-session/current-workspace refactors or Pipeline Path for complex/batch refactors via refactor-planner → refactor-pipeline-launcher. Use when the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'."
 ---
 
 # Refactor Workflow
 
-One-stop entry point for code refactoring. Covers the complete journey from a rough refactoring idea to verified, behavior-preserving code changes: deep goal clarification → structured planning → autonomous pipeline execution.
+Triage-based entry point for code refactoring. The workflow clarifies behavior-preserving goals, assesses risk and scope, asks the user to choose an approach, then follows one of two paths:
+
+- **Fast Path** — a simple behavior-preserving refactor is implemented directly in the **current session** and **current workspace** with the normal PrizmKit lifecycle commands.
+- **Pipeline Path** — complex or batch refactors are planned with `refactor-planner`, launched with `refactor-pipeline-launcher`, then monitored.
+
+This skill keeps Fast Path and Pipeline Path separate. Pipeline monitoring only happens after the user selects Pipeline Path and the launcher starts execution.
 
 ## When to Use
 
 User says:
 - "Refactor the auth module", "Clean up this code", "Restructure the payment service"
 - "Extract shared logic into a separate module", "Optimize code structure"
+- "Do this small behavior-preserving cleanup now"
 - "Batch refactor these modules", "Code refactoring across multiple files"
 - Code has accumulated tech debt that needs structural improvement
 - Module needs to be split, merged, or reorganized
 
 **Do NOT use this skill when:**
-- User only wants to plan refactoring (use `refactor-planner` directly)
-- User only wants to launch pipeline for existing .prizmkit/plans/refactor-list.json (use `refactor-pipeline-launcher`)
-- User wants to add features (use `feature-workflow`)
-- User wants to fix bugs (use `bug-planner` + `bugfix-pipeline-launcher`)
+- User only wants to plan refactoring without execution → use `refactor-planner` directly
+- User only wants to launch an existing `.prizmkit/plans/refactor-list.json` → use `refactor-pipeline-launcher`
+- User wants to add features → use `feature-workflow`
+- User wants to fix bugs → use `bug-fix-workflow` or `bug-planner` + `bugfix-pipeline-launcher`
 
 ---
 
 ## Overview
 
-Four phases take a rough refactoring idea to verified, behavior-preserving code so the user doesn't have to manually chain planner → launcher → monitoring:
+The shared contract is:
+
+1. **Brainstorm** — clarify refactoring type, collect reference materials, read relevant code/docs/tests, and confirm behavior-preservation requirements.
+2. **Assess difficulty and behavior risk** — decide whether the request is a simple behavior-preserving Fast Path candidate or a complex/batch Pipeline Path candidate.
+3. **AskUserQuestion approach selection** — present selectable options; never silently choose the path.
+4. **Execute selected path**:
+   - **Fast Path**: `/prizmkit-plan` → `/prizmkit-implement` with behavior-preservation tests/checks → `/prizmkit-code-review` → `/prizmkit-retrospective` → `/prizmkit-committer` in the current workspace.
+   - **Pipeline Path**: `refactor-planner` → `refactor-pipeline-launcher` → monitoring.
+
+### Terminology
 
-1. **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code → fully clarified refactoring goals
-2. **Plan** — call `refactor-planner` → `.prizmkit/plans/refactor-list.json` with N refactor items
-3. **Launch** — call `refactor-pipeline-launcher` → pipeline started (execution mode chosen by user via launcher)
-4. **Monitor** — track progress → status updates, completion report
+| Term | Meaning |
+|------|---------|
+| **Fast Path** | Current-session/current-workspace implementation for simple, behavior-preserving refactors. It does not create or consume `.prizmkit/plans/refactor-list.json` and does not start the refactor pipeline. |
+| **Pipeline Path** | Complex or batch refactor execution. Planner handoff goes to `refactor-planner`; launcher handoff goes to `refactor-pipeline-launcher`; monitoring follows only after launch. |
+| **Current session** | The interactive AI CLI session that is already discussing the refactor with the user. |
+| **Current workspace** | The current git checkout and working tree, not a background pipeline worktree/session. |
+| **Behavior preservation** | External behavior, public contracts, tests, and user-visible outcomes remain unchanged unless the user explicitly approves a behavior change as a feature. |
+| **Monitoring** | Status/log follow-up for a launched refactor pipeline; it is not part of the Fast Path. |
 
-### Branch Management
+### Workspace and Branch Model
 
-The dev-pipeline handles branch management per-refactor automatically:
-- Each refactor item is implemented on its own branch by the pipeline
-- Branches are created, committed, and managed by the pipeline session
-- This workflow does NOT create a top-level branch — the pipeline manages granular per-refactor branches
+- **Fast Path**: work happens in the current workspace and current interactive session. Use the current branch unless the project policy or user explicitly asks to create a branch.
+- **Pipeline Path**: `refactor-pipeline-launcher` and the dev-pipeline manage per-refactor branches/worktrees. This workflow does not create a top-level branch before handing off to the launcher.
 
 ---
 
 ## Input Modes
 
-**Mode A: From natural language description** (default)
+**Mode A: Natural language refactoring goal** (default)
 
 Natural language description of the refactoring goals. Can be:
+- A simple behavior-preserving refactor: "Extract this helper function and keep behavior unchanged"
 - A module target: "Refactor the auth module — extract shared middleware, simplify the token flow"
 - A batch of refactors: "Clean up the payment service, decouple the notification module, and extract common utilities"
 - An incremental request: "Also refactor the logging layer to use structured logging"
 
-Flow: brainstorm → refactor-planner → refactor-pipeline-launcher → monitor
+Flow: brainstorm → complexity/behavior-risk assessment → AskUserQuestion → Fast Path or Pipeline Path.
 
-**Mode B: From existing `.prizmkit/plans/refactor-list.json`** — user says "run pipeline from existing file", or the file already exists. Skip ahead per the [Resume table](#resume--interruption-recovery).
+**Mode B: Existing `.prizmkit/plans/refactor-list.json`**
 
-**Mode C: Incremental (add to existing refactor plan)** — user says "add more refactors". Brainstorm new goals, then invoke `refactor-planner` in incremental mode (appends to existing list) → launch → monitor.
+When the user says "run pipeline from existing file" or `.prizmkit/plans/refactor-list.json` already exists and should be executed:
+- Skip brainstorm and `refactor-planner`
+- Invoke `refactor-pipeline-launcher` directly
+- Monitor and report progress
+
+**Mode C: Incremental refactor request**
+
+When user says "add more refactors":
+- Brainstorm only the new refactoring goals
+- Assess whether the new scope is simple and behavior-preserving enough for Fast Path
+- For simple work: use Fast Path in the current workspace
+- For complex or batch work: invoke `refactor-planner` in incremental mode, then `refactor-pipeline-launcher`
 
 ---
 
@@ -79,6 +108,7 @@ Then ask:
 - **What** code needs restructuring (modules, files, patterns)
 - **Why** it needs refactoring (tech debt, coupling, complexity, readability, performance structure)
 - **What outcome** they want (target architecture, desired structure, quality goals)
+- **What behavior must remain unchanged** (public APIs, outputs, workflows, tests, performance-sensitive paths)
 
 ### Step 1.2: Collect Reference Materials
 
@@ -95,6 +125,7 @@ Ask:
 2. **Design documents** — "Do you have any design docs, architecture diagrams, or refactoring proposals I should read?"
 3. **Knowledge docs** — "Are there related `.prizmkit/prizm-docs/`, README files, or internal wiki pages for the target area?"
 4. **Related issues/PRs** — "Any related issues, PRs, or previous refactoring attempts I should be aware of?"
+5. **Behavior checks** — "Which tests, commands, or manual scenarios prove behavior must stay the same?"
 
 Record everything the user provides — these become inputs for Step 1.3.
 
@@ -121,23 +152,26 @@ Read `${SKILL_DIR}/references/brainstorm-guide.md` §Completion Signs for the fu
 
 Once brainstorming is complete, produce a structured goals summary. Read `${SKILL_DIR}/references/brainstorm-guide.md` §Refactoring Goals Summary Template for the structured output format. Present the summary to the user and get explicit confirmation before proceeding.
 
+The summary must include behavior-preservation expectations: tests to run, public contracts to keep stable, and any explicitly approved behavior changes. If behavior changes are required, route them as feature work rather than refactoring unless the user explicitly scopes them here.
+
 **CHECKPOINT CP-RW-0**: Refactoring goals fully clarified and confirmed by user.
 
 ---
 
 ### Step 1.7: Complexity Assessment & Approach Selection
 
-After confirming refactoring goals, assess whether this refactor needs the full pipeline or can be done directly in the current session.
+After confirming refactoring goals, assess whether this refactor needs the Pipeline Path or can be done directly in the current session/current workspace.
 
-**Simple refactor → Fast Path candidate** (ALL must be true):
+**Simple behavior-preserving refactor → Fast Path candidate** (ALL must be true):
 - Single module, no cross-module impact
 - ≤3 files affected
 - No public API or interface changes
 - Straightforward transformation (extract method, rename, move file, simplify logic)
-- Existing tests fully cover the affected code paths
-- No risk of behavior change
+- Existing tests or focused checks cover the affected behavior
+- No behavior change risk beyond what tests/checks can verify
 
-**Complex refactor → Planning Path** (ANY is true):
+**Complex or batch refactors → Pipeline Path candidate** (ANY is true):
+- Multiple refactor items or batch refactoring request
 - Cross-module impact (>2 modules affected)
 - Public API or interface changes required
 - Multiple interrelated refactoring steps with dependency ordering
@@ -145,48 +179,56 @@ After confirming refactoring goals, assess whether this refactor needs the full
 - Insufficient test coverage in target area (risk of hidden behavior changes)
 - Requires coordination with other ongoing work
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment ("This refactoring appears straightforward…" for simple, "This refactoring is complex and will benefit from structured planning…" for complex), but the two options are always the same:
+**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment: for a simple refactor, "This refactor appears straightforward and behavior-preserving enough for the current-session Fast Path." For a complex or batch refactor, "This refactor is complex or batch-oriented and should use the Pipeline Path."
 
 ```
 AskUserQuestion:
-  question: <tailored to simple vs complex assessment>
+  question: "How would you like to proceed?"
   header: "Approach"
   options:
-    - label: "Refactor now (fast path)"
-      description: "Plan and refactor directly in this session using /prizmkit-plan + /prizmkit-implement"
-    - label: "Add to refactor list (pipeline)"
-      description: "Generate .prizmkit/plans/refactor-list.json via refactor-planner, then launch pipeline for autonomous execution"
+    - label: "Refactor now (Fast Path — current session/current workspace)"
+      description: "Run /prizmkit-plan → /prizmkit-implement → /prizmkit-code-review → /prizmkit-retrospective → /prizmkit-committer directly in this workspace with behavior-preservation checks"
+    - label: "Use Pipeline Path (refactor-planner → refactor-pipeline-launcher)"
+      description: "Generate .prizmkit/plans/refactor-list.json with refactor-planner, then launch autonomous execution with refactor-pipeline-launcher"
 ```
 
-- **Refactor now** → Fast Path: `/prizmkit-plan` (goals → `spec.md` + `plan.md`) → `/prizmkit-implement` (behavior preservation verified by tests) → `/prizmkit-code-review` → `/prizmkit-committer` (`refactor(<scope>):` prefix) → `/prizmkit-retrospective` (sync `.prizmkit/prizm-docs/`). **End workflow** — skip Phase 2/3/4.
-- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline).
+- **Refactor now (Fast Path)**:
+  1. Invoke `/prizmkit-plan` with the goals summary → generates `spec.md` + `plan.md` including behavior-preservation strategy
+  2. Invoke `/prizmkit-implement` to execute the plan in the current workspace and verify behavior stays unchanged
+  3. Run `/prizmkit-code-review` for quality and behavior-preservation review
+  4. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
+  5. Commit via `/prizmkit-committer` with `refactor(<scope>):` prefix
+  6. End workflow — do not call `refactor-planner`, do not call `refactor-pipeline-launcher`, and do not enter monitoring
+- **Use Pipeline Path** → Continue to Phase 2 (Planner handoff)
 
 **NEVER proceed without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 
-**CHECKPOINT CP-RW-0.5**: Approach selected by user (fast path or pipeline).
+**CHECKPOINT CP-RW-0.5**: Approach selected by user (Fast Path or Pipeline Path).
 
 ---
 
-## Phase 2: Plan
+## Phase 2: Plan — Pipeline Path Only
 
-**Goal**: Generate structured .prizmkit/plans/refactor-list.json from the clarified refactoring goals.
+**Goal**: Generate structured `.prizmkit/plans/refactor-list.json` from the clarified refactoring goals.
+
+Run this phase only when the user selected Pipeline Path or provided a batch/complex refactor request that they chose to send through the pipeline.
 
 **STEPS**:
 
-1. **Invoke `refactor-planner` skill** with the full goals summary from Phase 1:
+1. **Planner handoff — invoke `refactor-planner`** with the full goals summary from Phase 1:
    - Pass the structured goals summary as input — NOT the raw user conversation
    - For new refactoring: standard planning mode
    - For existing projects with `--incremental`: incremental planning mode
    - **Input**: Markdown goals summary (refactor targets, scope, behavior preservation strategy)
    - **Output**: `.prizmkit/plans/refactor-list.json` (schema: `dev-pipeline-refactor-list-v1`) containing `project_name`, `refactors[]` with id (R-NNN), title, description, scope, type, priority, complexity, behavior_preservation, acceptance_criteria, dependencies, status
 
-2. **Interactive planning** (if refactor-planner requires clarification):
-   - Because Phase 1 was thorough, refactor-planner should need minimal clarification
+2. **Interactive planning** (if `refactor-planner` requires clarification):
+   - Because Phase 1 was thorough, `refactor-planner` should need minimal clarification
    - If questions arise, answer from the Phase 1 context or pass through to user
 
 3. **Validate output**:
    - Confirm `.prizmkit/plans/refactor-list.json` exists
-   - Show summary: total refactor items, complexity distribution, dependencies
+   - Show summary: total refactor items, complexity distribution, dependencies, behavior-preservation coverage
 
 **CHECKPOINT CP-RW-1**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
@@ -194,15 +236,15 @@ AskUserQuestion:
 
 ---
 
-## Phase 3: Launch
+## Phase 3: Launch — Pipeline Path Only
 
-**Goal**: Start the refactoring pipeline.
+**Goal**: Start the refactoring pipeline after planner handoff has produced a validated refactor list.
 
 **STEPS**:
 
 1. **Show refactor summary** before launching:
    ```
-   Ready to launch pipeline with N refactor items:
+   Ready to launch Pipeline Path with N refactor items:
      R-001: Extract auth middleware (medium complexity)
      R-002: Decouple notification service (high complexity)
      R-003: Simplify token flow (low complexity)
@@ -210,10 +252,11 @@ AskUserQuestion:
    Proceed? (Y/n)
    ```
 
-2. **Invoke `refactor-pipeline-launcher` skill**:
+2. **Launcher handoff — invoke `refactor-pipeline-launcher`**:
    - **Input**: Path to validated `.prizmkit/plans/refactor-list.json`
    - The launcher handles all prerequisites checks
    - The launcher presents execution mode choices to the user (foreground/background/manual)
+   - The launcher preserves strict behavior-check defaults
    - Do NOT duplicate execution mode selection here — let the launcher handle it
    - **Output**: PID/status, log file path, execution mode selected
    - Returns PID/status and log file location
@@ -226,9 +269,9 @@ AskUserQuestion:
 
 ---
 
-## Phase 4: Monitor
+## Phase 4: Monitor — Pipeline Path Only
 
-**Goal**: Track pipeline progress and report to user.
+**Goal**: Track pipeline progress and report to user. Monitoring applies only after `refactor-pipeline-launcher` has started a pipeline.
 
 **STEPS**:
 
@@ -271,13 +314,14 @@ AskUserQuestion:
 The workflow supports resuming by detecting existing state:
 
 | State Found | Resume From |
-|-------------|------------|
-| No `.prizmkit/plans/refactor-list.json` | Phase 1: Brainstorm |
+|-------------|-------------|
+| Fast Path `spec.md` + `plan.md` exist, code not committed | Resume `/prizmkit-implement` / review / retrospective / commit based on current state |
+| No `.prizmkit/plans/refactor-list.json` and no Fast Path artifacts | Phase 1: Brainstorm |
 | `.prizmkit/plans/refactor-list.json` exists, no pipeline state | Phase 3: Launch |
 | `.prizmkit/plans/refactor-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
 | All refactors completed | Report completion, suggest next steps |
 
-**Resume**: If `.prizmkit/plans/refactor-list.json` exists, ask user: "Existing refactor plan found with N items. Resume pipeline or re-plan?"
+**Resume**: If `.prizmkit/plans/refactor-list.json` exists, ask user: "Existing refactor plan found with N items. Resume Pipeline Path or re-plan?" If Fast Path artifacts exist, ask whether to continue the current-workspace refactor or discard/re-plan.
 
 ---
 
@@ -300,21 +344,36 @@ While the pipeline runs, the user can continue the conversation:
 |-------|--------|
 | User's refactoring goal is too vague | Ask for more context: "Can you describe what's wrong with the current code structure?" |
 | Brainstorming stalls | Offer concrete options: "Would you prefer incremental or comprehensive refactoring?" |
-| No tests exist for target module | WARN user, recommend writing tests first before refactoring |
+| No tests exist for target module | WARN user, recommend writing tests/checks before Fast Path; consider Pipeline Path for risky refactors |
+| Fast Path starts risking behavior change | Pause and ask whether to switch to Pipeline Path (`refactor-planner` → `refactor-pipeline-launcher`) |
 | `refactor-planner` cannot parse goals | Refine the goals summary and retry |
 | `.prizmkit/plans/refactor-list.json` generation failed | Show error, retry with refined input |
 | Pipeline launch failed | Show daemon log, suggest manual start with `python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json` or `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json` |
 | All refactor items blocked/failed | Show status, suggest retrying specific items |
 | User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
-| Behavior regression detected during pipeline | Pipeline handles per-item — failed items are retried or reported |
+| Behavior regression detected during Fast Path | Revert or fix immediately before commit; refactoring cannot ship with behavior regression |
+| Behavior regression detected during pipeline | Pipeline handles per-item retries/failures; report failed items and behavior checks |
+
+---
 
+## HANDOFF
 
+| From | To | Condition |
+|------|----|-----------|
+| **this skill** | `/prizmkit-plan` | User selects Fast Path for simple behavior-preserving refactor work in the current workspace |
+| **this skill** | `/prizmkit-implement` | Fast Path plan is ready for current-session implementation with behavior checks |
+| **this skill** | `/prizmkit-code-review` | Fast Path refactor is complete and needs quality/behavior-preservation review |
+| **this skill** | `/prizmkit-retrospective` | Fast Path refactor changes need `.prizmkit/prizm-docs/` sync before commit |
+| **this skill** | `/prizmkit-committer` | Fast Path refactor is reviewed, docs are synced, and behavior preservation is verified |
+| **this skill** | `refactor-planner` | User selects Pipeline Path for complex or batch refactors |
+| `refactor-planner` | `refactor-pipeline-launcher` | Planner handoff produced validated `.prizmkit/plans/refactor-list.json` |
+| `refactor-pipeline-launcher` | **this skill** | Launcher handoff completed and monitoring/status follow-up is needed |
+
+---
 
 ## Output
 
-- Structured refactoring goals summary (Phase 1 artifact)
-- `.prizmkit/plans/refactor-list.json` (Phase 2 artifact)
-- Pipeline execution (Phase 3)
-- Progress updates (Phase 4)
-- Multiple git commits with `refactor(<scope>):` prefix
-- Updated `.prizmkit/prizm-docs/` (via prizmkit-retrospective per refactor item)
+Output depends on the selected path:
+
+- **Fast Path**: `spec.md` + `plan.md`, behavior-preserving current-workspace code changes, behavior test/check evidence, `/prizmkit-code-review` result, updated `.prizmkit/prizm-docs/`, and one `refactor(<scope>):` commit from `/prizmkit-committer`.
+- **Pipeline Path**: structured refactoring goals summary, `.prizmkit/plans/refactor-list.json`, pipeline execution via `refactor-pipeline-launcher`, monitoring updates, and per-refactor commits managed by the dev-pipeline.

package/bundled/templates/project-memory-template.md

@@ -30,7 +30,7 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
   3. Add a pointer in the parent L1 doc's SUBDIRS section
 
 ### Available Commands
-Run `/prizm-kit` to see all available PrizmKit commands.
+Run `/prizmkit` to see all available PrizmKit commands.
 
 ### Fast Path for Simple Changes
 Not every change needs the full spec -> plan workflow. Use fast path for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.107",
+  "version": "1.1.108",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/ai-cli-launch.js

@@ -0,0 +1,194 @@
+const BUILT_IN_AI_CLI_NAMES = new Set(['claude', 'cbc', 'codebuddy', 'codex']);
+
+function asText(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+export function tokenizeCliArgs(value = '') {
+  const text = asText(value);
+  if (!text.trim()) return [];
+
+  const tokens = [];
+  let current = '';
+  let quote = '';
+  let escaping = false;
+  let started = false;
+
+  for (const char of text) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      started = true;
+      continue;
+    }
+
+    if (char === '\\' && quote !== "'") {
+      escaping = true;
+      started = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = '';
+      } else {
+        current += char;
+      }
+      started = true;
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      started = true;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (started) {
+        tokens.push(current);
+        current = '';
+        started = false;
+      }
+      continue;
+    }
+
+    current += char;
+    started = true;
+  }
+
+  if (escaping) {
+    throw new Error('Invalid CLI arguments: trailing escape character');
+  }
+  if (quote) {
+    throw new Error(`Invalid CLI arguments: unclosed ${quote} quote`);
+  }
+  if (started) tokens.push(current);
+
+  return tokens;
+}
+
+export function formatCliArgsForPrompt(args = []) {
+  const tokens = Array.isArray(args) ? args : tokenizeCliArgs(asText(args));
+  return tokens.map((token) => {
+    const value = String(token);
+    if (value === '') return "''";
+    if (!/[\s'"\\]/.test(value)) return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+  }).join(' ');
+}
+
+function normalizeExecutable(aiCli) {
+  const trimmed = asText(aiCli).trim();
+  if (!trimmed) return '';
+  const tokens = tokenizeCliArgs(trimmed);
+  if (tokens.length !== 1) {
+    throw new Error('自定义 AI CLI 需要把可执行命令和额外参数分开填写；请把额外参数写入无头模式希望添加的参数。');
+  }
+  return tokens[0];
+}
+
+function executableBasename(aiCli) {
+  const executable = normalizeExecutable(aiCli);
+  return executable.split(/[\\/]/).pop()?.toLowerCase() || '';
+}
+
+export function isBuiltInAiCli(aiCli) {
+  if (!asText(aiCli).trim()) return false;
+  return BUILT_IN_AI_CLI_NAMES.has(executableBasename(aiCli));
+}
+
+export function isCustomAiCli(aiCli) {
+  return Boolean(asText(aiCli).trim()) && !isBuiltInAiCli(aiCli);
+}
+
+function normalizePromptArg(value) {
+  const raw = asText(value).trim();
+  if (!raw) {
+    throw new Error('自定义 AI CLI 需要同时填写可执行命令和提示词注入参数。');
+  }
+  const tokens = tokenizeCliArgs(raw);
+  if (tokens.length !== 1 || !tokens[0]) {
+    throw new Error('自定义 AI CLI 的提示词注入参数必须是一个 argv token，例如 -p 或 -i。');
+  }
+  return tokens[0];
+}
+
+function normalizeExtraArgs(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (typeof item !== 'string') {
+        throw new Error('自定义 AI CLI 的额外参数必须是字符串 argv token。');
+      }
+      return item;
+    });
+  }
+  return tokenizeCliArgs(asText(value));
+}
+
+export function storedAiCliLaunch(config = {}) {
+  const launch = config?.ai_cli_launch;
+  if (!launch || typeof launch !== 'object' || launch.profile !== 'custom') {
+    return null;
+  }
+  return {
+    profile: 'custom',
+    prompt_arg: asText(launch.prompt_arg),
+    extra_args: Array.isArray(launch.extra_args) ? [...launch.extra_args] : asText(launch.extra_args),
+  };
+}
+
+export function resolveAiCliLaunchSelection(aiCli, options = {}) {
+  const normalizedAiCli = normalizeExecutable(aiCli);
+  if (!normalizedAiCli) {
+    return { aiCli: '', aiCliLaunch: null };
+  }
+
+  if (isBuiltInAiCli(normalizedAiCli)) {
+    return { aiCli: normalizedAiCli, aiCliLaunch: null };
+  }
+
+  const existingLaunch = options.aiCliLaunch || options.existingLaunch || {};
+  const promptArg = options.headlessPromptArg
+    ?? options.promptArg
+    ?? existingLaunch.prompt_arg
+    ?? existingLaunch.promptArg
+    ?? '';
+  const extraArgs = options.headlessExtraArgs
+    ?? options.extraArgs
+    ?? existingLaunch.extra_args
+    ?? existingLaunch.extraArgs
+    ?? [];
+
+  return {
+    aiCli: normalizedAiCli,
+    aiCliLaunch: {
+      profile: 'custom',
+      prompt_arg: normalizePromptArg(promptArg),
+      extra_args: normalizeExtraArgs(extraArgs),
+    },
+  };
+}
+
+export function applyAiCliLaunchToConfig(existingConfig = {}, selection = {}) {
+  const nextConfig = { ...existingConfig };
+  const aiCli = asText(selection.aiCli).trim();
+
+  if (!aiCli) {
+    delete nextConfig.ai_cli;
+    delete nextConfig.ai_cli_launch;
+    return nextConfig;
+  }
+
+  nextConfig.ai_cli = aiCli;
+  if (selection.aiCliLaunch) {
+    nextConfig.ai_cli_launch = {
+      profile: 'custom',
+      prompt_arg: selection.aiCliLaunch.prompt_arg,
+      extra_args: [...selection.aiCliLaunch.extra_args],
+    };
+  } else {
+    delete nextConfig.ai_cli_launch;
+  }
+  return nextConfig;
+}