@promptbook/cli 0.114.0-13 → 0.114.0-18

package/umd/index.umd.js

@@ -58,7 +58,7 @@
      * @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
@@ -2217,7 +2217,7 @@
      */
     async function ensureDirectory(projectPath, relativeDirectoryPath) {
         const directoryPath = path.join(projectPath, relativeDirectoryPath);
-        const isDirectoryExisting = await isExistingDirectory$1(directoryPath);
+        const isDirectoryExisting = await isExistingDirectory$2(directoryPath);
         if (!isDirectoryExisting) {
             await promises.mkdir(directoryPath, { recursive: true });
             return 'created';
@@ -2227,7 +2227,7 @@
     /**
      * Checks whether a path exists and is a directory.
      */
-    async function isExistingDirectory$1(path) {
+    async function isExistingDirectory$2(path) {
         try {
             return (await promises.stat(path)).isDirectory();
         }
@@ -5726,6 +5726,12 @@
 
             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
@@ -5734,6 +5740,13 @@
             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) {
@@ -30582,6 +30595,385 @@
         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 promises.readdir(path.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) => {
+            child_process.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.spaceTrim(`
+    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(path.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 = path.join(projectPath, '.gitignore');
+        try {
+            await promises.stat(gitignorePath);
+            return;
+        }
+        catch (_a) {
+            // Note: A project without ignore rules would commit its installed dependencies
+        }
+        await promises.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 promises.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: path.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__default["default"].yellow(`Could not commit changes of project "${options.projectName}"`), error);
+            return null;
+        }
+    }
+
     /**
      * Checks whether one repository-relative path is tracked by Git.
      */
@@ -30627,7 +31019,7 @@
 
             - 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))}
@@ -30759,13 +31151,79 @@
     }
     // 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.
@@ -30777,19 +31235,25 @@
         return _spaceTrim.spaceTrim((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.
         `);
     }
     /**
@@ -30822,10 +31286,7 @@
     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}`;
     }
 
     /**
@@ -37885,7 +38346,7 @@
      *
      * @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.
      *
@@ -37977,19 +38438,35 @@
      * 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.
      *
@@ -38215,6 +38692,286 @@
         }
     }
 
+    /**
+     * 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.
      *
@@ -38339,43 +39096,25 @@
     }
 
     /**
-     * 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 promises.readdir(path.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".
@@ -38383,7 +39122,7 @@
      * @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 {
@@ -38700,7 +39439,7 @@
         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) => {
@@ -38716,9 +39455,12 @@
                             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 });
             }
@@ -38736,6 +39478,12 @@
         }
         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,
@@ -38757,7 +39505,13 @@
                     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({
@@ -41773,7 +42527,9 @@
     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,
@@ -42457,6 +43213,52 @@
     // 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.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
+
     /**
      * Initializes `coder ping` command for Promptbook CLI utilities
      *
@@ -42475,6 +43277,7 @@
             - 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
@@ -42482,21 +43285,34 @@
         addPromptRunnerSelectionOptions(command);
         addHarnessUpdateOption(command);
         addPromptRunnerRuntimeOptions(command);
+        command.option('--period <duration>', _spaceTrim.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;
             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`
@@ -42933,27 +43749,6 @@
         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
      *
@@ -66995,7 +67790,7 @@
     padBook(validateBook(_spaceTrim.spaceTrim(`
             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`
@@ -72692,6 +73487,23 @@
         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.
      */
@@ -72929,6 +73741,60 @@
         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__default["default"].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__default["default"].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__default["default"].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.
      */
@@ -75762,23 +76628,6 @@
         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.