@promptbook/cli 0.114.0-3 → 0.114.0-30

package/umd/scripts/run-agent-messages/git/commitAgentProjectChanges.d.ts

@@ -0,0 +1,15 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * 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.
+ */
+export declare function commitAgentProjectChanges(options: {
+    readonly projectPath: string;
+    readonly projectName: string;
+    readonly commitMessage: string;
+}): Promise<AgentMessageProjectChange | null>;

package/umd/scripts/run-agent-messages/git/commitAnsweredMessageProjectChanges.d.ts

@@ -0,0 +1,24 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * 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.
+ */
+export declare function commitAnsweredMessageProjectChanges(options: {
+    /**
+     * Absolute path of the local agent folder owning the projects.
+     */
+    readonly agentFolderPath: string;
+    /**
+     * Commit message shared by every project commit of this message.
+     */
+    readonly commitMessage: string;
+}): Promise<ReadonlyArray<AgentMessageProjectChange>>;

package/umd/scripts/run-agent-messages/git/ensureAgentProjectGitRepository.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How one agent project directory relates to git.
+ *
+ * -   `own-repository` is a project whose own history the runner can commit into.
+ * -   `tracked-elsewhere` is a project belonging to a repository around the agent folder, whose
+ *     history is already kept by whoever owns that repository.
+ * -   `unavailable` is a project which cannot be committed, for example because git is missing.
+ */
+export type AgentProjectGitRepositoryState = 'own-repository' | 'tracked-elsewhere' | 'unavailable';
+/**
+ * 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.
+ */
+export declare function ensureAgentProjectGitRepository(projectPath: string): Promise<AgentProjectGitRepositoryState>;

package/umd/scripts/run-agent-messages/git/readAgentProjectCommitChange.d.ts

@@ -0,0 +1,11 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * 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.
+ */
+export declare function readAgentProjectCommitChange(options: {
+    readonly projectPath: string;
+    readonly projectName: string;
+}): Promise<AgentMessageProjectChange | null>;

package/umd/scripts/run-agent-messages/git/runAgentProjectGitCommand.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of one git command executed inside one agent project.
+ */
+export type AgentProjectGitCommandResult = {
+    /**
+     * Whether git reported success.
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * Standard output of the command, with the trailing newline removed.
+     */
+    readonly output: string;
+};
+/**
+ * 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.
+ */
+export declare function runAgentProjectGitCommand(options: {
+    readonly projectPath: string;
+    readonly args: ReadonlyArray<string>;
+}): Promise<AgentProjectGitCommandResult>;

package/umd/scripts/run-agent-messages/messages/buildAgentGoalChatPromptSection.d.ts

@@ -0,0 +1,26 @@
+import type { AgentPlannedMessageSnapshot } from '../../../src/book-3.0/AgentPlannedMessagesSidecar';
+/**
+ * Planned-message sidecar information made visible to one coding-harness prompt.
+ */
+export type AgentPlannedMessagesPromptSidecar = {
+    /**
+     * Portable path of the sidecar inside the agent folder.
+     */
+    readonly relativeSidecarPath: string;
+    /**
+     * Planned messages that are already waiting to wake the agent.
+     */
+    readonly currentPlannedMessages: ReadonlyArray<AgentPlannedMessageSnapshot>;
+};
+/**
+ * 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 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.
+ */
+export declare function buildAgentGoalChatPromptSection(sidecar: AgentPlannedMessagesPromptSidecar | undefined): string;

package/umd/scripts/run-agent-messages/messages/buildAgentMessagePrompt.d.ts

@@ -1,8 +1,19 @@
 import { type AgentProjectsPromptSectionOptions } from './buildAgentProjectsPromptSection';
+import { type AgentPlannedMessagesPromptSidecar } from './buildAgentGoalChatPromptSection';
+import { type AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
 /**
  * Options adjusting the generated agent message prompt.
  */
-export type BuildAgentMessagePromptOptions = AgentProjectsPromptSectionOptions;
+export type BuildAgentMessagePromptOptions = AgentProjectsPromptSectionOptions & {
+    /**
+     * Optional local TEAM roster prepared by the Agents Server for this user turn.
+     */
+    teamWorkspace?: AgentTeamPromptWorkspace;
+    /**
+     * Planned-message sidecar prepared by the Agents Server for the agent's singleton goal chat.
+     */
+    plannedMessagesSidecar?: AgentPlannedMessagesPromptSidecar;
+};
 /**
  * Builds the prompt sent to the selected coding runner for one queued user-thread book.
  */

package/umd/scripts/run-agent-messages/messages/buildAgentProjectsPromptSection.d.ts

@@ -1,20 +1,8 @@
+import type { AgentServerRuntimePromptApi } from './AgentServerRuntimePromptApi';
 /**
  * Internal runtime API details available to Agents Server-managed local agents.
  */
-export type AgentProjectRuntimePromptApi = {
-    /**
-     * Permanent id of the agent currently answering the message.
-     */
-    readonly agentPermanentId: string;
-    /**
-     * Environment variable containing the Agents Server origin.
-     */
-    readonly serverUrlEnvironmentVariableName: string;
-    /**
-     * Environment variable containing the internal worker token.
-     */
-    readonly tokenEnvironmentVariableName: string;
-};
+export type AgentProjectRuntimePromptApi = AgentServerRuntimePromptApi;
 /**
  * Options of the projects prompt section shared by every coding harness.
  */

package/umd/scripts/run-agent-messages/messages/buildAgentTeamPromptSection.d.ts

@@ -0,0 +1,12 @@
+import { type AgentTeamConversationWorkspaceManifest } from '../../../src/book-3.0/AgentTeamConversationWorkspace';
+/**
+ * TEAM workspace information made visible to one coding-harness prompt.
+ */
+export type AgentTeamPromptWorkspace = {
+    readonly relativeWorkspacePath: string;
+    readonly manifest: AgentTeamConversationWorkspaceManifest;
+};
+/**
+ * Builds the optional single-run TEAM consultation instructions for a coding harness.
+ */
+export declare function buildAgentTeamPromptSection(workspace: AgentTeamPromptWorkspace | undefined): string;

package/umd/scripts/run-agent-messages/messages/finalizeAgentTeamConversationWorkspace.d.ts

@@ -0,0 +1,16 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+import type { AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
+/**
+ * TEAM transcript files retained next to the finished user message.
+ */
+export type FinishedAgentTeamConversationWorkspace = {
+    readonly relativePaths: ReadonlyArray<string>;
+};
+/**
+ * Moves harness-created TEAM conversation transcripts into the finished-message history.
+ */
+export declare function finalizeAgentTeamConversationWorkspace(options: {
+    readonly projectPath: string;
+    readonly queuedMessage: AgentMessageFile;
+    readonly workspace: AgentTeamPromptWorkspace | null;
+}): Promise<FinishedAgentTeamConversationWorkspace | null>;

package/umd/scripts/run-agent-messages/messages/listAgentProjectDirectoryNames.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function listAgentProjectDirectoryNames(agentFolderPath: string): Promise<ReadonlyArray<string>>;

package/umd/scripts/run-agent-messages/messages/loadAgentPlannedMessagesSidecar.d.ts

@@ -0,0 +1,10 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+import type { AgentPlannedMessagesPromptSidecar } from './buildAgentGoalChatPromptSection';
+/**
+ * Loads the planned-message sidecar the Agents Server prepared for one queued message.
+ *
+ * @param projectPath - Absolute path of the current agent runner folder.
+ * @param queuedMessage - Queued message currently being answered.
+ * @returns Sidecar details for the prompt, or `null` outside Agents Server-managed runs.
+ */
+export declare function loadAgentPlannedMessagesSidecar(projectPath: string, queuedMessage: AgentMessageFile): Promise<AgentPlannedMessagesPromptSidecar | null>;

package/umd/scripts/run-agent-messages/messages/loadAgentTeamConversationWorkspace.d.ts

@@ -0,0 +1,6 @@
+import type { AgentMessageFile } from './AgentMessageFile';
+import type { AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
+/**
+ * Loads the optional TEAM roster snapshot for one queued message.
+ */
+export declare function loadAgentTeamConversationWorkspace(projectPath: string, queuedMessage: AgentMessageFile): Promise<AgentTeamPromptWorkspace | null>;

package/umd/scripts/run-agent-messages/messages/resolveAnsweredMessageTouches.d.ts

@@ -0,0 +1,29 @@
+import type { AgentMessageTouchedExternalSource } from '../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Everything one answered message worked with, both inside and outside the agent.
+ */
+export type AnsweredMessageTouches = {
+    /**
+     * Directory names of the agent projects the answer viewed or edited.
+     */
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    /**
+     * Sources outside the agent the answer reached.
+     */
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+};
+/**
+ * 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 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 projects and external sources, ordered by first appearance in the run.
+ */
+export declare function resolveAnsweredMessageTouches(options: {
+    readonly projectPath: string;
+    readonly runtimeLogPath: string;
+}): Promise<AnsweredMessageTouches>;

package/umd/scripts/run-codex-prompts/common/CoderRunControlFeedback.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Terminal control key of `ptbk coder run` which the user can press during a run.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlKey = 'P' | 'S' | 'X';
+/**
+ * Meaning of one control answer, which decides how it is colored in the terminal.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedbackTone = 'success' | 'info' | 'warning';
+/**
+ * Answer of the runner to one pressed control key.
+ *
+ * Every single key press produces one of these, including presses which change nothing, so the user
+ * always sees that the key was received.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedback = {
+    /**
+     * Control key the answer belongs to.
+     */
+    readonly controlKey: CoderRunControlKey;
+    /**
+     * Human-readable description of what the key press did.
+     */
+    readonly message: string;
+    /**
+     * Meaning of the answer, used to color it.
+     */
+    readonly tone: CoderRunControlFeedbackTone;
+};
+/**
+ * One control answer together with how many times the very same answer was repeated in a row.
+ *
+ * Pressing one control twice can produce the identical answer, so the repeat count is what makes the
+ * second press change the rendered frame as well.
+ *
+ * @private internal type of `ptbk coder` terminal controls
+ */
+export type CoderRunControlFeedbackNotice = CoderRunControlFeedback & {
+    /**
+     * How many times this exact answer was given in a row, starting at `1`.
+     */
+    readonly repeatCount: number;
+};
+/**
+ * How long one control answer stays visible in the rich terminal UI.
+ *
+ * @private internal constant of `ptbk coder` terminal controls
+ */
+export declare const CODER_RUN_CONTROL_FEEDBACK_DURATION_MS = 5000;

package/umd/scripts/run-codex-prompts/common/applyCoderRunControlKey.d.ts

@@ -0,0 +1,14 @@
+import type { CoderRunControlFeedback } from './CoderRunControlFeedback';
+/**
+ * Applies the terminal control bound to one pressed key and describes what that key press did.
+ *
+ * This is the single place where the `P`, `S` and `X` keys are turned into runner actions, so the
+ * plain console listener and the rich terminal UI always perform the same action and always answer
+ * the user, even when the pressed control changed nothing.
+ *
+ * @param keyName Name of the pressed key as reported by the `keypress` event.
+ * @returns The answer shown to the user, or `undefined` when the key is not a control key.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function applyCoderRunControlKey(keyName: string | undefined): CoderRunControlFeedback | undefined;

package/umd/scripts/run-codex-prompts/common/buildCoderRunControlKeyBadge.d.ts

@@ -0,0 +1,7 @@
+import type { CoderRunControlKey } from './CoderRunControlFeedback';
+/**
+ * Builds the colored badge of one control key, for example ` S `.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function buildCoderRunControlKeyBadge(controlKey: CoderRunControlKey): string;

package/umd/scripts/run-codex-prompts/common/createCoderRunStepTracker.d.ts

@@ -0,0 +1,48 @@
+import type { CodexLoginMethod } from '../../../src/book-3.0/codexLoginMethod';
+import type { CoderRunStep, CoderRunStepKind } from './CoderRunStep';
+/**
+ * Progress of one prompt round, reported right before a new step starts.
+ */
+export type CoderRunStepProgress = {
+    /**
+     * Kind of the step which is about to start.
+     */
+    readonly startedStepKind: CoderRunStepKind;
+    /**
+     * Steps of the same prompt round which have already finished, in the order they ran.
+     */
+    readonly finishedSteps: ReadonlyArray<CoderRunStep>;
+    /**
+     * Authentication method the harness reported, as soon as one of the finished steps revealed it.
+     */
+    readonly loginMethod?: CodexLoginMethod;
+};
+/**
+ * Notified right before one coder run step starts.
+ */
+export type OnCoderRunStepStarted = (progress: CoderRunStepProgress) => Promise<void>;
+/**
+ * Collects the measured steps of one prompt round and announces every step which starts.
+ */
+export type CoderRunStepTracker = {
+    /**
+     * Steps which have finished so far, in the order they ran.
+     */
+    readonly steps: ReadonlyArray<CoderRunStep>;
+    /**
+     * Announces that one step is about to start.
+     */
+    readonly startStep: (kind: CoderRunStepKind) => Promise<void>;
+    /**
+     * Records one finished step together with the authentication method its runner reported.
+     */
+    readonly finishStep: (step: CoderRunStep, loginMethod?: CodexLoginMethod) => void;
+};
+/**
+ * Creates the step tracker of one prompt round.
+ *
+ * The tracker is the single place which knows which steps have finished and which one is running,
+ * so both the finished `[x]` status line and the intermediate `[^]` in-progress status lines are
+ * built from the very same data.
+ */
+export declare function createCoderRunStepTracker(onStepStarted?: OnCoderRunStepStarted): CoderRunStepTracker;

package/umd/scripts/run-codex-prompts/common/formatCoderRunControlFeedback.d.ts

@@ -0,0 +1,13 @@
+import type { CoderRunControlFeedback } from './CoderRunControlFeedback';
+/**
+ * Formats one control answer as a single colored terminal line.
+ *
+ * The same line is printed by the plain console listener and rendered inside the `Controls` box of the
+ * rich terminal UI, so both modes answer a pressed control key identically.
+ *
+ * @param feedback Answer of the runner to the pressed control key.
+ * @param repeatCount How many times this exact answer was given in a row, rendered from the second time on.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function formatCoderRunControlFeedback(feedback: CoderRunControlFeedback, repeatCount?: number): string;

package/umd/scripts/run-codex-prompts/common/listenForCoderRunControls.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Listens for the terminal control keys while the plain console output is used.
+ *
+ * Every recognized key press is answered with one printed line, because the plain mode has no frame
+ * which could show the new state on its own. The rich terminal UI installs its own listener in
+ * [`renderCoderRunUi`](../ui/renderCoderRunUi.ts) and shares the very same key handling through
+ * [`applyCoderRunControlKey`](./applyCoderRunControlKey.ts).
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function listenForCoderRunControls(): void;
+/**
+ * Backwards-compatible alias for the shared terminal controls listener.
+ *
+ * @private internal utility of `ptbk coder` terminal controls
+ */
+export declare function listenForPause(): void;

package/umd/scripts/run-codex-prompts/common/normalizeLineEndingsInChangedFiles.d.ts

@@ -1,9 +1,8 @@
+import type { WorkingTreeChangesSnapshot } from '../git/workingTreeChanges';
 /**
  * Snapshot of file hashes for files that were already dirty before a coding round started.
  */
-export type ChangedFilesSnapshot = {
-    readonly changedFileHashes: ReadonlyMap<string, string>;
-};
+export type ChangedFilesSnapshot = WorkingTreeChangesSnapshot;
 /**
  * Options for normalizing line endings in files changed during one coding round.
  */

package/umd/scripts/run-codex-prompts/common/runGoScript/$spawnLoggedBashScript.d.ts

@@ -0,0 +1,25 @@
+/// <reference types="node" />
+import { type ChildProcessWithoutNullStreams } from 'child_process';
+/**
+ * Input used to start one temporary logged Bash script.
+ *
+ * @private internal type of `$spawnLoggedBashScript`
+ */
+type SpawnLoggedBashScriptOptions = {
+    readonly scriptPath: string;
+    readonly logPath?: string;
+    /**
+     * Process which owns the temporary harness shell. Defaults to the current coder process.
+     */
+    readonly parentProcessId?: number;
+};
+/**
+ * Starts one temporary Bash script in a process tree owned by the current Node process.
+ *
+ * The wrapper watches the supplied owning process ID. When that process exits abruptly, the wrapper terminates every
+ * nested shell and harness process instead of leaving it orphaned.
+ *
+ * @private internal utility of the coding prompt runner
+ */
+export declare function $spawnLoggedBashScript(options: SpawnLoggedBashScriptOptions): ChildProcessWithoutNullStreams;
+export {};

package/umd/scripts/run-codex-prompts/common/runGoScript/$terminateLoggedBashProcessTree.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import { type ChildProcess } from 'child_process';
+/**
+ * Stops one active temporary Bash shell together with the harness process tree it owns.
+ *
+ * Unix sends `SIGTERM` to the wrapper so its shell trap terminates the separately grouped harness job. Windows does
+ * not reliably deliver that signal to Bash, so the native `taskkill` command terminates the direct shell tree instead.
+ *
+ * @private internal utility of the coding prompt runner
+ */
+export declare function $terminateLoggedBashProcessTree(commandProcess: ChildProcess): void;

package/umd/scripts/run-codex-prompts/common/runGoScript/scriptExecutionLog.d.ts

@@ -9,6 +9,10 @@ export declare const PTBK_CODER_LOG_FILE_ENV_NAME = "PTBK_CODER_LOG_FILE";
  * without the generated script and the prompt it embeds.
  */
 export declare const SCRIPT_EXECUTION_LOG_RAW_OUTPUT_MARKER = "--- raw output ---";
+/**
+ * Environment variable that identifies the Node process responsible for a temporary harness shell.
+ */
+export declare const PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME = "PTBK_CODER_PARENT_PROCESS_ID";
 /**
  * Shapes one bash invocation that optionally mirrors live script output into a temporary log file.
  */

package/umd/scripts/run-codex-prompts/common/waitForPause.d.ts

@@ -54,14 +54,6 @@ export declare function waitForSkippableMilliseconds(waitToken: CoderRunSkippabl
  * Restores all shared terminal controls to their default state.
  */
 export declare function resetCoderRunControls(): void;
-/**
- * Listens for the terminal control keys.
- */
-export declare function listenForCoderRunControls(): void;
-/**
- * Backwards-compatible alias for the shared terminal controls listener.
- */
-export declare function listenForPause(): void;
 /**
  * If the execution is paused, it will wait until it is resumed.
  *

package/umd/scripts/run-codex-prompts/common/waitForSkippableWorldTimeDeadline.d.ts

@@ -0,0 +1,15 @@
+import { type WorldTimeDeadlineTick } from './waitUntilWorldTimeDeadline';
+/**
+ * Waits until one wall-clock deadline has passed, or until the user skips the wait with the `S` control.
+ *
+ * This is the single way `ptbk coder` waits for a deadline the user is allowed to cut short, so every
+ * wait which shows the `S  Skip current waiting` control really reacts to it: the pacing waits between
+ * prompts, the cool-down after an error, the harness session-limit waits and the server keep-alive poll.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function waitForSkippableWorldTimeDeadline(options: {
+    readonly deadlineTimeMs: number;
+    readonly pollIntervalMs: number;
+    readonly onTick?: WorldTimeDeadlineTick;
+}): Promise<void>;

package/umd/scripts/run-codex-prompts/git/coderCommitScope.d.ts

@@ -0,0 +1,31 @@
+import type { WorkingTreeChangesSnapshot } from './workingTreeChanges';
+/**
+ * Working tree state captured right before one `ptbk coder` operation starts changing the project.
+ *
+ * Note: This is the single mechanism which every `ptbk coder` command uses to commit only the files relevant
+ *       for the operation it has just performed, instead of everything which happens to be changed in the project.
+ */
+export type CoderCommitScope = {
+    /**
+     * Project the operation runs in.
+     */
+    readonly projectPath: string;
+    /**
+     * Files which were already changed before the operation started.
+     */
+    readonly snapshotBeforeOperation: WorkingTreeChangesSnapshot;
+};
+/**
+ * Captures the working tree state before one `ptbk coder` operation changes anything.
+ *
+ * The captured scope is passed to the commit of the very same operation, which then commits exactly the files
+ * this operation has created, changed, moved or deleted.
+ */
+export declare function captureCoderCommitScope(projectPath: string): Promise<CoderCommitScope>;
+/**
+ * Resolves the repository-relative paths which one `ptbk coder` operation has really changed.
+ *
+ * Files which were already changed before the operation started and which the operation did not touch are
+ * never part of the result, so they stay in the working tree instead of being swept into the commit.
+ */
+export declare function resolveCoderCommitScopePaths(scope: CoderCommitScope): Promise<ReadonlyArray<string>>;

package/umd/scripts/run-codex-prompts/git/coderGitSync.d.ts

@@ -1,3 +1,4 @@
+import type { CoderCommitScope } from './coderCommitScope';
 /**
  * Automatic git synchronization of the project changes made by one `ptbk coder` command.
  *
@@ -24,6 +25,17 @@ export type CoderGitSyncOptions = {
  * Note: This is the default for every command and helper which supports the git synchronization.
  */
 export declare const DISABLED_CODER_GIT_SYNC_OPTIONS: CoderGitSyncOptions;
+/**
+ * Pulls the latest repository changes and captures the working tree state before a `ptbk coder` command
+ * changes the project.
+ *
+ * The returned scope is handed over to `$commitCoderChanges` of the very same command, which then commits
+ * exactly the files this command has changed.
+ */
+export declare function $startCoderGitSync(options: {
+    readonly gitSync: CoderGitSyncOptions;
+    readonly projectPath?: string;
+}): Promise<CoderCommitScope>;
 /**
  * Pulls the latest repository changes before a `ptbk coder` command changes the project.
  */
@@ -34,10 +46,11 @@ export declare function $pullCoderChanges(options: {
 /**
  * Commits - and when requested also pushes - the changes one `ptbk coder` command has just made.
  *
- * Note: A repository without any change is left alone instead of creating an empty commit.
+ * Note: Only the files this very command has changed are committed, everything else is left in the working tree.
+ * Note: A command which changed nothing is left alone instead of creating an empty commit.
  */
 export declare function $commitCoderChanges(options: {
     readonly gitSync: CoderGitSyncOptions;
     readonly commitMessage: string;
-    readonly projectPath?: string;
+    readonly commitScope: CoderCommitScope;
 }): Promise<void>;

package/umd/scripts/run-codex-prompts/git/commitChanges.d.ts

@@ -1,7 +1,7 @@
 /**
  * Commits staged changes with the provided message using the dedicated coding-agent identity when configured,
  * otherwise falls back to the default Git configuration. Remote pushing is opt-in via `options.autoPush`,
- * `options.includePaths` can restrict staging, `options.onlyPaths` can restrict the commit pathspec,
+ * `options.relevantPaths` restricts both the staging and the commit to the files of the current operation,
  * `options.excludePaths` can keep temporary artifacts out of the created commit and
  * `options.isEmptyCommitAllowed` keeps a round without any file change from failing.
  *
@@ -10,8 +10,14 @@
  */
 export declare function commitChanges(message: string, options?: {
     autoPush?: boolean;
-    includePaths?: ReadonlyArray<string>;
-    onlyPaths?: ReadonlyArray<string>;
+    /**
+     * Repository-relative paths which are relevant for the current operation.
+     *
+     * Only these paths are staged and only they end up in the created commit, so unrelated changes of the
+     * project are left in the working tree. Everything is committed when the paths are not provided at all,
+     * while an empty list commits nothing but the file changes already staged before.
+     */
+    relevantPaths?: ReadonlyArray<string>;
     excludePaths?: ReadonlyArray<string>;
     projectPath?: string;
     isEmptyCommitAllowed?: boolean;