@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/cli/cli-commands/coder/planning/preparePlanningChanges.ts

@@ -0,0 +1,178 @@
+import { readFile, realpath } from 'fs/promises';
+import { relative } from 'path';
+import { isPromptToBeWritten } from '../../../../../scripts/run-codex-prompts/prompts/isPromptToBeWritten';
+import { PTBK_CODER_IGNORE_MARKER } from '../../../../../scripts/run-codex-prompts/prompts/loadPromptFiles';
+import { parsePromptFile } from '../../../../../scripts/run-codex-prompts/prompts/parsePromptFile';
+import { formatPromptEmojiTag, getFreshPromptEmojiTags } from '../../../../../scripts/utils/prompts/promptEmojiTags';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import { prepareCoderPrompt } from '../add';
+import { resolvePlanningPath } from './resolvePlanningPath';
+import type { PlanningProposal } from './planningProtocol';
+
+/**
+ * A fully rendered change retained in memory until the user explicitly saves it.
+ * @private internal type of `coder plan`
+ */
+export type PlanningChange = {
+    readonly path: string;
+    readonly before: string | null;
+    readonly after: string;
+    readonly draft: string;
+};
+
+/**
+ * Prepares an entire proposal set without writing. Exact replacements preserve unrelated content and line endings.
+ * @private internal utility of `coder plan`
+ */
+export async function preparePlanningChanges(
+    projectPath: string,
+    proposals: ReadonlyArray<PlanningProposal>,
+    templateOption: string | undefined,
+): Promise<PlanningChange[]> {
+    const canonicalProjectPath = await realpath(projectPath);
+    const createdCount = proposals.filter((proposal) => proposal.kind === 'create').length;
+    const { selectedEmojis } = createdCount
+        ? await getFreshPromptEmojiTags({ count: createdCount, rootDir: projectPath, isCacheWriteEnabled: false })
+        : { selectedEmojis: [] };
+    const changes: PlanningChange[] = [];
+    let numberOffset = 0;
+    for (const proposal of proposals) {
+        if (proposal.kind === 'create') {
+            const prepared = await prepareCoderPrompt({
+                projectPath,
+                description: `${proposal.title}\n\n${proposal.body}`,
+                priority: proposal.priority,
+                templateOption,
+                numberOffset,
+                reservedEmojiTag: formatPromptEmojiTag(selectedEmojis[numberOffset]!),
+            });
+            numberOffset++;
+            const path = prepared.filePath.replace(/\\/gu, '/');
+            resolvePlanningPath(projectPath, path, true);
+            const draft = prepared.content.replace(/^\[ \]/u, '[-]');
+            const after = proposal.isReady ? prepared.content : draft;
+            const parsed = parsePromptFile(path, after);
+            if (
+                after.includes(PTBK_CODER_IGNORE_MARKER) ||
+                parsed.sections.length !== 1 ||
+                (proposal.isReady && isPromptToBeWritten(parsed, parsed.sections[0]!))
+            ) {
+                throw new NotAllowed(
+                    spaceTrim(
+                        'A new proposal must contain one task without task separators or a queue ignore marker; unresolved placeholders require a draft. Split related tasks into separate proposals.',
+                    ),
+                );
+            }
+            changes.push({ path, before: null, after, draft });
+            continue;
+        }
+        const absolutePath = await realpath(resolvePlanningPath(projectPath, proposal.path, true));
+        const path = relative(canonicalProjectPath, absolutePath).replace(/\\/gu, '/');
+        const previous = changes.find((change) =>
+            process.platform === 'win32' ? change.path.toLowerCase() === path.toLowerCase() : change.path === path,
+        );
+        if (previous) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Propose one exact replacement per file per preview: \`${path}\`. Further revisions can be saved in the next turn.`,
+                ),
+            );
+        }
+        const before = await readFile(absolutePath, 'utf-8');
+        if (before.includes(PTBK_CODER_IGNORE_MARKER)) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `\`${path}\` is excluded from the PRD queue. Its context and ignore marker must be preserved.`,
+                ),
+            );
+        }
+        const file = parsePromptFile(path, before);
+        const find = proposal.find.replace(/\r?\n/gu, file.eol);
+        const replacement = proposal.replace.replace(/\r?\n/gu, file.eol);
+        const start = before.indexOf(find);
+        if (start < 0 || before.indexOf(find, start + 1) !== -1) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Edit in \`${path}\` must match one unique, unchanged text passage. Read it again before revising.`,
+                ),
+            );
+        }
+        const startLine = before.slice(0, start).split(/\r?\n/u).length - 1;
+        const endLine = startLine + find.split(/\r?\n/u).length - 1;
+        const section = file.sections.find(
+            (candidate) => candidate.startLine <= startLine && candidate.endLine >= endLine,
+        );
+        if (!section || !['todo', 'not-ready'].includes(section.status)) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Only pending or draft task bodies may be revised in \`${path}\`. Create new follow-up work as a new task.`,
+                ),
+            );
+        }
+        const identityLineIndex = file.lines.findIndex(
+            (line, index) =>
+                index >= (section.statusLineIndex === undefined ? section.startLine : section.statusLineIndex + 1) &&
+                index <= section.endLine &&
+                line.trim() !== '',
+        );
+        if (startLine <= identityLineIndex || /^\s*---\s*$/mu.test(replacement)) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Preserve task identity and lifecycle metadata in \`${path}\`; replace only the body of one task.`,
+                ),
+            );
+        }
+        let after = before.slice(0, start) + replacement + before.slice(start + find.length);
+        if (after.includes(PTBK_CODER_IGNORE_MARKER)) {
+            throw new NotAllowed(spaceTrim(`An edit cannot change the queue ignore metadata in \`${path}\`.`));
+        }
+        const afterFile = parsePromptFile(path, after);
+        if (afterFile.sections.length !== file.sections.length) {
+            throw new NotAllowed(spaceTrim(`An edit cannot add or remove task sections in \`${path}\`.`));
+        }
+        if (proposal.isReady && isPromptToBeWritten(afterFile, afterFile.sections[section.index]!)) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Unresolved placeholders in \`${path}\` require a draft; finish the entire task before marking it ready.`,
+                ),
+            );
+        }
+        const statusLine = section.statusLineIndex === undefined ? undefined : file.lines[section.statusLineIndex]!;
+        const lines = after.split(/\r?\n/u);
+        if (statusLine === undefined || section.statusLineIndex === undefined) {
+            if (section.status !== 'todo') {
+                throw new NotAllowed(
+                    spaceTrim(
+                        `Unsupported lifecycle metadata in \`${path}\` must be preserved; create a new task instead.`,
+                    ),
+                );
+            }
+            const draftLines = [...lines];
+            draftLines.splice(identityLineIndex, 0, '[-]', '');
+            const draft = draftLines.join(file.eol);
+            changes.push({ path, before, after: proposal.isReady ? after : draft, draft });
+            continue;
+        }
+        // Ready tasks retain routing tokens and priority verbatim. Draft promotion preserves the remaining suffix.
+        if (proposal.isReady && section.status === 'not-ready') {
+            lines[section.statusLineIndex] = statusLine.replace(/^(\s*)\[(?:-|\.)\]/u, '$1[ ]');
+            after = lines.join(file.eol);
+        }
+        // The parser supports clean [-] with priority marks. Refuse to discard model/agent metadata to make a draft.
+        const isDraftConversionSupported = /^\s*\[(?: |-|\.)\][!\s]*$/u.test(statusLine);
+        const draftLines = [...lines];
+        if (isDraftConversionSupported)
+            draftLines[section.statusLineIndex] = statusLine.replace(/^(\s*)\[.\]/u, '$1[-]');
+        if (!proposal.isReady && !isDraftConversionSupported) {
+            throw new NotAllowed(
+                spaceTrim(
+                    `Cannot convert routed task \`${path}\` into a draft without losing metadata. Keep the revision unsaved or create a separate draft task.`,
+                ),
+            );
+        }
+        const draft = isDraftConversionSupported ? draftLines.join(file.eol) : '';
+        changes.push({ path, before, after: proposal.isReady ? after : draft, draft });
+    }
+    return changes;
+}

package/src/cli/cli-commands/coder/planning/readPlanningContext.ts

@@ -0,0 +1,108 @@
+import { execFile } from 'child_process';
+// cspell:ignore fsmonitor textconv
+import { readFile, readdir, stat } from 'fs/promises';
+import { relative } from 'path';
+import { promisify } from 'util';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import type { PlanningRead } from './planningProtocol';
+import { resolvePlanningPath } from './resolvePlanningPath';
+
+/** Directories omitted from repository discovery; no links or hidden runtime state are followed. */
+const IGNORED_DIRECTORIES = new Set(['node_modules', 'vendor', 'dist', 'build', 'coverage']);
+/** Maximum bytes read from an individual repository file. */
+const MAX_FILE_BYTES = 524288;
+/** Fixed Git argument vectors prevent shell, diff-driver, pager, and filesystem-monitor execution. */
+const READ_ONLY_GIT_ARGUMENTS = {
+    status: ['status', '--short'],
+    diff: ['diff', '--no-ext-diff', '--no-textconv', '--stat'],
+    log: ['log', '-10', '--format=%h %s'],
+};
+
+/**
+ * Executes only the read operations in the planning protocol. Never evaluates a command from the model.
+ * @private internal utility of `coder plan`
+ */
+export async function readPlanningContext(projectPath: string, request: PlanningRead): Promise<string> {
+    if (request.kind === 'git') {
+        const result = await promisify(execFile)(
+            'git',
+            [
+                '--no-pager',
+                '--no-optional-locks',
+                '-c',
+                'core.fsmonitor=false',
+                ...READ_ONLY_GIT_ARGUMENTS[request.operation],
+            ],
+            {
+                cwd: projectPath,
+                timeout: 10000,
+                maxBuffer: MAX_FILE_BYTES,
+                windowsHide: true,
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            },
+        );
+        return result.stdout;
+    }
+    const path = resolvePlanningPath(projectPath, request.path);
+    if (request.kind === 'read') {
+        const content = await readPlanningText(path);
+        return content
+            .split(/\r?\n/u)
+            .slice(request.startLine - 1, request.startLine - 1 + request.lineCount)
+            .map((line, index) => `${request.startLine + index}: ${line}`)
+            .join('\n');
+    }
+    const files: string[] = [];
+    await listPlanningFiles(projectPath, request.path, files);
+    if (request.kind === 'list') {
+        return (
+            files.join('\n') +
+            (files.length >= 2000 ? '\n[Listing limited to 2000 paths; choose a narrower directory.]' : '')
+        );
+    }
+    const matches: string[] = [];
+    for (const file of files) {
+        const content = await readPlanningText(resolvePlanningPath(projectPath, file)).catch(() => '');
+        for (const [index, line] of content.split(/\r?\n/u).entries()) {
+            if (line.includes(request.query)) {
+                matches.push(`${file}:${index + 1}: ${line.slice(0, 500)}`);
+            }
+            if (matches.length >= 100) {
+                return matches.join('\n') + '\n[Search limited to 100 matches.]';
+            }
+        }
+    }
+    return matches.join('\n') || 'No matches.';
+}
+
+/** Reads bounded regular text, refusing binary or oversized files. */
+async function readPlanningText(path: string): Promise<string> {
+    const stats = await stat(path);
+    if (!stats.isFile() || stats.size > MAX_FILE_BYTES) {
+        throw new NotAllowed(spaceTrim('Choose a regular text file smaller than 512 KiB.'));
+    }
+    const content = await readFile(path, 'utf-8');
+    if (content.includes('\0')) {
+        throw new NotAllowed(spaceTrim('Binary files cannot be read as planning context.'));
+    }
+    return content;
+}
+
+/** Walks a bounded, deterministic directory listing, skipping links before traversing them. */
+async function listPlanningFiles(projectPath: string, directory: string, files: string[]): Promise<void> {
+    const path = resolvePlanningPath(projectPath, directory);
+    if ((await stat(path)).isFile()) {
+        files.push(relative(projectPath, path).replace(/\\/gu, '/'));
+        return;
+    }
+    for (const entry of (await readdir(path, { withFileTypes: true })).sort((left, right) =>
+        left.name.localeCompare(right.name),
+    )) {
+        if (files.length >= 2000) return;
+        if (entry.isSymbolicLink() || entry.name.startsWith('.') || IGNORED_DIRECTORIES.has(entry.name)) continue;
+        const entryPath = `${directory}/${entry.name}`;
+        if (entry.isDirectory()) await listPlanningFiles(projectPath, entryPath, files);
+        else if (entry.isFile()) files.push(entryPath.replace(/^\.\//u, ''));
+    }
+}

package/src/cli/cli-commands/coder/planning/resolvePlanningPath.ts

@@ -0,0 +1,72 @@
+import { lstatSync, realpathSync } from 'fs';
+import { isAbsolute, join, relative, resolve } from 'path';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+
+/** Control characters cannot be model-supplied filesystem path components. */
+const FIRST_PRINTABLE_CHARACTER_CODE = 32;
+
+/** Windows devices are not ordinary files, including when they carry a Markdown extension. */
+const WINDOWS_DEVICE_NAME_PATTERN = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;
+
+/** Repository guidance is never an editable PRD, even when stored alongside the queue. */
+const PLANNING_CONTEXT_FILE_NAMES = new Set(['agents.md', 'claude.md', 'gemini.md', 'readme.md', 'skill.md']);
+
+/**
+ * Resolves a repository path without traversing symlinks, junctions, device paths, or parent escapes.
+ * Writes additionally require an ordinary, singly linked PRD Markdown file in the active prompts directory.
+ * The queue loader reads only this directory; archives, templates and reusable context remain read-only.
+ * @private internal execution boundary of `coder plan`
+ */
+export function resolvePlanningPath(projectPath: string, path: string, isWriting = false): string {
+    const root = realpathSync(projectPath);
+    const normalizedPath = path.replace(/\\/gu, '/');
+    if (isAbsolute(path) || normalizedPath.includes(':') || normalizedPath.split('/').includes('..')) {
+        throw new NotAllowed(spaceTrim(`Planning path \`${path}\` must stay inside the project.`));
+    }
+    const segments = normalizedPath.split('/').filter((part) => part && part !== '.');
+    if (
+        segments.some(
+            (part) =>
+                part.startsWith('.') ||
+                WINDOWS_DEVICE_NAME_PATTERN.test(part) ||
+                (isWriting && /[$`%[\]]/u.test(part)) ||
+                /[<>"|?*]/u.test(part) ||
+                [...part].some((character) => character.charCodeAt(0) < FIRST_PRINTABLE_CHARACTER_CODE) ||
+                /[. ]$/u.test(part),
+        )
+    ) {
+        throw new NotAllowed(spaceTrim(`Planning cannot access hidden or special path \`${path}\`.`));
+    }
+    if (
+        isWriting &&
+        (segments[0] !== 'prompts' ||
+            segments.length !== 2 ||
+            !path.toLowerCase().endsWith('.md') ||
+            PLANNING_CONTEXT_FILE_NAMES.has(segments[1]!.toLowerCase()))
+    ) {
+        throw new NotAllowed(spaceTrim(`Planning can only author PRD Markdown files in \`prompts/\`: \`${path}\`.`));
+    }
+    let current = root;
+    for (const [index, segment] of segments.entries()) {
+        current = join(current, segment);
+        try {
+            const stats = lstatSync(current);
+            if (
+                stats.isSymbolicLink() ||
+                (!stats.isDirectory() && !stats.isFile()) ||
+                (isWriting && stats.isFile() && stats.nlink !== 1)
+            ) {
+                throw new NotAllowed(spaceTrim(`Planning refuses linked or special path \`${path}\`.`));
+            }
+            if (relative(root, realpathSync(current)).startsWith('..')) {
+                throw new NotAllowed(spaceTrim(`Planning path \`${path}\` escapes the project.`));
+            }
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'ENOENT' || index !== segments.length - 1 || !isWriting) {
+                throw error;
+            }
+        }
+    }
+    return resolve(current);
+}

package/src/cli/cli-commands/coder/planning/runPlanningHarness.ts

@@ -0,0 +1,249 @@
+import { spawn } from 'child_process';
+import { stat } from 'fs/promises';
+import { dirname, join } from 'path';
+import { createInterface } from 'readline';
+import { $terminateLoggedBashProcessTree } from '../../../../../scripts/run-codex-prompts/common/runGoScript/$terminateLoggedBashProcessTree';
+import { buildCodexUsageFromOutput } from '../../../../../scripts/run-codex-prompts/runners/openai-codex/buildCodexUsageFromOutput';
+import type { Usage } from '../../../../execution/Usage';
+import { UNCERTAIN_USAGE } from '../../../../execution/utils/usage-constants';
+import { PipelineExecutionError } from '../../../../errors/PipelineExecutionError';
+import { NotAllowed } from '../../../../errors/NotAllowed';
+import { spaceTrim } from '../../../../utils/organization/spaceTrim';
+import { $resolveHarnessCommandPath } from '../../common/harness/$resolveHarnessCommandPath';
+import { getHarnessDefinition } from '../../common/harness/HarnessDefinition';
+import { HARNESS_DEFAULT_MODELS } from '../../common/harness/HARNESS_DEFAULT_MODELS';
+import type { NormalizedPromptRunnerSelectionCliOptions } from '../../common/promptRunnerCliOptions';
+import { PLANNING_RESPONSE_SCHEMA_FILENAME } from './createPlanningWorkspace';
+
+/** Capabilities excluded from the planning process independently of any Book or prompt. */
+const DISABLED_PLANNING_FEATURES = [
+    'shell_tool',
+    'unified_exec',
+    'multi_agent',
+    'multi_agent_v2',
+    'apps',
+    'plugins',
+    'hooks',
+    'browser_use',
+    'computer_use',
+    'image_generation',
+    'code_mode',
+    'code_mode_host',
+    'request_permissions_tool',
+    'memories',
+    'skill_mcp_dependency_install',
+    'remote_plugin',
+    'workspace_dependencies',
+    'shell_snapshot',
+    'skill_search',
+    'tool_suggest',
+];
+/** Maximum duration of one inference; errors never enter the implementation runner's retry loop. */
+const PLANNING_TURN_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Bounded diagnostic tail retained when a harness fails. */
+const MAX_DIAGNOSTIC_LENGTH = 8000;
+
+/** Maximum raw output, including malformed streams that never terminate a JSON line. */
+const MAX_PLANNING_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Parameters for one tool-restricted inference. Repository reads and PRD writes are host operations.
+ * @private internal type of `coder plan`
+ */
+export type PlanningHarnessOptions = NormalizedPromptRunnerSelectionCliOptions & {
+    readonly workspacePath: string;
+    readonly prompt: string;
+    readonly signal: AbortSignal;
+    /** Reports available usage from this inference once, including turns whose final answer is malformed. */
+    readonly onUsage?: (usage: Usage) => void;
+};
+
+/**
+ * Rejects harnesses without a planning execution policy before any Git sync or process launch.
+ * @private internal utility of `coder plan`
+ */
+export function assertPlanningHarnessSupported(harness: string | undefined): void {
+    if (harness !== 'openai-codex') {
+        throw new NotAllowed(
+            spaceTrim(
+                'Planning currently supports `--harness openai-codex` only. Other harnesses have no enforced planning tool boundary.',
+            ),
+        );
+    }
+}
+
+/**
+ * Constructs a fail-closed Codex invocation. User config, rules, project config discovery, native shell,
+ * connectors, hooks and delegation cannot expand the planning tool set. Read-only sandboxing also denies patches.
+ * Older Codex versions that do not support these switches fail instead of using the implementation runner.
+ * @private internal utility of `coder plan`
+ */
+export function buildPlanningHarnessArguments(options: PlanningHarnessOptions): string[] {
+    const model = options.model === 'default' ? undefined : options.model || HARNESS_DEFAULT_MODELS['openai-codex'];
+    return [
+        '--ask-for-approval',
+        'never',
+        'exec',
+        '--sandbox',
+        'read-only',
+        '--ephemeral',
+        '--ignore-user-config',
+        '--ignore-rules',
+        '--skip-git-repo-check',
+        '--json',
+        '--output-schema',
+        join(options.workspacePath, PLANNING_RESPONSE_SCHEMA_FILENAME),
+        '--color',
+        'never',
+        '-C',
+        options.workspacePath,
+        '-c',
+        'project_root_markers=[".git"]',
+        '-c',
+        'web_search="disabled"',
+        '-c',
+        'mcp_servers={}',
+        '-c',
+        'project_doc_max_bytes=0',
+        ...DISABLED_PLANNING_FEATURES.flatMap((feature) => ['--disable', feature]),
+        ...(!options.allowCredits ? ['-c', 'forced_login_method="chatgpt"'] : []),
+        ...(model ? ['--model', model] : []),
+        ...(options.thinkingLevel ? ['-c', `model_reasoning_effort=${JSON.stringify(options.thinkingLevel)}`] : []),
+        '-',
+    ];
+}
+
+/**
+ * Runs a bounded inference with no shell interpolation and consumes only its final JSON answer.
+ * @private internal utility of `coder plan`
+ */
+export async function runPlanningHarness(options: PlanningHarnessOptions): Promise<string> {
+    assertPlanningHarnessSupported(options.agentName);
+    const command = await resolvePlanningHarnessCommand();
+    if (options.signal.aborted) throw new NotAllowed(spaceTrim('Planning cancelled.'));
+    return new Promise((resolve, reject) => {
+        const environment = { ...process.env };
+        // Config is isolated, but Codex still uses its normal authentication store. Do not source project .env files.
+        if (!options.allowCredits) {
+            delete environment.OPENAI_API_KEY;
+            delete environment.OPENAI_BASE_URL;
+            delete environment.CODEX_API_KEY;
+        }
+        const child = spawn(command.executable, [...command.arguments, ...buildPlanningHarnessArguments(options)], {
+            cwd: options.workspacePath,
+            env: environment,
+            stdio: 'pipe',
+            shell: false,
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        });
+        const reader = createInterface({ input: child.stdout });
+        let answer = '';
+        let diagnostics = '';
+        let outputSize = 0;
+        let isSettled = false;
+        let isHarnessFailed = false;
+        let usageEvent: string | undefined;
+        /** Finishes exactly once and terminates only this harness process tree. */
+        const finish = (error?: Error): void => {
+            if (isSettled) return;
+            isSettled = true;
+            clearTimeout(timeout);
+            options.signal.removeEventListener('abort', cancel);
+            reader.close();
+            options.onUsage?.(usageEvent ? buildCodexUsageFromOutput(usageEvent, options.model) : UNCERTAIN_USAGE);
+            if (error) {
+                if (process.platform !== 'win32' && child.pid) {
+                    try {
+                        process.kill(-child.pid, 'SIGKILL');
+                    } catch {
+                        child.kill('SIGKILL');
+                    }
+                } else {
+                    $terminateLoggedBashProcessTree(child);
+                }
+                reject(error);
+            } else resolve(answer);
+        };
+        /** Cancels inference before any host write can be proposed. */
+        const cancel = (): void => finish(new NotAllowed(spaceTrim('Planning cancelled. Saved PRDs are unchanged.')));
+        const timeout = setTimeout(
+            () =>
+                finish(
+                    new PipelineExecutionError(spaceTrim('Planner harness timed out. No proposed changes were saved.')),
+                ),
+            PLANNING_TURN_TIMEOUT_MS,
+        );
+        options.signal.addEventListener('abort', cancel, { once: true });
+        child.stdout.on('data', (data: Buffer) => {
+            outputSize += data.length;
+            if (outputSize > MAX_PLANNING_OUTPUT_BYTES) {
+                finish(new PipelineExecutionError(spaceTrim('Planner output exceeded the session limit.')));
+            }
+        });
+        child.stderr.on('data', (data: Buffer) => {
+            diagnostics = (diagnostics + data.toString()).slice(-MAX_DIAGNOSTIC_LENGTH);
+        });
+        child.stdin.on('error', (error) =>
+            finish(new PipelineExecutionError(spaceTrim(`Planner harness input failed: ${error.message}`))),
+        );
+        child.on('error', (error) =>
+            finish(
+                new PipelineExecutionError(
+                    spaceTrim(`Cannot start Codex: ${error.message}. Install and sign in to Codex before planning.`),
+                ),
+            ),
+        );
+        child.on('close', (code) =>
+            finish(
+                code === 0 && answer && !isHarnessFailed
+                    ? undefined
+                    : new PipelineExecutionError(
+                          spaceTrim(
+                              `Planner harness failed (${code}). No proposed changes were saved. Use a Codex version supporting --ignore-user-config and --ignore-rules.\n${diagnostics}`,
+                          ),
+                      ),
+            ),
+        );
+        reader.on('line', (line) => {
+            if (isSettled) return;
+            try {
+                const event = JSON.parse(line);
+                if (event.type === 'turn.completed' && event.usage) usageEvent = line;
+                if (event.type === 'item.completed' && event.item?.type === 'agent_message') answer = event.item.text;
+                if (event.type === 'turn.failed' || event.type === 'error') {
+                    isHarnessFailed = true;
+                    diagnostics = JSON.stringify(event);
+                }
+            } catch {
+                /* Non-JSON diagnostics never become executable instructions. */
+            }
+        });
+        child.stdin.end(options.prompt);
+    });
+}
+
+/** Resolves npm Windows shims to their JavaScript entrypoint so all model text stays off the command line. */
+async function resolvePlanningHarnessCommand(): Promise<{ executable: string; arguments: string[] }> {
+    const path = await $resolveHarnessCommandPath(getHarnessDefinition('openai-codex'));
+    if (!path)
+        throw new NotAllowed(
+            spaceTrim('Codex is not installed. Install and sign in to Codex, then retry `ptbk coder plan`.'),
+        );
+    if (process.platform !== 'win32' || path.toLowerCase().endsWith('.exe')) return { executable: path, arguments: [] };
+    const entrypoint = join(dirname(path), 'node_modules', '@openai', 'codex', 'bin', 'codex.js');
+    if (
+        await stat(entrypoint).then(
+            (entry) => entry.isFile(),
+            () => false,
+        )
+    ) {
+        return { executable: process.execPath, arguments: [entrypoint] };
+    }
+    throw new NotAllowed(
+        spaceTrim(
+            'Planning needs the native Codex executable or its standard npm installation on Windows; shell shims cannot enforce argument isolation.',
+        ),
+    );
+}