@promptbook/cli 0.114.0-3 → 0.114.0-30

package/src/cli/cli-commands/coder/ping.ts

@@ -5,6 +5,11 @@ import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -12,6 +17,7 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseOptionalPeriodDuration } from './waitOptions';
 
 /**
  * Initializes `coder ping` command for Promptbook CLI utilities
@@ -32,38 +38,68 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             - Verifies that the selected harness, model, thinking level and authentication really work
             - Reports the answer of the harness, the response time and the reported usage
             - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
             - Leaves the project exactly as it was — nothing is read, written, changed or committed
+            - Checks that the selected harness is installed and up to date unless --no-harness-update is used
             - Use --no-ui to stream the raw harness output instead of only the compact result
         `),
     );
 
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option(
+        '--period <duration>',
+        spaceTrim(`
+            Keep pinging once per period instead of pinging only once.
+            Accepts durations like 5h, 30m, 1h30m and repeats until it is stopped with CTRL+C.
+        `),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const { period: periodValue } = cliOptions as {
+                readonly period?: string;
+            } & PromptRunnerSelectionCliOptions;
+
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+            const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
-            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
-            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
-            const { printCoderPingResult } = await import(
-                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
-            );
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
-            const result = await pingCoderHarness({
+            const pingOptions = {
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 allowCredits: runnerOptions.allowCredits,
                 shouldPrintLiveOutput: runnerOptions.noUi,
-            });
+            };
+
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            if (periodMs !== undefined) {
+                const { pingCoderHarnessPeriodically } = await import(
+                    '../../../../scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically'
+                );
+
+                // Note: This never returns - it keeps pinging until the user stops the process
+                await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+                return;
+            }
+
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
 
-            printCoderPingResult(result);
+            printCoderPingResult(await pingCoderHarness(pingOptions));
         }),
     );
 }

package/src/cli/cli-commands/coder/run.ts

@@ -10,6 +10,12 @@ import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativ
 import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
+import { $ensurePromptbookCliInstallations } from '../common/promptbook-cli/$ensurePromptbookCliInstallations';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -41,12 +47,16 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
             Features:
             - Automatically stages and commits changes with agent identity unless --no-commit is used
+            - Commits only the prompt file and the files the coding agent has changed, leaving unrelated changes alone
+            - Refuses to start on a dirty working tree unless --git-changes says what should happen with the changes
+            - Optional --git-changes continue resumes the single prompt an interrupted coder left in the [^] status
             - Optional post-commit git push with explicit --auto-push opt-in
             - Optional pre-prompt git pull with explicit --auto-pull opt-in
             - Optional --isolate runs every prompt in its own temporary git worktree and merges it back when verified
             - Optional --preserve-logs keeps temp prompt/log artifacts after successful rounds
             - Optional --no-ui keeps plain streaming console output for logging and debugging
-            - Checks that the selected harness is installed globally and up to date before the first prompt
+            - Checks that the selected harness is installed and up to date before the first prompt unless --no-harness-update is used
+            - In interactive mode, checks local and global Promptbook CLI installations and offers to update them
             - Supports GPG signing of commits
             - Optional pre-coding test run that can stop or repair pre-existing failures
             - Optional post-prompt verification with test-feedback retries
@@ -57,6 +67,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
 
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     command.option(
         '--agent <agent-book-path>',
         'Path to a .book file whose compiled system message is prepended to each coding prompt',
@@ -195,8 +206,9 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
-
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
             // [1] Parse the wait options and --no-auto:
             //   default: run automatically through the queue (no waiting between prompts)
@@ -205,6 +217,13 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
             //   --wait-between-prompts: pace from start of one prompt to start of next
             //   --wait-after-error: wait before retrying after an error (default 10m)
             const waitForUser = !auto;
+
+            if (await $ensurePromptbookCliInstallations()) {
+                return process.exit(0);
+            }
+
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
+
             const waitAfterPrompt = parseOptionalWaitDuration(waitAfterPromptValue, 0);
             const waitBetweenPrompts = parseOptionalWaitDuration(waitBetweenPromptsValue, 0);
             const waitAfterError = parseOptionalWaitDuration(waitAfterErrorValue, DEFAULT_WAIT_AFTER_ERROR_MS);
@@ -217,7 +236,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

package/src/cli/cli-commands/coder/server.ts

@@ -12,6 +12,11 @@ import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { createNonNegativeIntegerOptionParser } from '../common/createNonNegativeIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
+import {
+    addHarnessUpdateOption,
+    normalizeHarnessUpdateCliOptions,
+    type HarnessUpdateCliOptions,
+} from '../common/harnessUpdateCliOptions';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerExecutionOptions,
@@ -48,7 +53,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
 
             Features:
             - Runs the same prompt processing as \`ptbk coder run\`
-            - Checks that the selected harness is installed globally and up to date on startup
+            - Checks that the selected harness is installed and up to date on startup unless --no-harness-update is used
             - Does not exit when all prompts are done; polls for new prompt files instead
             - Serves a kanban board at http://localhost:<port> for visual progress tracking
             - Allows editing prompt files directly from the browser (Trello-style)
@@ -64,6 +69,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
     );
     command.option('--dry-run', 'Print unwritten prompts without executing', false);
     addPromptRunnerSelectionOptions(command);
+    addHarnessUpdateOption(command);
     command.option(
         '--agent <agent-book-path>',
         'Path to a .book file whose compiled system message is prepended to each coding prompt',
@@ -173,8 +179,11 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
             const runnerOptions = normalizePromptRunnerCliOptions(cliOptions as PromptRunnerCliOptions, {
                 isAgentRequired: !dryRun,
             });
+            const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(
+                cliOptions as HarnessUpdateCliOptions,
+            );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName]);
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
             // [1] Parse the wait options and --no-auto (same logic as `coder run`)
             const waitForUser = !auto;
@@ -190,7 +199,7 @@ export function $initializeCoderServerCommand(program: Program): $side_effect {
                 waitBetweenPrompts,
                 waitAfterError,
                 noCommit: runnerOptions.noCommit,
-                ignoreGitChanges: runnerOptions.ignoreGitChanges,
+                gitChanges: runnerOptions.gitChanges,
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 agent,

package/src/cli/cli-commands/coder/verify.ts

@@ -1,8 +1,15 @@
 import colors from 'colors';
-import type {
+import {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import type { VerifyPromptsOrder } from '../../../../scripts/verify-prompts/VerifyPromptsOrder';
+import {
+    DEFAULT_VERIFY_PROMPTS_ORDER,
+    VERIFY_PROMPTS_ORDER_DESCRIPTIONS,
+    VERIFY_PROMPTS_ORDER_VALUES,
+} from '../../../../scripts/verify-prompts/VerifyPromptsOrder';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
 import {
@@ -33,6 +40,7 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
                 - Auto-appends repair prompts for incomplete work
                 - Processes files with all-done prompts first
                 - Supports ignoring matching prompt candidates for one verification run
+                - Supports processing the prompt files from the earliest, from the latest or in random order
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
 
@@ -41,7 +49,23 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
         ),
     );
 
-    command.option('--reverse', 'Process prompt files in reverse order', false);
+    command.addOption(
+        new Option(
+            '--order <order>',
+            spaceTrim(
+                (block) => `
+                    Order in which the prompt files are processed:
+                    ${block(
+                        VERIFY_PROMPTS_ORDER_VALUES.map(
+                            (order) => `- ${order}: ${VERIFY_PROMPTS_ORDER_DESCRIPTIONS[order]}`,
+                        ).join('\n'),
+                    )}
+                `,
+            ),
+        )
+            .choices([...VERIFY_PROMPTS_ORDER_VALUES])
+            .default(DEFAULT_VERIFY_PROMPTS_ORDER),
+    );
     command.option(
         '--ignore <candidate-text>',
         'Ignore prompt files whose filename or first prompt line contains the given text (repeatable)',
@@ -52,8 +76,8 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { reverse, ignore } = cliOptions as {
-                readonly reverse: boolean;
+            const { order, ignore } = cliOptions as {
+                readonly order: VerifyPromptsOrder;
                 readonly ignore: ReadonlyArray<string>;
             } & CoderGitSyncCliOptions;
 
@@ -63,7 +87,7 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
             const { verifyPrompts } = await import('../../../../scripts/verify-prompts/verify-prompts');
 
             try {
-                await verifyPrompts({ reverse, ignore, gitSync });
+                await verifyPrompts({ order, ignore, gitSync });
             } catch (error) {
                 console.error(colors.bgRed('Prompt verification failed:'), error);
                 return process.exit(1);

package/src/cli/cli-commands/coder/waitOptions.ts

@@ -1,4 +1,6 @@
+import { spaceTrim } from 'spacetrim';
 import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+import { NotAllowed } from '../../../errors/NotAllowed';
 
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
@@ -21,4 +23,35 @@ export function parseOptionalWaitDuration(value: string | undefined, defaultMs:
     return parseDuration(value);
 }
 
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+
+    const periodMs = parseDuration(value);
+
+    if (periodMs <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${optionName}\`: \`${value}\`.
+
+                Use a **positive** duration like \`5h\`, \`30m\` or \`1h30m\`.
+            `),
+        );
+    }
+
+    return periodMs;
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/common/coderGitSyncCliOptions.ts

@@ -26,7 +26,7 @@ export type CoderGitSyncCliOptions = {
 export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
     Git synchronization:
     - --auto-pull pulls the latest changes before this command changes anything
-    - --commit commits the changes made by this command
+    - --commit commits only the files this command has changed, unrelated changes stay in the working tree
     - --auto-push pushes the created commit to the remote repository
 `);
 
@@ -39,7 +39,11 @@ export const CODER_GIT_SYNC_DESCRIPTION = spaceTrim(`
  * @private internal utility of `promptbookCli`
  */
 export function addCoderGitSyncOptions(command: Program): void {
-    command.option('--commit', 'Commit the changes made by this command with the coding-agent git identity', false);
+    command.option(
+        '--commit',
+        'Commit the files changed by this command with the coding-agent git identity, leaving unrelated changes uncommitted',
+        false,
+    );
     command.option('--auto-push', 'Automatically git push the created commit, requires --commit', false);
     command.option(
         '--auto-pull',

package/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts

@@ -1,25 +1,35 @@
 import colors from 'colors';
-import { $askForHarnessInstallationApproval } from './$askForHarnessInstallationApproval';
-import { $installHarness } from './$installHarness';
+import { $askForNpmPackageInstallationApproval } from '../npm/$askForNpmPackageInstallationApproval';
+import { $runHarnessInstallationCommand } from './$runHarnessInstallationCommand';
 import { buildHarnessInstallCommand } from './buildHarnessInstallCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
 import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 import { formatHarnessInstallationWarning } from './formatHarnessInstallationWarning';
+import { formatHarnessManualUpdateInstruction } from './formatHarnessManualUpdateInstruction';
+import { resolveHarnessUpdatePlan } from './resolveHarnessUpdatePlan';
 
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+ * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
  *
  * @private internal utility of `promptbookCli`
  */
 export async function $applyHarnessInstallationStatus(status: HarnessInstallationStatus): Promise<void> {
-    const { definition, installationState, installedVersion, latestVersion } = status;
+    const { definition, installationState, installedVersion } = status;
 
     if (installationState === 'up-to-date') {
         console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is up to date.`));
         return;
     }
 
+    if (installationState === 'installed') {
+        console.info(
+            colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`),
+        );
+        return;
+    }
+
     if (installationState === 'unknown') {
         console.info(
             colors.gray(
@@ -31,18 +41,64 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
 
     console.warn(colors.yellow(formatHarnessInstallationWarning(status)));
 
-    const isInstallationApproved = await $askForHarnessInstallationApproval(
-        installationState === 'not-installed'
-            ? `Install ${definition.label} globally now?`
-            : `Update ${definition.label} to ${latestVersion} now?`,
+    if (installationState === 'not-installed') {
+        await $applyMissingHarnessInstallation(definition);
+        return;
+    }
+
+    await $applyOutdatedHarnessInstallation(status);
+}
+
+/**
+ * Offers to install a missing harness globally through npm.
+ */
+async function $applyMissingHarnessInstallation(definition: HarnessDefinition): Promise<void> {
+    const installCommand = buildHarnessInstallCommand(definition);
+
+    const isInstallationApproved = await $askForNpmPackageInstallationApproval(
+        `Install ${definition.label} globally now?`,
     );
 
     if (!isInstallationApproved) {
-        console.info(colors.gray(`Skipped, run \`${buildHarnessInstallCommand(definition)}\` to do it manually.`));
+        console.info(colors.gray(`Skipped, run \`${installCommand}\` to do it manually.`));
+        return;
+    }
+
+    await $runHarnessInstallationCommand({
+        definition,
+        operation: 'install',
+        command: installCommand,
+        environment: definition.npmInstallEnvironment,
+    });
+}
+
+/**
+ * Offers to update an outdated harness exactly where it is installed.
+ */
+async function $applyOutdatedHarnessInstallation(status: HarnessInstallationStatus): Promise<void> {
+    const { definition, latestVersion, installationOrigin } = status;
+    const updatePlan = resolveHarnessUpdatePlan(definition, installationOrigin.installationMethod);
+
+    if (updatePlan.command === null || !updatePlan.isRunnableByPromptbook) {
+        console.info(colors.gray(formatHarnessManualUpdateInstruction(status, updatePlan)));
+        return;
+    }
+
+    const isUpdateApproved = await $askForNpmPackageInstallationApproval(
+        `Update ${definition.label} to ${latestVersion} with \`${updatePlan.command}\` now?`,
+    );
+
+    if (!isUpdateApproved) {
+        console.info(colors.gray(`Skipped, run \`${updatePlan.command}\` to do it manually.`));
         return;
     }
 
-    await $installHarness(definition);
+    await $runHarnessInstallationCommand({
+        definition,
+        operation: 'update',
+        command: updatePlan.command,
+        environment: updatePlan.environment,
+    });
 }
 
 // Note: [🟡] Code for CLI harness installation handling [$applyHarnessInstallationStatus](src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts

@@ -1,27 +1,43 @@
 import { $resolveInstalledHarnessVersion } from './$resolveInstalledHarnessVersion';
-import { $resolveLatestHarnessVersion } from './$resolveLatestHarnessVersion';
+import { $resolveLatestNpmPackageVersion } from '../npm/$resolveLatestNpmPackageVersion';
+import { isNpmPackageVersionOutdated } from '../npm/isNpmPackageVersionOutdated';
+import { $resolveHarnessInstallationOrigin } from './$resolveHarnessInstallationOrigin';
 import type { HarnessDefinition } from './HarnessDefinition';
+import { UNKNOWN_HARNESS_INSTALLATION_ORIGIN } from './HarnessInstallationOrigin';
 import type { HarnessInstallationState, HarnessInstallationStatus } from './HarnessInstallationStatus';
-import { isHarnessVersionOutdated } from './isHarnessVersionOutdated';
 
 /**
- * Detects whether one CLI coding harness is installed globally and whether it is up to date.
+ * Detects whether one CLI coding harness is installed globally and, when enabled, whether it is up to date.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and queries npm
+ * Note: `$` is used to indicate that this function is not a pure function - it runs the harness command and may query npm
  *
  * @private internal utility of `promptbookCli`
  */
-export async function $checkHarnessInstallation(definition: HarnessDefinition): Promise<HarnessInstallationStatus> {
-    const [installedVersion, latestVersion] = await Promise.all([
+export async function $checkHarnessInstallation(
+    definition: HarnessDefinition,
+    isHarnessUpdateCheckEnabled = true,
+): Promise<HarnessInstallationStatus> {
+    // Note: The origin is only needed to update an outdated harness, so it is not looked up without the update check
+    const [installedVersion, latestVersion, installationOrigin] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        $resolveLatestHarnessVersion(definition),
+        isHarnessUpdateCheckEnabled
+            ? $resolveLatestNpmPackageVersion(definition.npmPackageName)
+            : Promise.resolve(null),
+        isHarnessUpdateCheckEnabled
+            ? $resolveHarnessInstallationOrigin(definition)
+            : Promise.resolve(UNKNOWN_HARNESS_INSTALLATION_ORIGIN),
     ]);
 
     return {
         definition,
-        installationState: resolveHarnessInstallationState(installedVersion, latestVersion),
+        installationState: resolveHarnessInstallationState(
+            installedVersion,
+            latestVersion,
+            isHarnessUpdateCheckEnabled,
+        ),
         installedVersion,
         latestVersion,
+        installationOrigin,
     };
 }
 
@@ -31,16 +47,23 @@ export async function $checkHarnessInstallation(definition: HarnessDefinition):
 function resolveHarnessInstallationState(
     installedVersion: string | null,
     latestVersion: string | null,
+    isHarnessUpdateCheckEnabled: boolean,
 ): HarnessInstallationState {
     if (installedVersion === null) {
         return 'not-installed';
     }
 
+    if (!isHarnessUpdateCheckEnabled) {
+        return 'installed';
+    }
+
     if (latestVersion === null) {
         return 'unknown';
     }
 
-    return isHarnessVersionOutdated(installedVersion, latestVersion) ? 'outdated' : 'up-to-date';
+    return isNpmPackageVersionOutdated(installedVersion, latestVersion, { isPrereleaseIgnored: true })
+        ? 'outdated'
+        : 'up-to-date';
 }
 
 // Note: [🟡] Code for CLI harness installation check [$checkHarnessInstallation](src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$ensureHarnessInstallations.ts

@@ -5,8 +5,8 @@ import type { HarnessDefinition } from './HarnessDefinition';
 import { getHarnessDefinition } from './HarnessDefinition';
 
 /**
- * Checks that every given CLI coding harness is installed globally and up to date and offers to
- * install or update the ones which are not.
+ * Checks that every given CLI coding harness is installed globally and, when enabled, up to date.
+ * Offers to install missing harnesses and update outdated ones.
  *
  * Harness names which are `undefined`, for example when no `--harness` is selected in a dry run,
  * are ignored so that every call site can pass its raw selection.
@@ -17,6 +17,7 @@ import { getHarnessDefinition } from './HarnessDefinition';
  */
 export async function $ensureHarnessInstallations(
     harnessNames: ReadonlyArray<PromptRunnerHarnessName | undefined>,
+    isHarnessUpdateCheckEnabled = true,
 ): Promise<void> {
     const definitions = resolveCheckedHarnessDefinitions(harnessNames);
 
@@ -25,7 +26,9 @@ export async function $ensureHarnessInstallations(
     }
 
     // Note: Detection of all harnesses runs in parallel, the questions have to be asked one by one
-    const statuses = await Promise.all(definitions.map((definition) => $checkHarnessInstallation(definition)));
+    const statuses = await Promise.all(
+        definitions.map((definition) => $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled)),
+    );
 
     for (const status of statuses) {
         await $applyHarnessInstallationStatus(status);

package/src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.ts

@@ -0,0 +1,46 @@
+import { realpath } from 'fs/promises';
+import { $execCommand } from '../../../../utils/execCommand/$execCommand';
+import type { HarnessDefinition } from './HarnessDefinition';
+
+/**
+ * Time limit for looking up where the harness command lives.
+ */
+const HARNESS_COMMAND_LOOKUP_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Finds out which file is really executed when the harness command runs.
+ *
+ * The lookup deliberately uses the very same `PATH` which runs the harness, so it reports the copy of the
+ * harness which Promptbook itself would use. Symbolic links are followed, because installers like the
+ * standalone OpenAI Codex installer only link their package into a directory on `PATH`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs a command in a shell
+ *
+ * @returns Resolved path of the harness command or `null` when the command is not available
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveHarnessCommandPath(definition: HarnessDefinition): Promise<string | null> {
+    const lookupCommand =
+        process.platform === 'win32' ? `where ${definition.commandName}` : `command -v ${definition.commandName}`;
+
+    const output: string = await $execCommand({
+        command: lookupCommand,
+        crashOnError: true,
+        timeout: HARNESS_COMMAND_LOOKUP_TIMEOUT_MS,
+        isVerbose: false,
+    }).catch(() => '');
+
+    // Note: `where` lists every match on its own line, only the first one is really executed
+    const commandPath = output
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line !== '');
+
+    if (commandPath === undefined) {
+        return null;
+    }
+
+    return await realpath(commandPath).catch(() => commandPath);
+}
+
+// Note: [🟡] Code for CLI harness command lookup [$resolveHarnessCommandPath](src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.ts

@@ -0,0 +1,36 @@
+import { $resolveNpmGlobalPrefixPath } from '../npm/$resolveNpmGlobalPrefixPath';
+import { $resolveHarnessCommandPath } from './$resolveHarnessCommandPath';
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
+import { UNKNOWN_HARNESS_INSTALLATION_ORIGIN } from './HarnessInstallationOrigin';
+import { resolveHarnessInstallationMethodFromPaths } from './resolveHarnessInstallationMethodFromPaths';
+
+/**
+ * Finds out where one CLI coding harness is really installed and which tool manages it.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs shell commands
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export async function $resolveHarnessInstallationOrigin(
+    definition: HarnessDefinition,
+): Promise<HarnessInstallationOrigin> {
+    const commandPath = await $resolveHarnessCommandPath(definition);
+
+    if (commandPath === null) {
+        return UNKNOWN_HARNESS_INSTALLATION_ORIGIN;
+    }
+
+    const npmGlobalPrefixPath = await $resolveNpmGlobalPrefixPath();
+
+    return {
+        commandPath,
+        installationMethod: resolveHarnessInstallationMethodFromPaths({
+            definition,
+            commandPath,
+            npmGlobalPrefixPath,
+        }),
+    };
+}
+
+// Note: [🟡] Code for CLI harness installation origin detection [$resolveHarnessInstallationOrigin](src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.ts) should never be published outside of `@promptbook/cli`