@promptbook/cli 0.114.0-13 → 0.114.0-18

package/esm/index.es.js

@@ -4,7 +4,7 @@ import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import { writeFile, stat, mkdir, readFile, readdir, rm, cp, lstat, symlink, rename, unlink, appendFile, realpath, copyFile, access, constants, watch, rmdir } from 'fs/promises';
 import { join, delimiter, relative, basename, resolve, dirname, isAbsolute, extname } from 'path';
 import { createHash, randomBytes } from 'crypto';
-import { spawn, spawnSync } from 'child_process';
+import { spawn, spawnSync, execFile } from 'child_process';
 import moment from 'moment';
 import * as fs from 'fs';
 import { createWriteStream, mkdirSync, writeFileSync, statSync, readFileSync, existsSync, promises } from 'fs';
@@ -48,7 +48,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-13';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-18';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2207,7 +2207,7 @@ async function isExistingFile$4(path) {
  */
 async function ensureDirectory(projectPath, relativeDirectoryPath) {
     const directoryPath = join(projectPath, relativeDirectoryPath);
-    const isDirectoryExisting = await isExistingDirectory$1(directoryPath);
+    const isDirectoryExisting = await isExistingDirectory$2(directoryPath);
     if (!isDirectoryExisting) {
         await mkdir(directoryPath, { recursive: true });
         return 'created';
@@ -2217,7 +2217,7 @@ async function ensureDirectory(projectPath, relativeDirectoryPath) {
 /**
  * Checks whether a path exists and is a directory.
  */
-async function isExistingDirectory$1(path) {
+async function isExistingDirectory$2(path) {
     try {
         return (await stat(path)).isDirectory();
     }
@@ -5716,6 +5716,12 @@ class FromCommitmentDefinition extends BaseCommitmentDefinition {
 
             Inherits agent source from another agent.
 
+            Every agent inherits from the core agent \`@Adam\` unless it says otherwise, so writing no ${this.type} at all
+            is the same as writing \`${this.type} @Adam\`. Write \`${this.type} @Null\` to inherit from nothing.
+
+            An agent has exactly one parent, so when ${this.type} is written more than once, the last one wins and
+            overrides every earlier one.
+
             ## Examples
 
             \`\`\`book
@@ -5724,6 +5730,13 @@ class FromCommitmentDefinition extends BaseCommitmentDefinition {
             FROM https://s6.ptbk.io/benjamin-white
             RULE Speak only in English.
             \`\`\`
+
+            \`\`\`book
+            My Standalone Agent
+
+            FROM @Null
+            RULE Speak only in English.
+            \`\`\`
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
@@ -30572,6 +30585,385 @@ function buildPromptTestScriptPath(scriptPath) {
     return `${scriptPath}.test.sh`;
 }
 
+/**
+ * Lists the direct project directories of one agent folder.
+ *
+ * @param agentFolderPath - Absolute path of the local agent folder.
+ * @returns Project directory names, or an empty list when the agent has no projects folder.
+ */
+async function listAgentProjectDirectoryNames(agentFolderPath) {
+    try {
+        const projectsRootEntries = await readdir(join(agentFolderPath, AGENT_PROJECTS_DIRECTORY_PATH), {
+            withFileTypes: true,
+        });
+        return projectsRootEntries
+            .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
+            .map((projectDirectoryEntry) => projectDirectoryEntry.name);
+    }
+    catch (_a) {
+        return [];
+    }
+}
+
+/**
+ * Largest git output kept in memory, so an enormous diff can never exhaust the runner process.
+ */
+const AGENT_PROJECT_GIT_OUTPUT_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * Time after which one git command of a project repository is given up on.
+ */
+const AGENT_PROJECT_GIT_TIMEOUT_MS = 60 * 1000;
+/**
+ * Author and committer used for project commits when no coding-agent identity is configured.
+ *
+ * A project repository is created by the runner on a server which usually has no git identity at
+ * all, so committing must never depend on the machine configuration.
+ */
+const AGENT_PROJECT_GIT_FALLBACK_IDENTITY = {
+    GIT_AUTHOR_NAME: 'Promptbook Agent',
+    GIT_AUTHOR_EMAIL: 'agent@promptbook.studio',
+    GIT_COMMITTER_NAME: 'Promptbook Agent',
+    GIT_COMMITTER_EMAIL: 'agent@promptbook.studio',
+};
+/**
+ * Runs one git command inside one agent project directory.
+ *
+ * Commands are executed without a shell and with an explicit argument list, so a project name or
+ * a file path can never be interpreted as a shell fragment. A failing command is reported through
+ * `isSuccessful` instead of throwing, because git uses the exit code to answer questions such as
+ * "is there anything staged" and because auto-committing a project must never fail an answer the
+ * agent already produced.
+ *
+ * @param options - Project directory and the git arguments to run there.
+ * @returns Outcome of the command.
+ */
+async function runAgentProjectGitCommand(options) {
+    return await new Promise((resolve) => {
+        execFile('git', [...options.args], {
+            cwd: options.projectPath,
+            env: { ...process.env, ...AGENT_PROJECT_GIT_FALLBACK_IDENTITY, ...(buildAgentGitEnv() || {}) },
+            maxBuffer: AGENT_PROJECT_GIT_OUTPUT_MAX_BYTES,
+            timeout: AGENT_PROJECT_GIT_TIMEOUT_MS,
+            windowsHide: true,
+        }, (error, stdout) => {
+            resolve({
+                isSuccessful: !error,
+                output: stripTrailingNewline(stdout || ''),
+            });
+        });
+    });
+}
+/**
+ * Removes the single trailing newline git appends to its output.
+ *
+ * @param output - Raw command output.
+ * @returns Output without its trailing newline.
+ *
+ * @private helper of `runAgentProjectGitCommand`
+ */
+function stripTrailingNewline(output) {
+    return output.replace(/\r?\n$/u, '');
+}
+
+/**
+ * Branch created for a project repository, so every agent project starts with the same history.
+ */
+const AGENT_PROJECT_GIT_INITIAL_BRANCH = 'main';
+/**
+ * Paths kept out of a project repository created by the runner.
+ *
+ * Only a project which brings no ignore rules of its own receives these, and they cover exactly
+ * the two things that must never enter an automatic commit: installed dependencies and secrets.
+ */
+const AGENT_PROJECT_GIT_DEFAULT_IGNORE_PATHS = spaceTrim$1(`
+    node_modules/
+    .env
+    .env.*
+`);
+/**
+ * Makes sure one agent project is a git repository of its own.
+ *
+ * A project which is already tracked by a repository around the agent folder is deliberately left
+ * alone: initializing a repository inside it would turn it into an embedded repository and break
+ * the history that already covers it.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns How the project relates to git after this call.
+ */
+async function ensureAgentProjectGitRepository(projectPath) {
+    if (await isExistingDirectory$1(join(projectPath, '.git'))) {
+        return 'own-repository';
+    }
+    if (await isProjectTrackedByOuterRepository(projectPath)) {
+        return 'tracked-elsewhere';
+    }
+    if (!(await initializeAgentProjectGitRepository(projectPath))) {
+        return 'unavailable';
+    }
+    await writeDefaultAgentProjectGitignoreIfMissing(projectPath);
+    return 'own-repository';
+}
+/**
+ * Creates the repository of one project, naming its first branch when git supports it.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns `true` when the project is a repository afterwards.
+ *
+ * @private helper of `ensureAgentProjectGitRepository`
+ */
+async function initializeAgentProjectGitRepository(projectPath) {
+    const initResult = await runAgentProjectGitCommand({
+        projectPath,
+        args: ['init', `--initial-branch=${AGENT_PROJECT_GIT_INITIAL_BRANCH}`],
+    });
+    if (initResult.isSuccessful) {
+        return true;
+    }
+    // Note: `--initial-branch` needs git 2.28, so an older git still gets its repository
+    return (await runAgentProjectGitCommand({ projectPath, args: ['init'] })).isSuccessful;
+}
+/**
+ * Checks whether a repository around the agent folder already tracks the project files.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns `true` when an outer repository tracks at least one file of the project.
+ *
+ * @private helper of `ensureAgentProjectGitRepository`
+ */
+async function isProjectTrackedByOuterRepository(projectPath) {
+    const trackedFilesResult = await runAgentProjectGitCommand({
+        projectPath,
+        args: ['ls-files', '--', '.'],
+    });
+    return trackedFilesResult.isSuccessful && trackedFilesResult.output.trim().length > 0;
+}
+/**
+ * Writes the default ignore rules into a freshly initialized project repository.
+ *
+ * A project which already brings its own rules keeps them untouched.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ *
+ * @private helper of `ensureAgentProjectGitRepository`
+ */
+async function writeDefaultAgentProjectGitignoreIfMissing(projectPath) {
+    const gitignorePath = join(projectPath, '.gitignore');
+    try {
+        await stat(gitignorePath);
+        return;
+    }
+    catch (_a) {
+        // Note: A project without ignore rules would commit its installed dependencies
+    }
+    await writeFile(gitignorePath, `${AGENT_PROJECT_GIT_DEFAULT_IGNORE_PATHS}\n`, 'utf-8');
+}
+/**
+ * Checks whether one path is an existing directory.
+ *
+ * @param directoryPath - Absolute path to check.
+ * @returns `true` when the path exists and is a directory.
+ *
+ * @private helper of `ensureAgentProjectGitRepository`
+ */
+async function isExistingDirectory$1(directoryPath) {
+    try {
+        return (await stat(directoryPath)).isDirectory();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+
+/**
+ * Largest diff carried into a chat, so one huge commit cannot bloat every message payload.
+ */
+const AGENT_PROJECT_DIFF_MAX_LENGTH = 20000;
+/**
+ * Describes the latest commit of one agent project repository.
+ *
+ * @param options - Project directory and the project name the description is reported under.
+ * @returns Description of the commit, or `null` when git could not describe it.
+ */
+async function readAgentProjectCommitChange(options) {
+    const { projectPath, projectName } = options;
+    const [commitHashResult, committedAtResult, numstatResult, diffResult] = await Promise.all([
+        runAgentProjectGitCommand({ projectPath, args: ['rev-parse', 'HEAD'] }),
+        runAgentProjectGitCommand({ projectPath, args: ['show', '--no-patch', '--format=%cI', 'HEAD'] }),
+        runAgentProjectGitCommand({ projectPath, args: ['show', '--numstat', '--format=', 'HEAD'] }),
+        runAgentProjectGitCommand({ projectPath, args: ['show', '--patch', '--format=', 'HEAD'] }),
+    ]);
+    if (!commitHashResult.isSuccessful || commitHashResult.output.trim().length === 0) {
+        return null;
+    }
+    const changedFiles = parseAgentProjectNumstat(numstatResult.isSuccessful ? numstatResult.output : '');
+    const diff = diffResult.isSuccessful ? diffResult.output : '';
+    return {
+        projectName,
+        commitHash: commitHashResult.output.trim(),
+        committedAt: resolveCommittedAt(committedAtResult.isSuccessful ? committedAtResult.output : ''),
+        changedFiles,
+        insertionCount: sumChangedFileCounts(changedFiles, 'insertionCount'),
+        deletionCount: sumChangedFileCounts(changedFiles, 'deletionCount'),
+        diff: diff.slice(0, AGENT_PROJECT_DIFF_MAX_LENGTH),
+        isDiffTruncated: diff.length > AGENT_PROJECT_DIFF_MAX_LENGTH,
+    };
+}
+/**
+ * Parses the `git show --numstat` output into changed files.
+ *
+ * Binary files report `-` instead of line counts, which is kept as a zero-line change so the file
+ * is still listed as touched.
+ *
+ * @param numstatOutput - Raw numstat output.
+ * @returns Changed files in the order git reported them.
+ *
+ * @private helper of `readAgentProjectCommitChange`
+ */
+function parseAgentProjectNumstat(numstatOutput) {
+    return numstatOutput
+        .split(/\r?\n/u)
+        .map((numstatLine) => numstatLine.split('\t'))
+        .filter((numstatColumns) => numstatColumns.length >= 3 && numstatColumns[2].trim().length > 0)
+        .map((numstatColumns) => ({
+        path: numstatColumns.slice(2).join('\t').trim(),
+        insertionCount: parseChangedLineCount(numstatColumns[0]),
+        deletionCount: parseChangedLineCount(numstatColumns[1]),
+    }));
+}
+/**
+ * Parses one numstat line count.
+ *
+ * @param rawLineCount - Raw numstat column.
+ * @returns Parsed count, or `0` for binary files and unparseable columns.
+ *
+ * @private helper of `readAgentProjectCommitChange`
+ */
+function parseChangedLineCount(rawLineCount) {
+    const parsedLineCount = Number.parseInt(rawLineCount.trim(), 10);
+    return Number.isFinite(parsedLineCount) && parsedLineCount >= 0 ? parsedLineCount : 0;
+}
+/**
+ * Sums one line-count field across all changed files.
+ *
+ * @param changedFiles - Changed files of the commit.
+ * @param countName - Field to sum.
+ * @returns Total count.
+ *
+ * @private helper of `readAgentProjectCommitChange`
+ */
+function sumChangedFileCounts(changedFiles, countName) {
+    return changedFiles.reduce((total, changedFile) => total + changedFile[countName], 0);
+}
+/**
+ * Normalizes the commit timestamp git reported.
+ *
+ * @param rawCommittedAt - Raw ISO timestamp from git.
+ * @returns Usable ISO timestamp, falling back to the current time when git reported none.
+ *
+ * @private helper of `readAgentProjectCommitChange`
+ */
+function resolveCommittedAt(rawCommittedAt) {
+    const trimmedCommittedAt = rawCommittedAt.trim();
+    if (trimmedCommittedAt.length === 0 || !Number.isFinite(Date.parse(trimmedCommittedAt))) {
+        return new Date().toISOString();
+    }
+    return new Date(trimmedCommittedAt).toISOString();
+}
+
+/**
+ * Commits everything one answered message changed inside one agent project.
+ *
+ * The project is turned into a git repository first when it is not one yet, so the work of every
+ * answer stays recoverable and reviewable as a normal commit history.
+ *
+ * @param options - Project identity and the commit message describing the answered message.
+ * @returns What was committed, or `null` when the project changed nothing or cannot be committed.
+ */
+async function commitAgentProjectChanges(options) {
+    const { projectPath, projectName, commitMessage } = options;
+    if ((await ensureAgentProjectGitRepository(projectPath)) !== 'own-repository') {
+        return null;
+    }
+    const stageResult = await runAgentProjectGitCommand({ projectPath, args: ['add', '--all', '--', '.'] });
+    if (!stageResult.isSuccessful) {
+        return null;
+    }
+    if (!(await hasStagedAgentProjectChanges(projectPath))) {
+        return null;
+    }
+    const commitResult = await runAgentProjectGitCommand({
+        projectPath,
+        args: ['commit', '--message', commitMessage],
+    });
+    if (!commitResult.isSuccessful) {
+        return null;
+    }
+    return await readAgentProjectCommitChange({ projectPath, projectName });
+}
+/**
+ * Checks whether the project index holds anything to commit.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns `true` when committing would create a non-empty commit.
+ *
+ * @private helper of `commitAgentProjectChanges`
+ */
+async function hasStagedAgentProjectChanges(projectPath) {
+    // Note: `--quiet` makes git answer through its exit code — success means nothing is staged
+    const stagedChangesResult = await runAgentProjectGitCommand({
+        projectPath,
+        args: ['diff', '--cached', '--quiet'],
+    });
+    return !stagedChangesResult.isSuccessful;
+}
+
+/**
+ * Commits what one answered message changed in every project of one agent.
+ *
+ * Every project of an agent is its own git repository, so each answer which modified one becomes a
+ * commit there. The projects are committed one after another because they share the git executable
+ * and because an agent works with a handful of projects at most.
+ *
+ * Committing is best-effort bookkeeping around an answer the agent already produced: a project
+ * whose commit fails is reported to the console and skipped instead of failing the message.
+ *
+ * @param options - Agent folder and the commit message describing the answered message.
+ * @returns What was committed, one entry per project the message really changed.
+ */
+async function commitAnsweredMessageProjectChanges(options) {
+    const { agentFolderPath, commitMessage } = options;
+    const projectNames = await listAgentProjectDirectoryNames(agentFolderPath);
+    const projectChanges = [];
+    for (const projectName of projectNames) {
+        const projectChange = await commitAgentProjectChangesSafely({
+            projectPath: join(agentFolderPath, AGENT_PROJECTS_DIRECTORY_PATH, projectName),
+            projectName,
+            commitMessage,
+        });
+        if (projectChange) {
+            projectChanges.push(projectChange);
+        }
+    }
+    return projectChanges;
+}
+/**
+ * Commits one project without letting its failure reach the answered message.
+ *
+ * @param options - Project identity and commit message.
+ * @returns What was committed, or `null` when nothing changed or committing failed.
+ *
+ * @private helper of `commitAnsweredMessageProjectChanges`
+ */
+async function commitAgentProjectChangesSafely(options) {
+    try {
+        return await commitAgentProjectChanges(options);
+    }
+    catch (error) {
+        console.warn(colors.yellow(`Could not commit changes of project "${options.projectName}"`), error);
+        return null;
+    }
+}
+
 /**
  * Checks whether one repository-relative path is tracked by Git.
  */
@@ -30617,7 +31009,7 @@ function buildAgentProjectsPromptSection(options = {}) {
 
             - You have 100% control over every project folder: create, read, modify, and delete files there, run scripts and commands inside it, and keep any persistent data you need between conversations.
             - When the user asks you to build something (for example a website) or to do longer-term work, create a new project folder \`${AGENT_PROJECTS_DIRECTORY_PATH}/<project-name>/\` (use a short kebab-case name) and do the work inside it. Modify an existing project when the user refers to work you already did.
-            - A project can be a git repository — you can run \`git init\` inside a project folder and commit your work there.
+            - Every project is a git repository and everything you change in one is committed there automatically once you finish the message, so you never need to run \`git init\` or \`git commit\` yourself and your work stays recoverable.
             - Do not touch anything outside the \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory beyond the file changes allowed at the top of this prompt.
 
             ${block(buildProjectReferenceInstructions(projectsUrlPath))}
@@ -30749,13 +31141,79 @@ function formatTimeoutUnit(value, unit) {
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Describes one planned-message schedule in a single sentence fragment.
+ *
+ * A planned message can repeat forever, repeat a bounded number of times, run inside a date window, or
+ * wake the agent only once. Every surface showing a planned message — the wake-up itself, the goal-chat
+ * notes, the planned-message prompt section, and the model tools — describes it with this one helper,
+ * so an agent never has to reconcile two different wordings of the same plan.
+ *
+ * @param schedule - Schedule of the planned message.
+ * @returns Fragment such as `repeats every 5 minutes (2 of 10 runs done)`.
+ *
+ * @private internal utility of the Agents Server planned messages
+ */
+function describeAgentPlannedMessageSchedule(schedule) {
+    const scheduleParts = [
+        describeAgentPlannedMessageRecurrence(schedule),
+        ...describeAgentPlannedMessageBounds(schedule),
+    ];
+    return scheduleParts.join(', ');
+}
+/**
+ * Describes how often one planned message wakes the agent.
+ *
+ * @param schedule - Schedule of the planned message.
+ * @returns Recurrence fragment.
+ *
+ * @private internal utility of `describeAgentPlannedMessageSchedule`
+ */
+function describeAgentPlannedMessageRecurrence(schedule) {
+    if (schedule.cronExpression) {
+        return `repeats on cron \`${schedule.cronExpression}\``;
+    }
+    if (schedule.intervalMs) {
+        return `repeats every ${formatTimeoutDurationHuman(schedule.intervalMs)}`;
+    }
+    return schedule.dueAt ? `wakes you once at ${schedule.dueAt}` : 'wakes you once';
+}
+/**
+ * Describes the bounds limiting how long one planned message keeps repeating.
+ *
+ * @param schedule - Schedule of the planned message.
+ * @returns Fragments for the starting date, ending date, and run count that are really set.
+ *
+ * @private internal utility of `describeAgentPlannedMessageSchedule`
+ */
+function describeAgentPlannedMessageBounds(schedule) {
+    const bounds = [];
+    const runCount = schedule.runCount || 0;
+    if (schedule.startsAt) {
+        bounds.push(`starting ${schedule.startsAt}`);
+    }
+    if (schedule.endsAt) {
+        bounds.push(`until ${schedule.endsAt}`);
+    }
+    if (schedule.maxRunCount) {
+        bounds.push(`${runCount} of ${schedule.maxRunCount} runs done`);
+    }
+    else if (runCount > 0) {
+        bounds.push(`${runCount} run${runCount === 1 ? '' : 's'} done`);
+    }
+    if ((schedule.cronExpression || schedule.intervalMs) && schedule.dueAt) {
+        bounds.push(`next at ${schedule.dueAt}`);
+    }
+    return bounds;
+}
+
 /**
  * Builds the planned-message instructions available to an Agents Server-managed coding agent.
  *
  * Planned messages always target the agent's singleton goal chat, regardless of the chat in which the
- * wake-up is planned, and they repeat like `setInterval` until they are cancelled. The sidecar file is
- * the only channel that changes them, so an answer that merely claims a follow-up was planned changes
- * nothing — and an answer that changes nothing keeps the current plan running.
+ * wake-up is planned, and each of them keeps repeating until its schedule is over or it is cancelled.
+ * The sidecar file is the only channel that changes them, so an answer that merely claims a follow-up
+ * was planned changes nothing — and an answer that changes nothing keeps the current plan running.
  *
  * @param sidecar - Sidecar prepared by the Agents Server for the answered message.
  * @returns Prompt section, or an empty string outside Agents Server-managed runs.
@@ -30767,19 +31225,25 @@ function buildAgentGoalChatPromptSection(sidecar) {
     return spaceTrim$1((block) => `
             ## Planned goal-chat messages
 
-            You can plan a message that repeatedly wakes you in your singleton goal chat. A planned message works like \`setInterval\`, not like \`setTimeout\`: once planned, it keeps waking you at its interval until you cancel it. This works during every Agents Server-managed chat invocation, not only while answering inside the goal chat.
+            You can plan a message that wakes you in your singleton goal chat. A planned message works like \`setInterval\`, not like \`setTimeout\`: once planned, it keeps waking you until its schedule is over or you cancel it. This works during every Agents Server-managed chat invocation, not only while answering inside the goal chat.
 
             ${block(buildCurrentPlannedMessagesLines(sidecar.currentPlannedMessages))}
 
             Editing \`${sidecar.relativeSidecarPath}\` is the **only** way to change what wakes you. Writing in your answer that you scheduled something does not schedule anything.
 
-            -   **Keeping your planned messages as they are is the default.** When the list above already matches your goal, leave \`commands\` empty — every listed message keeps repeating on its own, and re-planning it would only duplicate it.
-            -   When your goal needs a repeating wake-up that is not listed above, append \`{"action":"set","milliseconds":<repeat interval>,"message":"<what each future invocation must do>"}\` to the \`commands\` array of that file.
-            -   When a listed message no longer matches your goal (for example your goal now says every 10 minutes while the message repeats every 5 minutes), append \`{"action":"cancel","timeoutId":"<timeout id>"}\` and one \`set\` command with the interval your goal really requires.
-            -   When your goal no longer needs a listed message at all, cancel it without planning a replacement.
+            -   **Keeping your planned messages as they are is the default.** When the list above already matches your goal, leave \`commands\` empty — every listed message keeps waking you on its own, and re-planning it would only duplicate it.
+            -   When your goal needs a wake-up that is not listed above, append \`{"action":"set","milliseconds":<repeat interval>,"message":"<what each future invocation must do>"}\` to the \`commands\` array of that file.
+            -   A planned message is shaped by these fields, which \`set\` and \`update\` both accept:
+                -   \`milliseconds\` — repeat interval of at least \`60000\`, or
+                -   \`cronExpression\` — a five-field cron such as \`"0 9 * * 1-5"\`, evaluated in the server time zone (use **either** this **or** \`milliseconds\`),
+                -   \`maxRunCount\` — how many times in total the message wakes you, for example \`1\` for a one-off message,
+                -   \`startsAt\` and \`endsAt\` — ISO dates bounding when it may wake you, for example \`"2026-09-01T08:00:00.000Z"\`.
+            -   When a listed message no longer matches your goal, append \`{"action":"update","timeoutId":"<timeout id>","<field>":<new value>}\` with only the fields you want to change. The message keeps its id, a field you leave out stays as it is, and \`null\` removes a bound such as \`endsAt\`. Use \`update\` instead of cancelling and planning the same message again.
+            -   When your goal no longer needs a listed message at all, append \`{"action":"cancel","timeoutId":"<timeout id>"}\` without planning a replacement.
             -   Never edit \`version\`, \`agentPermanentId\`, or \`currentPlannedMessages\`.
-            -   The Agents Server applies every command once your answer is finished, and each repetition appears in the goal chat and invokes you there.
-            -   Only mention a planned follow-up in your answer when it is really planned: either you appended the matching \`set\` command, or you kept one of the messages listed above.
+            -   The Agents Server applies every command once your answer is finished, and each wake-up appears in the goal chat and invokes you there.
+            -   A planned message which finished — because it ran \`maxRunCount\` times or passed its \`endsAt\` — stops on its own and disappears from the list above, so you never have to clean it up.
+            -   Only mention a planned follow-up in your answer when it is really planned: either you appended the matching \`set\` or \`update\` command, or you kept one of the messages listed above.
         `);
 }
 /**
@@ -30812,10 +31276,7 @@ function buildCurrentPlannedMessagesLines(currentPlannedMessages) {
 function createCurrentPlannedMessageLine(plannedMessage) {
     var _a;
     const message = ((_a = plannedMessage.message) === null || _a === void 0 ? void 0 : _a.trim()) || 'Continue working towards the current goal.';
-    const schedule = plannedMessage.intervalMs
-        ? `repeats every ${formatTimeoutDurationHuman(plannedMessage.intervalMs)}`
-        : `wakes you once at ${plannedMessage.dueAt}`;
-    return `-   \`${plannedMessage.timeoutId}\` ${schedule}: ${message}`;
+    return `-   \`${plannedMessage.timeoutId}\` ${describeAgentPlannedMessageSchedule(plannedMessage)}: ${message}`;
 }
 
 /**
@@ -37875,7 +38336,7 @@ const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH
  *
  * @private internal convention shared by the Agents Server and agent-folder runner
  */
-const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'cancel'];
+const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'update', 'cancel'];
 /**
  * Creates the relative planned-message sidecar path of one queued message.
  *
@@ -37967,19 +38428,35 @@ function normalizeAgentPlannedMessageSnapshots(rawSnapshots) {
  * Normalizes the optional fields of one already planned message.
  *
  * @param snapshot - Planned-message entry with the required identity fields.
- * @returns Snapshot with a usable repeat interval and message.
+ * @returns Snapshot with a usable schedule and message.
  *
  * @private internal utility of `parseAgentPlannedMessagesSidecar`
  */
 function createNormalizedAgentPlannedMessageSnapshot(snapshot) {
-    const intervalMs = Number(snapshot.intervalMs);
     return {
         timeoutId: snapshot.timeoutId,
         dueAt: snapshot.dueAt,
         message: typeof snapshot.message === 'string' ? snapshot.message : null,
-        intervalMs: Number.isFinite(intervalMs) && intervalMs > 0 ? Math.floor(intervalMs) : null,
+        intervalMs: normalizeAgentPlannedMessagePositiveCount(snapshot.intervalMs),
+        cronExpression: typeof snapshot.cronExpression === 'string' ? snapshot.cronExpression : null,
+        startsAt: typeof snapshot.startsAt === 'string' ? snapshot.startsAt : null,
+        endsAt: typeof snapshot.endsAt === 'string' ? snapshot.endsAt : null,
+        maxRunCount: normalizeAgentPlannedMessagePositiveCount(snapshot.maxRunCount),
+        runCount: normalizeAgentPlannedMessagePositiveCount(snapshot.runCount) || 0,
     };
 }
+/**
+ * Normalizes one optional positive whole number of a planned-message snapshot.
+ *
+ * @param value - Untrusted interval, run count, or run-count limit.
+ * @returns Whole positive number, or `null` when the value cannot be used.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessagePositiveCount(value) {
+    const numericValue = Number(value);
+    return Number.isFinite(numericValue) && numericValue > 0 ? Math.floor(numericValue) : null;
+}
 /**
  * Checks whether one untrusted sidecar entry describes an already planned message.
  *
@@ -38205,6 +38682,286 @@ function parseAgentMessageRuntimeLogEvent(line) {
     }
 }
 
+/**
+ * Maximum count of external sources reported for one answered message.
+ *
+ * A single answer can reach the same kind of source many times, so the chip row below it stays
+ * readable by keeping only the sources touched first.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const MAX_TOUCHED_EXTERNAL_SOURCES = 12;
+/**
+ * Maximum length of one search query shown as the name of a touched search source.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const MAX_SEARCH_QUERY_LENGTH = 48;
+/**
+ * Separator between the segments of one integration tool name, as in `mcp__gmail__create_draft`.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const INTEGRATION_TOOL_NAME_SEPARATOR = '__';
+/**
+ * First segment marking one tool name as belonging to an integration.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const INTEGRATION_TOOL_NAME_PREFIX = 'mcp';
+/**
+ * Names of the harness tools which look something up on the web, indexed for case-insensitive matching.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const WEB_SEARCH_TOOL_NAMES = new Set(['WebSearch', 'web_search'].map((webSearchToolName) => webSearchToolName.toLowerCase()));
+/**
+ * Matches one shell command invoking a network client, whose arguments therefore address the outside world.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const NETWORK_CLIENT_COMMAND_REGEX = /(^|[\s|;&(])(curl|wget|invoke-webrequest|iwr)\b/iu;
+/**
+ * Matches one web address inside a shell command.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const COMMAND_URL_REGEX = /https?:\/\/[^\s"'`<>)\]]+/giu;
+/**
+ * Separators used between the words of one integration name.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const INTEGRATION_NAME_WORD_SEPARATOR_REGEX = /[-_.\s]+/gu;
+/**
+ * Hostnames which address the machine the agent runs on and are therefore not external.
+ *
+ * @private internal constant of agent-message touched external sources
+ */
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1', '[::1]']);
+/**
+ * Resolves which sources outside the agent one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a source counts as touched when the
+ * harness reached it in a tool invocation — calling an integration, fetching a web address,
+ * searching the web, or running a network client in the shell. Only tool payloads are inspected:
+ * tool results and assistant narration are ignored so a service merely mentioned in the
+ * conversation is never reported, and addresses of the machine the agent runs on are dropped
+ * because they are internal.
+ *
+ * @param options - Raw runtime log content of one answered message.
+ * @returns Touched external sources without duplicates, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+function resolveAgentMessageTouchedExternalSources(options) {
+    const touchedExternalSources = new Map();
+    for (const event of parseAgentMessageRuntimeLogEvents(options.logText)) {
+        for (const externalSource of resolveRuntimeLogEventExternalSources(event)) {
+            const externalSourceKey = createExternalSourceKey(externalSource);
+            if (!touchedExternalSources.has(externalSourceKey)) {
+                touchedExternalSources.set(externalSourceKey, externalSource);
+            }
+            if (touchedExternalSources.size === MAX_TOUCHED_EXTERNAL_SOURCES) {
+                return Array.from(touchedExternalSources.values());
+            }
+        }
+    }
+    return Array.from(touchedExternalSources.values());
+}
+/**
+ * Collects every external source described by one runtime log event.
+ *
+ * Claude Code reports tool invocations as `tool_use` content blocks, while Codex reports executed
+ * commands, web searches, and integration calls as items.
+ *
+ * @param event - One structured runtime log event.
+ * @returns External sources the event reached, possibly with duplicates.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function resolveRuntimeLogEventExternalSources(event) {
+    var _a;
+    const externalSources = [];
+    for (const contentBlock of ((_a = event.message) === null || _a === void 0 ? void 0 : _a.content) || []) {
+        if (contentBlock.type === 'tool_use') {
+            externalSources.push(...resolveToolUseExternalSources(contentBlock));
+        }
+    }
+    externalSources.push(...resolveCodexItemExternalSources(event.item));
+    return externalSources;
+}
+/**
+ * Collects the external sources reached by one Claude Code tool invocation.
+ *
+ * @param contentBlock - One `tool_use` content block.
+ * @returns External sources the invocation reached.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function resolveToolUseExternalSources(contentBlock) {
+    const toolName = contentBlock.name || '';
+    const toolInput = contentBlock.input || {};
+    return collectDefinedExternalSources([
+        createIntegrationExternalSource(resolveIntegrationName(toolName)),
+        typeof toolInput.url === 'string' ? createWebsiteExternalSource(toolInput.url) : null,
+        WEB_SEARCH_TOOL_NAMES.has(toolName.toLowerCase()) && typeof toolInput.query === 'string'
+            ? createSearchExternalSource(toolInput.query)
+            : null,
+        ...(typeof toolInput.command === 'string' ? resolveNetworkCommandExternalSources(toolInput.command) : []),
+    ]);
+}
+/**
+ * Collects the external sources reached by one Codex runtime item.
+ *
+ * @param item - One Codex item of a runtime log event.
+ * @returns External sources the item reached.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function resolveCodexItemExternalSources(item) {
+    if (!item) {
+        return [];
+    }
+    return collectDefinedExternalSources([
+        item.type === 'mcp_tool_call'
+            ? createIntegrationExternalSource(item.server || resolveIntegrationName(item.tool || ''))
+            : null,
+        item.type === 'web_search' && typeof item.query === 'string' ? createSearchExternalSource(item.query) : null,
+        ...(typeof item.command === 'string' ? resolveNetworkCommandExternalSources(item.command) : []),
+    ]);
+}
+/**
+ * Drops the candidates which turned out not to describe an external source.
+ *
+ * @param candidates - Resolved sources mixed with the candidates that resolved to nothing.
+ * @returns Only the sources which were resolved.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function collectDefinedExternalSources(candidates) {
+    return candidates.filter((candidate) => candidate !== null);
+}
+/**
+ * Resolves the integration a tool name belongs to, following the `mcp__<integration>__<tool>` convention.
+ *
+ * @param toolName - Raw harness tool name.
+ * @returns Raw integration name, or `null` when the tool belongs to no integration.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function resolveIntegrationName(toolName) {
+    const toolNameSegments = toolName.split(INTEGRATION_TOOL_NAME_SEPARATOR);
+    if (toolNameSegments.length < 3 || toolNameSegments[0].toLowerCase() !== INTEGRATION_TOOL_NAME_PREFIX) {
+        return null;
+    }
+    return toolNameSegments[1] || null;
+}
+/**
+ * Creates one touched integration source.
+ *
+ * @param integrationName - Raw integration name, or `null` when there is none.
+ * @returns Touched source, or `null` when the integration cannot be named.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function createIntegrationExternalSource(integrationName) {
+    const humanizedIntegrationName = humanizeIntegrationName(integrationName || '');
+    if (humanizedIntegrationName === '') {
+        return null;
+    }
+    return { kind: 'integration', name: humanizedIntegrationName };
+}
+/**
+ * Creates one touched website source.
+ *
+ * @param rawUrl - Raw web address the harness reached.
+ * @returns Touched source, or `null` when the address is unusable or addresses the local machine.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function createWebsiteExternalSource(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl.trim());
+    }
+    catch (_a) {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return null;
+    }
+    const hostname = url.hostname.toLowerCase();
+    if (hostname === '' || LOCAL_HOSTNAMES.has(hostname) || hostname.endsWith('.localhost')) {
+        return null;
+    }
+    return { kind: 'website', name: hostname, url: url.href };
+}
+/**
+ * Creates one touched web search source.
+ *
+ * @param query - Raw query the harness looked up.
+ * @returns Touched source, or `null` when the query is empty.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function createSearchExternalSource(query) {
+    const normalizedQuery = query.replace(/\s+/gu, ' ').trim();
+    if (normalizedQuery === '') {
+        return null;
+    }
+    return {
+        kind: 'search',
+        name: normalizedQuery.length <= MAX_SEARCH_QUERY_LENGTH
+            ? normalizedQuery
+            : `${normalizedQuery.slice(0, MAX_SEARCH_QUERY_LENGTH).trimEnd()}…`,
+    };
+}
+/**
+ * Collects the websites addressed by one shell command running a network client.
+ *
+ * Commands which do not invoke a network client are ignored, so a web address that merely appears
+ * in the text the agent writes into a file is never reported as touched.
+ *
+ * @param command - One executed shell command.
+ * @returns Touched website sources of the command.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function resolveNetworkCommandExternalSources(command) {
+    if (!NETWORK_CLIENT_COMMAND_REGEX.test(command)) {
+        return [];
+    }
+    const commandUrlRegex = new RegExp(COMMAND_URL_REGEX.source, COMMAND_URL_REGEX.flags);
+    const externalSources = [];
+    let commandUrlMatch = commandUrlRegex.exec(command);
+    while (commandUrlMatch !== null) {
+        const externalSource = createWebsiteExternalSource(commandUrlMatch[0]);
+        if (externalSource) {
+            externalSources.push(externalSource);
+        }
+        commandUrlMatch = commandUrlRegex.exec(command);
+    }
+    return externalSources;
+}
+/**
+ * Converts one raw integration name into its user-facing form.
+ *
+ * For example `google-calendar` becomes `Google Calendar`.
+ *
+ * @param integrationName - Raw integration name.
+ * @returns Human-readable integration name, or an empty string when there is nothing to show.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function humanizeIntegrationName(integrationName) {
+    return integrationName
+        .trim()
+        .split(INTEGRATION_NAME_WORD_SEPARATOR_REGEX)
+        .filter((integrationNameWord) => integrationNameWord !== '')
+        .map((integrationNameWord) => capitalize(integrationNameWord))
+        .join(' ');
+}
+/**
+ * Builds the key identifying one external source across the whole run.
+ *
+ * @param externalSource - One touched external source.
+ * @returns Key under which repeated touches of the same source collapse into one.
+ * @private internal helper of `resolveAgentMessageTouchedExternalSources`
+ */
+function createExternalSourceKey(externalSource) {
+    return `${externalSource.kind}:${externalSource.name.toLowerCase()}`;
+}
+
 /**
  * Matches one project directory name following the agent `projects/` folder in a file path or command.
  *
@@ -38329,43 +39086,25 @@ function resolveCandidateProjectNames(toolInvocationText) {
 }
 
 /**
- * Resolves which agent projects one answered message viewed or edited.
+ * Resolves which agent projects and which external sources one answered message touched.
  *
  * The runtime log is deleted as soon as the harness run finishes, so this must be called while
- * the log still exists — the Agents Server later shows the reported projects as chips below the
- * answer. Reporting touched projects is best-effort telemetry: an unreadable log or projects
- * folder simply yields no projects instead of failing the already answered message.
+ * the log still exists — the Agents Server later shows everything reported here as chips below
+ * the answer. Reporting touches is best-effort telemetry: an unreadable log or projects folder
+ * simply yields nothing instead of failing the already answered message.
  *
  * @param options - Agent folder path and the live runtime log path of the answered message.
- * @returns Touched project directory names, ordered by first appearance in the run.
+ * @returns Touched projects and external sources, ordered by first appearance in the run.
  */
-async function resolveTouchedAgentProjects(options) {
+async function resolveAnsweredMessageTouches(options) {
     const [logText, knownProjectNames] = await Promise.all([
         readOptionalTextFile(options.runtimeLogPath),
         listAgentProjectDirectoryNames(options.projectPath),
     ]);
-    return resolveAgentMessageTouchedProjectNames({ logText, knownProjectNames });
-}
-/**
- * Lists the direct project directories of one agent folder.
- *
- * @param projectPath - Absolute path of the local agent folder.
- * @returns Project directory names, or an empty list when the agent has no projects folder.
- *
- * @private helper of `resolveTouchedAgentProjects`
- */
-async function listAgentProjectDirectoryNames(projectPath) {
-    try {
-        const projectsRootEntries = await readdir(join(projectPath, AGENT_PROJECTS_DIRECTORY_PATH), {
-            withFileTypes: true,
-        });
-        return projectsRootEntries
-            .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
-            .map((projectDirectoryEntry) => projectDirectoryEntry.name);
-    }
-    catch (_a) {
-        return [];
-    }
+    return {
+        touchedProjectNames: resolveAgentMessageTouchedProjectNames({ logText, knownProjectNames }),
+        touchedExternalSources: resolveAgentMessageTouchedExternalSources({ logText }),
+    };
 }
 /**
  * Reads one text file and treats a missing runtime log as "nothing was recorded".
@@ -38373,7 +39112,7 @@ async function listAgentProjectDirectoryNames(projectPath) {
  * @param filePath - Absolute path of the file to read.
  * @returns File content, or `null` when it cannot be read.
  *
- * @private helper of `resolveTouchedAgentProjects`
+ * @private helper of `resolveAnsweredMessageTouches`
  */
 async function readOptionalTextFile(filePath) {
     try {
@@ -38690,7 +39429,7 @@ async function runQueuedAgentMessage(options) {
     uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
     const executionStartedAt = new Date().toISOString();
     let promptRunResult;
-    let touchedProjectNames = [];
+    let answeredMessageTouches = { touchedProjectNames: [], touchedExternalSources: [] };
     try {
         try {
             promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => {
@@ -38706,9 +39445,12 @@ async function runQueuedAgentMessage(options) {
                         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAttempt(attemptCount);
                     },
                 });
-                // Note: The runtime log is deleted right after this handler, so the projects this
+                // Note: The runtime log is deleted right after this handler, so everything this
                 //       answer worked with must be resolved while the log still exists.
-                touchedProjectNames = await resolveTouchedAgentProjects({ projectPath, runtimeLogPath: logPath });
+                answeredMessageTouches = await resolveAnsweredMessageTouches({
+                    projectPath,
+                    runtimeLogPath: logPath,
+                });
                 return runResult;
             }, { preserveArtifactsOnSuccess: false });
         }
@@ -38726,6 +39468,12 @@ async function runQueuedAgentMessage(options) {
     }
     const executionFinishedAt = new Date().toISOString();
     await normalizeLineEndingsForAgentRound(projectPath, runOptions, roundChangedFilesSnapshot);
+    // Note: Every agent project keeps its own git history, so what this message did to a project is
+    //       committed there before the answer becomes visible and travels with the run report.
+    const projectChanges = await commitAnsweredMessageProjectChanges({
+        agentFolderPath: projectPath,
+        commitMessage: buildAgentMessageCommitMessage(queuedMessage),
+    });
     const finishedTeamWorkspace = await finalizeAgentTeamConversationWorkspace({
         projectPath,
         queuedMessage,
@@ -38747,7 +39495,13 @@ async function runQueuedAgentMessage(options) {
                 startedAt: executionStartedAt,
                 finishedAt: executionFinishedAt,
             },
-            ...(touchedProjectNames.length === 0 ? {} : { touchedProjectNames }),
+            ...(answeredMessageTouches.touchedProjectNames.length === 0
+                ? {}
+                : { touchedProjectNames: answeredMessageTouches.touchedProjectNames }),
+            ...(answeredMessageTouches.touchedExternalSources.length === 0
+                ? {}
+                : { touchedExternalSources: answeredMessageTouches.touchedExternalSources }),
+            ...(projectChanges.length === 0 ? {} : { projectChanges }),
         },
     });
     await commitAnsweredMessageIfEnabled({
@@ -41763,7 +42517,9 @@ function comparePrereleaseIdentifier(firstIdentifier, secondIdentifier) {
 async function $checkHarnessInstallation(definition, isHarnessUpdateCheckEnabled = true) {
     const [installedVersion, latestVersion] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        isHarnessUpdateCheckEnabled ? $resolveLatestNpmPackageVersion(definition.npmPackageName) : Promise.resolve(null),
+        isHarnessUpdateCheckEnabled
+            ? $resolveLatestNpmPackageVersion(definition.npmPackageName)
+            : Promise.resolve(null),
     ]);
     return {
         definition,
@@ -42447,6 +43203,52 @@ function listDefaultCoderProjectPromptTemplateDisplayPaths() {
 // Note: [🟡] Code for CLI command [init](src/cli/cli-commands/coder/init.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Default wait duration applied before retrying a prompt round after an error (10 minutes).
+ *
+ * @private internal constant of `ptbk coder` wait handling
+ */
+const DEFAULT_WAIT_AFTER_ERROR_MS$1 = 10 * 60 * 1000;
+/**
+ * Parses an optional Commander duration string and returns the resolved milliseconds.
+ *
+ * Returns `defaultMs` when the flag was not provided or was provided without a non-empty value.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+function parseOptionalWaitDuration(value, defaultMs) {
+    if (typeof value !== 'string' || value === '') {
+        return 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
+ */
+function parseOptionalPeriodDuration(optionName, value) {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+    const periodMs = parseDuration(value);
+    if (periodMs <= 0) {
+        throw new NotAllowed(spaceTrim$1(`
+                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
+
 /**
  * Initializes `coder ping` command for Promptbook CLI utilities
  *
@@ -42465,6 +43267,7 @@ function $initializeCoderPingCommand(program) {
             - 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 globally 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
@@ -42472,21 +43275,34 @@ function $initializeCoderPingCommand(program) {
     addPromptRunnerSelectionOptions(command);
     addHarnessUpdateOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option('--period <duration>', spaceTrim$1(`
+            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;
         const runnerOptions = normalizePromptRunnerSelectionCliOptions(cliOptions, { isAgentRequired: true });
         const { isHarnessUpdateCheckEnabled } = normalizeHarnessUpdateCliOptions(cliOptions);
+        // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+        const periodMs = parseOptionalPeriodDuration('--period', periodValue);
         await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
-        // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
-        const { pingCoderHarness } = await Promise.resolve().then(function () { return pingCoderHarness$1; });
-        const { printCoderPingResult } = await Promise.resolve().then(function () { return printCoderPingResult$1; });
-        const result = await pingCoderHarness({
+        const pingOptions = {
             agentName: runnerOptions.agentName,
             model: runnerOptions.model,
             thinkingLevel: runnerOptions.thinkingLevel,
             allowCredits: runnerOptions.allowCredits,
             shouldPrintLiveOutput: runnerOptions.noUi,
-        });
-        printCoderPingResult(result);
+        };
+        // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+        if (periodMs !== undefined) {
+            const { pingCoderHarnessPeriodically } = await Promise.resolve().then(function () { return pingCoderHarnessPeriodically$1; });
+            // Note: This never returns - it keeps pinging until the user stops the process
+            await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+            return;
+        }
+        const { pingCoderHarness } = await Promise.resolve().then(function () { return pingCoderHarness$1; });
+        const { printCoderPingResult } = await Promise.resolve().then(function () { return printCoderPingResult$1; });
+        printCoderPingResult(await pingCoderHarness(pingOptions));
     }));
 }
 // Note: [🟡] Code for CLI command [ping](src/cli/cli-commands/coder/ping.ts) should never be published outside of `@promptbook/cli`
@@ -42923,27 +43739,6 @@ function isTestBeforeMode(value) {
     return TEST_BEFORE_MODE_VALUES.includes(value);
 }
 
-/**
- * Default wait duration applied before retrying a prompt round after an error (10 minutes).
- *
- * @private internal constant of `ptbk coder` wait handling
- */
-const DEFAULT_WAIT_AFTER_ERROR_MS$1 = 10 * 60 * 1000;
-/**
- * Parses an optional Commander duration string and returns the resolved milliseconds.
- *
- * Returns `defaultMs` when the flag was not provided or was provided without a non-empty value.
- *
- * @private internal utility of `ptbk coder` wait handling
- */
-function parseOptionalWaitDuration(value, defaultMs) {
-    if (typeof value !== 'string' || value === '') {
-        return defaultMs;
-    }
-    return parseDuration(value);
-}
-// Note: [💞] Ignore a discrepancy between file name and entity name
-
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
  *
@@ -66985,7 +67780,7 @@ function validateBook(source) {
 padBook(validateBook(spaceTrim$1(`
             AI Avatar
 
-            PERSONA A friendly AI assistant that helps you with your tasks
+            GOAL Help users with their tasks as a friendly AI assistant.
         `)));
 // <- Note: Not using book`...` notation to avoid strange error in jest unit tests `TypeError: (0 , book_notation_1.book) is not a function`
 // <- TODO: [🐱‍🚀] `GENESIS_BOOK` / `ADAM_BOOK` in `/agents/adam.book`
@@ -72682,6 +73477,23 @@ var findUnwrittenPrompts$1 = /*#__PURE__*/Object.freeze({
     findUnwrittenPrompts: findUnwrittenPrompts
 });
 
+/**
+ * Formats one unknown error-like value into its readable message without the stack trace.
+ *
+ * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
+ * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
+ */
+function formatUnknownErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    const serializedError = JSON.stringify(error, null, 2);
+    return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
+}
+
 /**
  * Builds a normalized temporary shell script path for prompt runners.
  */
@@ -72919,6 +73731,60 @@ var printCoderPingResult$1 = /*#__PURE__*/Object.freeze({
     printCoderPingResult: printCoderPingResult
 });
 
+/**
+ * How often the countdown to the next periodic ping is reported to the console (30 minutes).
+ *
+ * A period like `5h` is meant to be left running unattended, so the countdown is deliberately
+ * coarse — it is a sign of life, not a progress bar.
+ */
+const CODER_PING_COUNTDOWN_UPDATE_INTERVAL_MS = 30 * 60 * 1000;
+/**
+ * Pings the selected harness and model once per period until the process is stopped.
+ *
+ * This keeps the quota window of the harness refreshing without any real work, so the window is
+ * always open by the time you need it. The loop never ends on its own — it is stopped with `CTRL+C`
+ * or by killing the process — therefore a failing ping is reported and the next period is started
+ * instead of tearing the whole loop down.
+ */
+async function pingCoderHarnessPeriodically(options) {
+    const { periodMs, ...pingOptions } = options;
+    console.info(colors.gray(`🏓 Pinging every ${formatDurationMs(periodMs)} until stopped with CTRL+C`));
+    // Note: The loop is intentionally endless - only `CTRL+C` or killing the process ends it
+    for (;;) {
+        const nextPingTimeMs = Date.now() + periodMs;
+        await reportOneCoderPing(pingOptions);
+        await waitUntilNextCoderPing(nextPingTimeMs);
+    }
+}
+/**
+ * Sends and reports one ping of the endless loop, keeping the loop alive when the harness fails.
+ */
+async function reportOneCoderPing(options) {
+    try {
+        printCoderPingResult(await pingCoderHarness(options));
+    }
+    catch (error) {
+        console.error(colors.red(`🏓 Ping failed: ${formatUnknownErrorMessage(error)}`));
+    }
+}
+/**
+ * Waits until the wall-clock time of the next ping, reporting how much of the period is left.
+ */
+async function waitUntilNextCoderPing(nextPingTimeMs) {
+    await waitUntilWorldTimeDeadline({
+        deadlineTimeMs: nextPingTimeMs,
+        pollIntervalMs: CODER_PING_COUNTDOWN_UPDATE_INTERVAL_MS,
+        onTick(remainingDurationMs) {
+            console.info(colors.gray(`   Next ping in ${formatDurationMs(remainingDurationMs)}`));
+        },
+    });
+}
+
+var pingCoderHarnessPeriodically$1 = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    pingCoderHarnessPeriodically: pingCoderHarnessPeriodically
+});
+
 /**
  * Default wait duration applied before retrying a failed prompt round.
  */
@@ -75752,23 +76618,6 @@ function buildCoderIsolationWorktreeDisplayPath(taskName) {
     return getPromptbookTemporaryPath(CODER_ISOLATION_WORKTREES_DIRECTORY_NAME, taskName);
 }
 
-/**
- * Formats one unknown error-like value into its readable message without the stack trace.
- *
- * Use this instead of `formatUnknownErrorDetails` whenever the text is shown to the user, for example
- * inside a branded error, where the stack of the wrapped error would only bury the actual cause.
- */
-function formatUnknownErrorMessage(error) {
-    if (error instanceof Error) {
-        return error.message;
-    }
-    if (typeof error === 'string') {
-        return error;
-    }
-    const serializedError = JSON.stringify(error, null, 2);
-    return serializedError !== null && serializedError !== void 0 ? serializedError : String(error);
-}
-
 /**
  * Git configuration key which lets Git read, write and delete files whose absolute path is longer than
  * the Windows `MAX_PATH` limit of 260 characters.