@promptbook/cli 0.114.0-2 → 0.114.0-3

package/src/book-3.0/LiteAgent.ts

@@ -1,10 +1,4 @@
-import {
-    Agent as AgentFromKit,
-    fileSearchTool,
-    run,
-    setDefaultOpenAIClient,
-    setDefaultOpenAIKey,
-} from '@openai/agents';
+import type { Agent as AgentFromKit } from '@openai/agents';
 import { readFile } from 'fs/promises';
 import { basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -17,6 +11,7 @@ import { computeOpenAiUsage } from '../llm-providers/openai/computeOpenAiUsage';
 import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
 import { OpenAiAgentKitExecutionToolsToolBuilder } from '../llm-providers/openai/OpenAiAgentKitExecutionToolsToolBuilder';
 import { OpenAiVectorStoreHandler } from '../llm-providers/openai/OpenAiVectorStoreHandler';
+import { loadOpenAiAgentsModule } from '../llm-providers/openai/utils/loadOpenAiAgentsModule';
 import { $provideScriptingForNode } from '../scrapers/_common/register/$provideScriptingForNode';
 import type { string_knowledge_source_link } from '../types/string_knowledge_source_content';
 import type { string_markdown, string_markdown_text } from '../types/string_markdown';
@@ -112,6 +107,7 @@ export class LiteAgent {
         const preparedAgent = await this.prepareAgent();
         preparedAgent.toolBuilder?.clearRunState();
 
+        const { run } = await loadOpenAiAgentsModule();
         const result = await run(
             preparedAgent.agent,
             createLiteAgentPromptText(normalizedMessage, options.context, preparedAgent.modelRequirements.promptSuffix),
@@ -165,6 +161,12 @@ export class LiteAgent {
             userId: this.options.userId,
         });
         const client = await runtime.getClient();
+        const {
+            Agent: AgentFromKit,
+            fileSearchTool,
+            setDefaultOpenAIClient,
+            setDefaultOpenAIKey,
+        } = await loadOpenAiAgentsModule();
 
         setDefaultOpenAIClient(client as TODO_any);
 
@@ -190,9 +192,9 @@ export class LiteAgent {
                   })
                 : null;
         const agentTools =
-            toolBuilder?.buildAgentKitTools({
+            (await toolBuilder?.buildAgentKitTools({
                 tools: modelRequirements.tools ? [...modelRequirements.tools] : undefined,
-            }) || [];
+            })) || [];
         const normalizedKnowledgeSources = await normalizeLiteAgentKnowledgeSources(
             modelRequirements.knowledgeSources || [],
             resolvedSource.sourceDirectoryPath,

package/src/book-components/Chat/utils/$provideServerDomWindow.ts

@@ -0,0 +1,77 @@
+import type { WindowLike as DomWindowLike } from 'dompurify';
+import { spaceTrim } from 'spacetrim';
+import { assertsError } from '../../../errors/assertsError';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
+
+/**
+ * Shared DOM window reused by every render which happens outside of a browser
+ *
+ * @private utility of `$provideServerDomWindow`
+ */
+let serverDomWindow: DomWindowLike | null = null;
+
+/**
+ * Provides a DOM `window` for runtimes which do not have one, for example Node.js during server-side rendering
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it creates and caches one shared DOM window
+ *
+ * @returns DOM window which can back a DOM-dependent library like `DOMPurify`
+ * @throws {EnvironmentMismatchError} When the current runtime can not create a DOM window
+ * @private utility of `renderMarkdown`
+ */
+export function $provideServerDomWindow(): DomWindowLike {
+    if (serverDomWindow === null) {
+        const { JSDOM } = requireServerDomLibrary();
+        serverDomWindow = new JSDOM('').window as unknown as DomWindowLike;
+    }
+
+    return serverDomWindow;
+}
+
+/**
+ * Loads `jsdom` which backs the DOM window outside of a browser
+ *
+ * Note: [😷] `jsdom` reaches for Node.js built-ins like `fs`, `child_process` and `net`, so browser bundlers must
+ *       never follow the `require` below - even though it is unreachable in a browser, bundlers resolve it statically.
+ *       They are told to replace `jsdom` with an empty module by the `browser` field of the generated package
+ *       manifests, which is written by `applyBrowserUnsupportedDependencyStubs` during the package generation.
+ *
+ * @returns The `jsdom` library
+ * @throws {EnvironmentMismatchError} When `jsdom` can not be loaded in the current runtime
+ * @private utility of `$provideServerDomWindow`
+ */
+function requireServerDomLibrary(): typeof import('jsdom') {
+    let serverDomLibrary: Partial<typeof import('jsdom')> | null = null;
+    let serverDomLibraryError: Error | null = null;
+
+    try {
+        // Note: [😷] Keep `'jsdom'` written as a literal, bundlers do not replace a computed module name
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        serverDomLibrary = require('jsdom') as typeof import('jsdom');
+    } catch (error) {
+        assertsError(error);
+        serverDomLibraryError = error;
+    }
+
+    if (typeof serverDomLibrary?.JSDOM !== 'function') {
+        throw new EnvironmentMismatchError(
+            spaceTrim(
+                (block) => `
+                    Markdown can not be rendered because there is no DOM in the current runtime.
+
+                    Rendered markdown is sanitized through \`DOMPurify\`, which needs a DOM - the DOM of the browser
+                    when the code runs in a browser and \`jsdom\` in every other runtime, for example during
+                    server-side rendering in **Node.js**.
+
+                    ${block(
+                        serverDomLibraryError === null
+                            ? 'The `jsdom` module was resolved but it does not export `JSDOM`, which happens when a bundler replaces `jsdom` with an empty module in a build which is neither a browser build nor a Node.js build.'
+                            : `${serverDomLibraryError.name}: ${serverDomLibraryError.message}`,
+                    )}
+                `,
+            ),
+        );
+    }
+
+    return serverDomLibrary as typeof import('jsdom');
+}

package/src/book-components/Chat/utils/renderMarkdown.ts

@@ -9,6 +9,7 @@ import type { Converter as ShowdownConverter } from 'showdown';
 import showdown from 'showdown';
 import type { string_html, string_markdown } from '../../../types/string_markdown';
 import { TODO_USE } from '../../../utils/organization/TODO_USE';
+import { $provideServerDomWindow } from './$provideServerDomWindow';
 import { createCitationMarkerRegex, parseCitationMarker } from './parseCitationMarker';
 
 /**
@@ -218,13 +219,6 @@ let browserMarkdownSanitizer: DomPurifyInstance | null = null;
  */
 let serverMarkdownSanitizer: DomPurifyInstance | null = null;
 
-/**
- * Shared JSDOM window backing the server-side DOMPurify instance.
- *
- * @private utility of `renderMarkdown`
- */
-let serverMarkdownSanitizerWindow: DomPurifyWindowLike | null = null;
-
 /**
  * Pattern matching CODE FENCE.
  */
@@ -546,21 +540,6 @@ function createMarkdownSanitizer(sanitizerWindow: DomPurifyWindowLike): DomPurif
     return markdownSanitizer;
 }
 
-/**
- * Lazily creates the JSDOM window used by server-side markdown sanitization.
- *
- * @private utility of `renderMarkdown`
- */
-function getServerMarkdownSanitizerWindow(): DomPurifyWindowLike {
-    if (!serverMarkdownSanitizerWindow) {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { JSDOM } = require('jsdom') as typeof import('jsdom');
-        serverMarkdownSanitizerWindow = new JSDOM('').window as unknown as DomPurifyWindowLike;
-    }
-
-    return serverMarkdownSanitizerWindow;
-}
-
 /**
  * Returns the shared DOMPurify instance appropriate for the current runtime.
  *
@@ -573,7 +552,7 @@ function getMarkdownSanitizer(): DomPurifyInstance {
         return browserMarkdownSanitizer;
     }
 
-    serverMarkdownSanitizer ??= createMarkdownSanitizer(getServerMarkdownSanitizerWindow());
+    serverMarkdownSanitizer ??= createMarkdownSanitizer($provideServerDomWindow());
 
     return serverMarkdownSanitizer;
 }

package/src/cli/cli-commands/agents-server/buildAgentsServer/createAgentsServerRuntimeEnvironment.ts

@@ -22,6 +22,14 @@ export const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = 'PTBK_AGENTS_SERVER_BUI
  */
 export const PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV = 'PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION';
 
+/**
+ * Environment variable that disables throwaway webpack filesystem caches for CLI-owned production builds.
+ *
+ * @private internal constant of `buildAgentsServer`
+ */
+export const PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE_ENV =
+    'PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE';
+
 /**
  * Conservative Next.js build worker count used by CLI-owned Agents Server production builds.
  *
@@ -41,6 +49,7 @@ export function createAgentsServerRuntimeEnvironment(
     nodeModulesPath: string,
     options: {
         readonly isNextValidationIgnored?: boolean;
+        readonly isWebpackFilesystemCacheDisabled?: boolean;
     } = {},
 ): NodeJS.ProcessEnv {
     return {
@@ -54,6 +63,11 @@ export function createAgentsServerRuntimeEnvironment(
                   [PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV]: 'true',
               }
             : {}),
+        ...(options.isWebpackFilesystemCacheDisabled
+            ? {
+                  [PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE_ENV]: 'true',
+              }
+            : {}),
     };
 }
 

package/src/cli/cli-commands/agents-server/buildAgentsServer/ensureAgentsServerBuild.ts

@@ -30,6 +30,7 @@ export async function ensureAgentsServerBuild(
     });
     const buildEnvironment = createAgentsServerRuntimeEnvironment(environment, preparedRuntime.nodeModulesPath, {
         isNextValidationIgnored: preparedRuntime.isAppPathMaterialized,
+        isWebpackFilesystemCacheDisabled: true,
     });
 
     if (

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

@@ -4,12 +4,18 @@ import type {
 } from 'commander';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import prompts from 'prompts';
 import { spaceTrim } from 'spacetrim';
 import { NotAllowed } from '../../../errors/NotAllowed';
 import { ParseError } from '../../../errors/ParseError';
 import { normalizeToKebabCase } from '../../../utils/normalization/normalize-to-kebab-case';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { loadPromptsModule } from '../../common/loadPromptsModule';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import {
     buildCoderPromptSection,
@@ -49,15 +55,19 @@ const FALLBACK_PROMPT_SLUG = 'prompt';
 export function $initializeCoderAddCommand(program: Program): $side_effect {
     const command = program.command('add');
     command.description(
-        spaceTrim(`
-            Add one ready-to-run prompt file to the queue
+        spaceTrim(
+            (block) => `
+                Add one ready-to-run prompt file to the queue
 
-            Provide the description as an argument, pipe it through stdin, or run without arguments to type it interactively:
-            - \`ptbk coder add "some new feature"\`
-            - \`ptbk coder add --priority 1 "some new feature"\`
-            - \`ptbk coder add <<EOF ... EOF\`
-            - \`ptbk coder add\`
-        `),
+                Provide the description as an argument, pipe it through stdin, or run without arguments to type it interactively:
+                - \`ptbk coder add "some new feature"\`
+                - \`ptbk coder add --priority 1 "some new feature"\`
+                - \`ptbk coder add <<EOF ... EOF\`
+                - \`ptbk coder add\`
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
+            `,
+        ),
     );
 
     command.argument('[description]', 'Plain-language description of the feature or task to implement');
@@ -77,22 +87,39 @@ export function $initializeCoderAddCommand(program: Program): $side_effect {
                 .join(', ')}) or a markdown file path relative to the current project root.
         `),
     );
+    addCoderGitSyncOptions(command);
 
     command.action(
         handleActionErrors(async (descriptionArgument: string | undefined, cliOptions) => {
             const { priority, template: templateOption } = cliOptions as {
                 readonly priority: number;
                 readonly template?: string;
-            };
+            } & CoderGitSyncCliOptions;
+
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
+            const projectPath = process.cwd();
 
             const description = await resolveCoderPromptDescription(descriptionArgument);
 
-            await addCoderPrompt({
-                projectPath: process.cwd(),
+            // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
+            const { $commitCoderChanges, $pullCoderChanges } = await import(
+                '../../../../scripts/run-codex-prompts/git/coderGitSync'
+            );
+
+            await $pullCoderChanges({ gitSync, projectPath });
+
+            const { /* filePath,*/ emojiTag } = await addCoderPrompt({
+                projectPath,
                 description,
                 priority,
                 templateOption,
             });
+
+            await $commitCoderChanges({
+                gitSync,
+                projectPath,
+                commitMessage: `${emojiTag} Add prompt`,
+            });
         }),
     );
 }
@@ -216,6 +243,7 @@ async function resolveCoderPromptDescription(descriptionArgument: string | undef
         return standardInputDescription;
     }
 
+    const { default: prompts } = await loadPromptsModule();
     const response = await prompts({
         type: 'text',
         name: 'description',

package/src/cli/cli-commands/coder/generate-boilerplates.ts

@@ -6,6 +6,12 @@ import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import {
     buildCoderPromptSection,
@@ -24,9 +30,13 @@ import {
 export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $side_effect {
     const command = program.command('generate-boilerplates');
     command.description(
-        spaceTrim(`
-            Generate prompt boilerplate files with unique emoji tags
-        `),
+        spaceTrim(
+            (block) => `
+                Generate prompt boilerplate files with unique emoji tags
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
+            `,
+        ),
     );
 
     command.option('--count <count>', `Number of prompt boilerplate files to generate`, '5');
@@ -40,22 +50,38 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
                 .join(', ')}) or a markdown file path relative to the current project root.
         `),
     );
+    addCoderGitSyncOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { count: countOption, template: templateOption } = cliOptions as {
                 readonly count: string;
                 readonly template?: string;
-            };
+            } & CoderGitSyncCliOptions;
 
             const filesCount = parseFilesCount(countOption);
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
+            const projectPath = process.cwd();
+
+            // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
+            const { $commitCoderChanges, $pullCoderChanges } = await import(
+                '../../../../scripts/run-codex-prompts/git/coderGitSync'
+            );
+
+            await $pullCoderChanges({ gitSync, projectPath });
 
             await generatePromptBoilerplate({
-                projectPath: process.cwd(),
+                projectPath,
                 filesCount,
                 templateOption,
             });
 
+            await $commitCoderChanges({
+                gitSync,
+                projectPath,
+                commitMessage: `Prompts ${filesCount}x`,
+            });
+
             return process.exit(0);
         }),
     );

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

@@ -3,6 +3,12 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
@@ -61,16 +67,36 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
 
                 Checks that the coding harnesses are installed globally and up to date:
                 ${block(listCheckedHarnessLabels())}
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `,
         ),
     );
 
+    addCoderGitSyncOptions(command);
+
     command.action(
-        handleActionErrors(async () => {
+        handleActionErrors(async (cliOptions) => {
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
             const projectPath = process.cwd();
+
+            // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
+            const { $commitCoderChanges, $pullCoderChanges } = await import(
+                '../../../../scripts/run-codex-prompts/git/coderGitSync'
+            );
+
+            await $pullCoderChanges({ gitSync, projectPath });
+
             const summary = await initializeCoderProjectConfiguration(projectPath);
             printInitializationSummary(summary);
             await generatePromptBoilerplate({ projectPath, filesCount: 5 });
+
+            await $commitCoderChanges({
+                gitSync,
+                projectPath,
+                commitMessage: 'Initialize Promptbook Coder',
+            });
+
             await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
         }),
     );

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

@@ -2,10 +2,9 @@ import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
-import { NotAllowed } from '../../../errors/NotAllowed';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
-import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { handleActionErrors } from '../common/handleActionErrors';
+import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import type { PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
 import {
     addPromptRunnerRuntimeOptions,
@@ -15,12 +14,9 @@ import {
 } from '../common/promptRunnerCliOptions';
 
 /**
- * Initializes `coder ping` command for Promptbook CLI utilities.
- *
- * The command makes one small, isolated harness/model call, prints its result
- * and reports how long the harness/model turn took.
+ * Initializes `coder ping` command for Promptbook CLI utilities
  *
- * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI
  *
  * @private internal function of `promptbookCli`
  */
@@ -28,15 +24,16 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
     const command = program.command('ping');
     command.description(
         spaceTrim(`
-            Test one harness and model connection with a small disposable task
+            Send one tiny dummy prompt to a harness and model to measure and warm them up
 
             ${PROMPT_RUNNER_DESCRIPTION}
 
             Features:
-            - Runs the dummy task in a temporary directory outside the current project
-            - Prints the result returned by the selected harness and model
-            - Reports the elapsed harness/model response time in milliseconds
-            - Can be used to start consuming an applicable harness/model quota before a longer run
+            - 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
+            - Leaves the project exactly as it was — nothing is read, written, changed or committed
+            - Use --no-ui to stream the raw harness output instead of only the compact result
         `),
     );
 
@@ -45,50 +42,31 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const normalizedOptions = normalizePromptRunnerSelectionCliOptions(
+            const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
             );
 
-            const agentName = normalizedOptions.agentName;
-            if (!agentName) {
-                throw new NotAllowed(
-                    spaceTrim(`
-                        A harness is required for \`ptbk coder ping\`.
+            await $ensureHarnessInstallations([runnerOptions.agentName]);
 
-                        Pass one with \`--harness <harness-name>\`.
-                    `),
-                );
-            }
-
-            await $ensureHarnessInstallations([agentName]);
+            // 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'
+            );
 
-            // Note: Import the runner-backed implementation dynamically to avoid loading heavy dependencies until needed.
-            const { runCoderPing } = await import('../../../../scripts/run-agent-chat/runCoderPing');
-            const pingResult = await runCoderPing({
-                agentName,
-                model: normalizedOptions.model,
-                thinkingLevel: normalizedOptions.thinkingLevel,
-                isUiDisabled: normalizedOptions.noUi,
-                isCreditsAllowed: normalizedOptions.allowCredits,
+            const result = await pingCoderHarness({
+                agentName: runnerOptions.agentName,
+                model: runnerOptions.model,
+                thinkingLevel: runnerOptions.thinkingLevel,
+                allowCredits: runnerOptions.allowCredits,
+                shouldPrintLiveOutput: runnerOptions.noUi,
             });
 
-            printCoderPingResult(pingResult);
+            printCoderPingResult(result);
         }),
     );
 }
 
-/**
- * Prints the result and duration of one completed coder ping.
- */
-function printCoderPingResult(pingResult: { readonly result: string; readonly elapsedTimeMs: number }): void {
-    console.info(
-        spaceTrim(`
-            Result: ${pingResult.result}
-            Time: ${pingResult.elapsedTimeMs.toFixed(0)} ms
-        `),
-    );
-}
-
 // Note: [🟡] Code for CLI command [ping](src/cli/cli-commands/coder/ping.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name

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

@@ -4,6 +4,12 @@ import type {
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
+import {
+    addCoderGitSyncOptions,
+    CODER_GIT_SYNC_DESCRIPTION,
+    normalizeCoderGitSyncCliOptions,
+} from '../common/coderGitSyncCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -16,17 +22,23 @@ import { handleActionErrors } from '../common/handleActionErrors';
 export function $initializeCoderVerifyCommand(program: Program): $side_effect {
     const command = program.command('verify');
     command.description(
-        spaceTrim(`
-            Interactive verification helper for completed prompts
+        spaceTrim(
+            (block) => `
+                Interactive verification helper for completed prompts
 
-            Features:
-            - Displays list of prompt files with status counts
-            - Guides through verification of completed prompts marked [x]
-            - Archives verified prompt files to prompts/done/ directory
-            - Auto-appends repair prompts for incomplete work
-            - Processes files with all-done prompts first
-            - Supports ignoring matching prompt candidates for one verification run
-        `),
+                Features:
+                - Displays list of prompt files with status counts
+                - Guides through verification of completed prompts marked [x]
+                - Archives verified prompt files to prompts/done/ directory
+                - Auto-appends repair prompts for incomplete work
+                - Processes files with all-done prompts first
+                - Supports ignoring matching prompt candidates for one verification run
+
+                ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                Note: The git synchronization is applied around each single verification, not once per run.
+            `,
+        ),
     );
 
     command.option('--reverse', 'Process prompt files in reverse order', false);
@@ -36,19 +48,22 @@ export function $initializeCoderVerifyCommand(program: Program): $side_effect {
         collectStringOption,
         [],
     );
+    addCoderGitSyncOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
             const { reverse, ignore } = cliOptions as {
                 readonly reverse: boolean;
                 readonly ignore: ReadonlyArray<string>;
-            };
+            } & CoderGitSyncCliOptions;
+
+            const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
 
             // Note: Import the main function dynamically to avoid loading heavy dependencies until needed
             const { verifyPrompts } = await import('../../../../scripts/verify-prompts/verify-prompts');
 
             try {
-                await verifyPrompts({ reverse, ignore });
+                await verifyPrompts({ reverse, ignore, gitSync });
             } catch (error) {
                 console.error(colors.bgRed('Prompt verification failed:'), error);
                 return process.exit(1);

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

@@ -23,8 +23,8 @@ import { $initializeCoderVerifyCommand } from './coder/verify';
  * - add: Add one ready-to-run prompt file to the queue
  * - generate-boilerplates: Generate prompt boilerplate files
  * - find-refactor-candidates: Find files that need refactoring
- * - ping: Test one harness and model connection with a disposable task
  * - run: Run coding prompts with AI agents
+ * - ping: Test one harness and model with a tiny dummy prompt
  * - verify: Verify completed prompts
  * - find-fresh-emoji-tags: Find unused emoji tags
  *
@@ -44,8 +44,8 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
             - find-unwritten: List prompt sections that still need to be authored
-            - ping: Test one harness and model connection with a disposable task
             - run: Run coding prompts with AI agents
+            - ping: Test the connection, response time and quota of one harness and model
             - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
             - find-fresh-emoji-tags: Find unused emoji tags
@@ -58,8 +58,8 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
     $initializeCoderFindUnwrittenCommand(coderCommand);
-    $initializeCoderPingCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderPingCommand(coderCommand);
     $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);