pipeline-worker 0.1.25 → 0.1.27

package/dist/forge/types.d.ts

@@ -3,7 +3,7 @@
  * implementation maps pull requests / workflow runs / jobs onto the same
  * shapes so the workflow and MCP server never branch on the forge.
  */
-import type { MergeRequest, Pipeline, PipelineJob } from '../types.js';
+import type { MergeMethod, MergeRequest, Pipeline, PipelineJob } from '../types.js';
 export interface CreateMrArgs {
     sourceBranch: string;
     targetBranch: string;
@@ -33,4 +33,31 @@ export interface ForgeClient {
      * resolution on every push, before the forge has even checked.
      */
     hasMergeConflicts(mrIid: number): Promise<boolean>;
+    /**
+     * Asks the forge to merge this MR/PR automatically once CI (and any
+     * required approvals) allow it — GitHub's `enablePullRequestAutoMerge`
+     * GraphQL mutation, GitLab's `merge_when_pipeline_succeeds`. Throws on
+     * rejection (e.g. the forge's auto-merge feature isn't enabled for this
+     * repo, or approvals are still pending); the caller treats this as
+     * best-effort and must not let a rejection fail the run.
+     */
+    enableAutoMerge(mrIid: number, mergeMethod: MergeMethod): Promise<void>;
+    /**
+     * True once the forge reports the MR/PR as actually merged — GitHub's
+     * `merged` flag on the pull request, GitLab's `state: "merged"`. Used
+     * after enableAutoMerge to detect that the auto-merge really landed, so
+     * the local target branch can be fast-forwarded to include it (see
+     * workflow/syncTargetBranch.ts). A still-open or closed-unmerged MR/PR
+     * reads as false.
+     */
+    isMrMerged(mrIid: number): Promise<boolean>;
+    /**
+     * The project's custom CI/CD configuration file path, if one is set
+     * (GitLab's "CI/CD configuration file" project setting) — used by
+     * watchPipeline.ts's hasCiConfig to recognize CI as configured even when
+     * it isn't at the conventional `.gitlab-ci.yml` path. GitHub has no
+     * equivalent concept (workflows are always under `.github/workflows`) and
+     * always resolves undefined, with no network call.
+     */
+    getCiConfigPath(): Promise<string | undefined>;
 }

package/dist/git/commit.d.ts

@@ -2,6 +2,15 @@
 export declare function stageAll(worktreePath: string): Promise<void>;
 export declare function commit(worktreePath: string, message: string): Promise<void>;
 export declare function push(worktreePath: string, remote: string, branch: string): Promise<void>;
+/**
+ * Force-pushes with `--force-with-lease`, never plain `--force`: the lease
+ * refuses the push if `remote`'s branch has moved since we last observed it
+ * (a stray commit from elsewhere, a human pushing a fixup), failing loudly
+ * instead of silently discarding that work. Used only by the opt-in
+ * squash-on-merge step (git/squash.ts), the one operation in this tool that
+ * rewrites already-pushed history.
+ */
+export declare function forcePushWithLease(worktreePath: string, remote: string, branch: string): Promise<void>;
 /** True when the worktree has staged, unstaged, or untracked changes. */
 export declare function hasChanges(worktreePath: string): Promise<boolean>;
 /** Files git still reports as unmerged — conflict markers from a `git apply --3way` or `git merge` not yet resolved and staged. */

package/dist/git/commit.js

@@ -13,6 +13,17 @@ export async function commit(worktreePath, message) {
 export async function push(worktreePath, remote, branch) {
     await execFileAsync('git', ['push', '--set-upstream', remote, branch], { cwd: worktreePath });
 }
+/**
+ * Force-pushes with `--force-with-lease`, never plain `--force`: the lease
+ * refuses the push if `remote`'s branch has moved since we last observed it
+ * (a stray commit from elsewhere, a human pushing a fixup), failing loudly
+ * instead of silently discarding that work. Used only by the opt-in
+ * squash-on-merge step (git/squash.ts), the one operation in this tool that
+ * rewrites already-pushed history.
+ */
+export async function forcePushWithLease(worktreePath, remote, branch) {
+    await execFileAsync('git', ['push', '--force-with-lease', remote, branch], { cwd: worktreePath });
+}
 /** True when the worktree has staged, unstaged, or untracked changes. */
 export async function hasChanges(worktreePath) {
     const { stdout } = await execFileAsync('git', ['status', '--porcelain'], { cwd: worktreePath });

package/dist/git/commit.js.map

@@ -1 +1 @@
-{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../src/git/commit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../src/git/commit.ts"],"names":[],"mappings":"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"}

package/dist/git/squash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Collapses every commit on `worktreePath`'s current branch since it
+ * diverged from `origin/targetBranch` into a single commit titled
+ * `commitMessage` — the mechanics behind the opt-in `squashOnMerge` config
+ * flag (see orchestrate.ts's finalizeRun). Preserves tree content exactly;
+ * `git reset --soft` only rewrites history, never the working tree.
+ */
+export declare function squashCommitsSinceMergeBase(worktreePath: string, targetBranch: string, commitMessage: string): Promise<void>;

package/dist/git/squash.js

@@ -0,0 +1,26 @@
+/**
+ * Collapses every commit on `worktreePath`'s current branch since it
+ * diverged from `origin/targetBranch` into a single commit titled
+ * `commitMessage` — the mechanics behind the opt-in `squashOnMerge` config
+ * flag (see orchestrate.ts's finalizeRun). Preserves tree content exactly;
+ * `git reset --soft` only rewrites history, never the working tree.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mergeBase, commit } from './commit.js';
+const execFileAsync = promisify(execFile);
+async function currentHeadSha(worktreePath) {
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: worktreePath });
+    return stdout.trim();
+}
+export async function squashCommitsSinceMergeBase(worktreePath, targetBranch, commitMessage) {
+    await execFileAsync('git', ['fetch', 'origin', targetBranch], { cwd: worktreePath });
+    const base = await mergeBase(worktreePath, `origin/${targetBranch}`);
+    const head = await currentHeadSha(worktreePath);
+    if (head === base) {
+        throw new Error(`nothing to squash — HEAD is already at the merge-base with origin/${targetBranch}`);
+    }
+    await execFileAsync('git', ['reset', '--soft', base], { cwd: worktreePath });
+    await commit(worktreePath, commitMessage);
+}
+//# sourceMappingURL=squash.js.map

package/dist/git/squash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"squash.js","sourceRoot":"","sources":["../../src/git/squash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,KAAK,UAAU,cAAc,CAAC,YAAoB;IAChD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;IAC5F,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,YAAoB,EAAE,YAAoB,EAAE,aAAqB;IACjH,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;IACrF,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,YAAY,EAAE,UAAU,YAAY,EAAE,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,qEAAqE,YAAY,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;IAC7E,MAAM,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AAC5C,CAAC"}

package/dist/state/runState.d.ts

@@ -5,6 +5,7 @@
  * state (the forge client's findExistingMr is the real idempotency guard).
  */
 import type { RunState } from '../types.js';
+import type { AgentUsage } from '../agent/types.js';
 export declare function saveRunState(repoRoot: string, state: RunState): void;
 export declare function loadRunState(repoRoot: string, branch: string): RunState | undefined;
 /**
@@ -13,7 +14,15 @@ export declare function loadRunState(repoRoot: string, branch: string): RunState
  * `state` in place, matching how saveRunState is already called throughout
  * orchestrate.ts/watchPipeline.ts.
  */
-export declare function recordEvent(repoRoot: string, state: RunState, message: string, level?: 'info' | 'error'): void;
+export declare function recordEvent(repoRoot: string, state: RunState, message: string, level?: 'info' | 'error', tokens?: number): void;
+/**
+ * Narrates one agent turn into the run's history, carrying its token spend
+ * when the adapter reported any (see AgentUsage). A no-op when there is no
+ * usage to record: an entry saying "spent unknown tokens" would add noise to
+ * `sessions` without informing anyone — the turn itself is already narrated
+ * by its surrounding step events.
+ */
+export declare function recordAgentTokens(repoRoot: string, state: RunState, purpose: string, usage: AgentUsage | undefined): void;
 export interface RunSession {
     branch: string;
     state: RunState;

package/dist/state/runState.js

@@ -35,12 +35,20 @@ export function saveRunState(repoRoot, state) {
         console.error(`Warning: failed to persist run state for branch ${state.branch}: ${message}`);
     }
 }
+function migrateRunState(raw) {
+    if (raw.ciFixAttempt === undefined || raw.conflictAttempt === undefined) {
+        const legacy = raw.attempt ?? 0;
+        raw.ciFixAttempt ??= legacy;
+        raw.conflictAttempt ??= legacy;
+    }
+    return raw;
+}
 export function loadRunState(repoRoot, branch) {
     const path = statePath(repoRoot, branch);
     if (!existsSync(path))
         return undefined;
     try {
-        return JSON.parse(readFileSync(path, 'utf-8'));
+        return migrateRunState(JSON.parse(readFileSync(path, 'utf-8')));
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -54,14 +62,32 @@ export function loadRunState(repoRoot, branch) {
  * `state` in place, matching how saveRunState is already called throughout
  * orchestrate.ts/watchPipeline.ts.
  */
-export function recordEvent(repoRoot, state, message, level = 'info') {
+export function recordEvent(repoRoot, state, message, level = 'info', tokens) {
     const now = new Date().toISOString();
     state.startedAt ??= now;
     state.updatedAt = now;
-    const history = [...(state.history ?? []), { at: now, phase: state.phase, level, message }];
+    const entry = { at: now, phase: state.phase, level, message };
+    if (tokens !== undefined) {
+        entry.tokens = tokens;
+        state.totalTokens = (state.totalTokens ?? 0) + tokens;
+    }
+    const history = [...(state.history ?? []), entry];
     state.history = history.length > MAX_HISTORY_ENTRIES ? history.slice(history.length - MAX_HISTORY_ENTRIES) : history;
     saveRunState(repoRoot, state);
 }
+/**
+ * Narrates one agent turn into the run's history, carrying its token spend
+ * when the adapter reported any (see AgentUsage). A no-op when there is no
+ * usage to record: an entry saying "spent unknown tokens" would add noise to
+ * `sessions` without informing anyone — the turn itself is already narrated
+ * by its surrounding step events.
+ */
+export function recordAgentTokens(repoRoot, state, purpose, usage) {
+    const tokens = usage?.totalTokens;
+    if (tokens === undefined)
+        return;
+    recordEvent(repoRoot, state, `Agent turn (${purpose})`, 'info', tokens);
+}
 /**
  * Lists every persisted run in this repo (one per state file), most
  * recently updated first. A corrupt/partial state file is skipped rather

package/dist/state/runState.js.map

@@ -1 +1 @@
-{"version":3,"file":"runState.js","sourceRoot":"","sources":["../../src/state/runState.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runState.js","sourceRoot":"","sources":["../../src/state/runState.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,8FAA8F;AAC9F,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,SAAS,QAAQ,CAAC,QAAgB;IAChC,OAAO,IAAI,CAAC,QAAQ,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,SAAS,CAAC,QAAgB,EAAE,MAAc;IACjD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAe;IAC5D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC/B,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/C,wEAAwE;QACxE,qEAAqE;QACrE,wEAAwE;QACxE,yEAAyE;QACzE,oCAAoC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;QAClD,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QAChE,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,KAAK,CAAC,mDAAmD,KAAK,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC;IAC/F,CAAC;AACH,CAAC;AAgBD,SAAS,eAAe,CAAC,GAAoC;IAC3D,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,GAAG,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACxE,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;QAChC,GAAG,CAAC,YAAY,KAAK,MAAM,CAAC;QAC5B,GAAG,CAAC,eAAe,KAAK,MAAM,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,MAAc;IAC3D,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAa,CAAC,CAAC;IAC9E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,KAAK,CAAC,wCAAwC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QAC1E,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,KAAe,EAAE,OAAe,EAAE,QAA0B,MAAM,EAAE,MAAe;IAC/H,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,KAAK,CAAC,SAAS,KAAK,GAAG,CAAC;IACxB,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC;IACtB,MAAM,KAAK,GAAoB,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC/E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;QACtB,KAAK,CAAC,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC;IACxD,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IAClD,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACrH,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAe,EAAE,OAAe,EAAE,KAA6B;IACjH,MAAM,MAAM,GAAG,KAAK,EAAE,WAAW,CAAC;IAClC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,eAAe,OAAO,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1E,CAAC;AAOD;;;;;GAKG;AACH,qCAAqC;AACrC,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACvC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAa,CAAC;YAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;AACnG,CAAC"}

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 /** Single source of truth for pipeline-worker's cross-module data shapes. */
 export type AgentName = 'claude' | 'copilot' | 'pi';
 export type ForgeName = 'gitlab' | 'github';
+export type MergeMethod = 'merge' | 'squash' | 'rebase';
 export interface PipelineWorkerConfig {
     agent: AgentName;
     forge: ForgeName;
@@ -31,6 +32,20 @@ export interface PipelineWorkerConfig {
     runLintAndTest: boolean;
     /** Once checks pass, add a bullet for this change under CHANGELOG.md's [Unreleased] section (creating the file if absent) and include it in the commit. Off by default: not every consuming repo keeps a changelog. */
     updateChangelog: boolean;
+    /** Once the MR/PR opens, ask the forge to merge it automatically as soon as CI (and any required approvals) allow — best-effort, never fails the run if the forge rejects it. Off by default: merging is a policy decision, not something to turn on silently. */
+    autoMergeOnGreen: boolean;
+    /** Merge strategy passed to enableAutoMerge. Defaults to 'squash'. GitLab has no per-request rebase option — 'rebase' there silently falls back to the project's own default merge method. */
+    mergeMethod: MergeMethod;
+    /**
+     * Once CI is green, collapse every commit this run made on the branch
+     * since it diverged from targetBranch into one (titled from the captured
+     * intent) and force-push — keeps history clean regardless of the target
+     * repo's merge-strategy setting. Off by default: unlike every other write
+     * this tool makes, this rewrites already-pushed history (force-push), a
+     * materially different risk. Only reliable with autoMergeOnGreen off — the
+     * forge may already have merged (and deleted) the branch before this runs.
+     */
+    squashOnMerge: boolean;
 }
 export type RunPhase = 'diff' | 'intent' | 'checks' | 'mr' | 'watch' | 'done' | 'escalated';
 /** One entry in RunState.history — a timestamped narration of what happened during the run, for `pipeline-worker sessions`. */
@@ -39,6 +54,8 @@ export interface RunHistoryEntry {
     phase: RunPhase;
     level: 'info' | 'error';
     message: string;
+    /** Agent tokens spent by the turn this entry narrates. Absent when the adapter reports no usage (pi/copilot) or the entry isn't an agent turn. */
+    tokens?: number;
 }
 export interface RunState {
     branch: string;
@@ -46,8 +63,13 @@ export interface RunState {
     worktreePath: string;
     mrIid?: number;
     pipelineId?: number;
-    attempt: number;
+    /** Automated-fix attempts spent on a real CI failure (watchPipeline.ts's runCiFixAttempt); bounded by config.maxFixAttempts independently of conflictAttempt. */
+    ciFixAttempt: number;
+    /** Automated-fix attempts spent resolving merge conflicts with the target branch (watchPipeline.ts's tryResolveConflicts); bounded by config.maxFixAttempts independently of ciFixAttempt, so a long-lived PR needing several trivial rebases can't exhaust the budget meant for real bug-fixing. */
+    conflictAttempt: number;
     phase: RunPhase;
+    /** Running sum of every history entry's `tokens` — the run's total agent spend, as far as the adapter reports it. Absent on state files written before this field existed and on runs whose adapter reports no usage. */
+    totalTokens?: number;
     /** ISO 8601 timestamp of when this run was first created. Absent on state files written before this field existed. */
     startedAt?: string;
     /** ISO 8601 timestamp of the most recent state write. Absent on state files written before this field existed. */

package/dist/ui/format.d.ts

@@ -0,0 +1,8 @@
+/** Shared human-readable formatting helpers for token/duration figures. */
+/**
+ * Renders a token count the way the run header and session views show it:
+ * `949 tok`, `1.9k tok`, `41.2k tok`, `1.2M tok`. One decimal place above
+ * 1000, with a trailing `.0` trimmed so round figures read as `2k tok`, not
+ * `2.0k tok`.
+ */
+export declare function formatTokens(tokens: number): string;

package/dist/ui/format.js

@@ -0,0 +1,17 @@
+/** Shared human-readable formatting helpers for token/duration figures. */
+/**
+ * Renders a token count the way the run header and session views show it:
+ * `949 tok`, `1.9k tok`, `41.2k tok`, `1.2M tok`. One decimal place above
+ * 1000, with a trailing `.0` trimmed so round figures read as `2k tok`, not
+ * `2.0k tok`.
+ */
+export function formatTokens(tokens) {
+    if (!Number.isFinite(tokens) || tokens < 0)
+        return '? tok';
+    if (tokens < 1000)
+        return `${Math.round(tokens)} tok`;
+    const scaled = tokens < 1_000_000 ? { value: tokens / 1000, suffix: 'k' } : { value: tokens / 1_000_000, suffix: 'M' };
+    const text = scaled.value.toFixed(1).replace(/\.0$/, '');
+    return `${text}${scaled.suffix} tok`;
+}
+//# sourceMappingURL=format.js.map

package/dist/ui/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/ui/format.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3D,IAAI,MAAM,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACtD,MAAM,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACvH,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,OAAO,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,MAAM,CAAC;AACvC,CAAC"}

package/dist/ui/renderer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Rendering strategies for the run tree (ui/runTree.ts). Two implementations:
+ *
+ * - LineRenderer (here): append-only scrolled lines — used when stdout is not
+ *   a TTY (CI logs, piped output) or when PIPELINE_WORKER_PLAIN_OUTPUT=true.
+ *   Zero cursor movement; colors are applied via node:util's styleText, which
+ *   already disables itself on non-color streams.
+ * - TreeRenderer (ui/treeRenderer.ts): the live TTY dashboard with a pinned
+ *   bottom region.
+ *
+ * Renderers receive fine-grained TreeEvents from the facade (ui/steps.ts) and
+ * may ignore the granularity (TreeRenderer just repaints). log() is the one
+ * channel for freeform text — notes, agent output, warnings — so a renderer
+ * that owns the screen can route it above its pinned region.
+ */
+import type { RunStatus, RunTree, StepNode, TreeEvent } from './runTree.js';
+export interface Renderer {
+    onEvent(event: TreeEvent, tree: RunTree): void;
+    /** Freeform text outside the tree: notes, agent output, warnings. */
+    log(text: string): void;
+    /** Final paint for the run's terminal status; must leave the terminal usable. */
+    stop(status: RunStatus, detail: string | undefined, tree: RunTree): void;
+}
+export declare function formatElapsed(ms: number): string;
+/** The parenthesized tail of a finished step: '(3.2s · 1.9k tok)', or '' when neither figure is known. */
+export declare function formatStepFigures(node: StepNode): string;
+/** 'attempt N/M' when both sides are known, else ''. */
+export declare function formatAttempt(node: StepNode): string;
+/**
+ * Append-only narration, one block per step: a bold start line with the
+ * detail beneath it, phase changes as indented arrows, and a colored
+ * ✓/✗/– settle line with duration and token figures. Mirrors the shape of
+ * the old numbered-stage output so non-TTY logs stay diffable and greppable.
+ */
+export declare class LineRenderer implements Renderer {
+    private readonly out;
+    constructor(out?: (line: string) => void);
+    onEvent(event: TreeEvent): void;
+    log(text: string): void;
+    stop(status: RunStatus, detail: string | undefined, tree: RunTree): void;
+}

package/dist/ui/renderer.js

@@ -0,0 +1,93 @@
+/**
+ * Rendering strategies for the run tree (ui/runTree.ts). Two implementations:
+ *
+ * - LineRenderer (here): append-only scrolled lines — used when stdout is not
+ *   a TTY (CI logs, piped output) or when PIPELINE_WORKER_PLAIN_OUTPUT=true.
+ *   Zero cursor movement; colors are applied via node:util's styleText, which
+ *   already disables itself on non-color streams.
+ * - TreeRenderer (ui/treeRenderer.ts): the live TTY dashboard with a pinned
+ *   bottom region.
+ *
+ * Renderers receive fine-grained TreeEvents from the facade (ui/steps.ts) and
+ * may ignore the granularity (TreeRenderer just repaints). log() is the one
+ * channel for freeform text — notes, agent output, warnings — so a renderer
+ * that owns the screen can route it above its pinned region.
+ */
+import { styleText } from 'node:util';
+import { formatTokens } from './format.js';
+export function formatElapsed(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+/** The parenthesized tail of a finished step: '(3.2s · 1.9k tok)', or '' when neither figure is known. */
+export function formatStepFigures(node) {
+    const parts = [];
+    if (node.durationMs !== undefined)
+        parts.push(formatElapsed(node.durationMs));
+    if (node.tokens !== undefined)
+        parts.push(formatTokens(node.tokens));
+    return parts.length > 0 ? ` (${parts.join(' · ')})` : '';
+}
+/** 'attempt N/M' when both sides are known, else ''. */
+export function formatAttempt(node) {
+    return node.attempt !== undefined && node.maxAttempts !== undefined ? `attempt ${node.attempt}/${node.maxAttempts}` : '';
+}
+const FINISH_GLYPH = { done: '✓', failed: '✗', skipped: '–' };
+const FINISH_COLOR = { done: 'green', failed: 'red', skipped: 'dim' };
+const FINAL_LINE = {
+    done: '🎉 Done',
+    failed: '✗ Run failed',
+    escalated: '🚨 Stopped for human review',
+    interrupted: '⏹ Interrupted',
+};
+/**
+ * Append-only narration, one block per step: a bold start line with the
+ * detail beneath it, phase changes as indented arrows, and a colored
+ * ✓/✗/– settle line with duration and token figures. Mirrors the shape of
+ * the old numbered-stage output so non-TTY logs stay diffable and greppable.
+ */
+export class LineRenderer {
+    out;
+    // The default defers the console.log lookup to call time (not construction),
+    // so a test — or the TreeRenderer's console interception — that swaps
+    // console.log after this renderer exists still receives the output.
+    constructor(out = (line) => console.log(line)) {
+        this.out = out;
+    }
+    onEvent(event) {
+        if (event.kind === 'start') {
+            const attempt = formatAttempt(event.node);
+            this.out('');
+            this.out(styleText(['bold', 'cyan'], `▶ ${event.node.label}${attempt ? ` — ${attempt}` : ''}`));
+            if (event.node.detail)
+                this.out(styleText('dim', `  ${event.node.detail}`));
+            return;
+        }
+        if (event.kind === 'update' && event.node.status === 'running' && event.node.detail) {
+            this.out(styleText('dim', `  → ${event.node.detail}`));
+            return;
+        }
+        if (event.kind === 'finish') {
+            const status = event.node.status;
+            const glyph = FINISH_GLYPH[status] ?? '?';
+            const skipTail = status === 'skipped' ? ' (skipped)' : '';
+            const detail = event.node.detail ? ` — ${event.node.detail}` : '';
+            this.out(styleText(FINISH_COLOR[status] ?? 'dim', `${glyph} ${event.node.label}${skipTail}${detail}${formatStepFigures(event.node)}`));
+        }
+        // 'add', 'tokens', and 'header' need no line of their own: tokens show on
+        // the finish line, and header changes only matter to the live dashboard.
+    }
+    log(text) {
+        this.out(text);
+    }
+    stop(status, detail, tree) {
+        if (status === 'running')
+            return;
+        const total = tree.totalTokens();
+        const tokensPart = total > 0 ? ` (${formatTokens(total)})` : '';
+        this.out('');
+        this.out(styleText('bold', `${FINAL_LINE[status]}${tokensPart}`));
+        if (detail)
+            this.out(styleText('dim', `  ${detail}`));
+    }
+}
+//# sourceMappingURL=renderer.js.map

package/dist/ui/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../src/ui/renderer.ts"],"names":[],"mappings":"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"}

package/dist/ui/runTree.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The run's step tree: a pure in-memory data model of every workflow step,
+ * its status, timing, attempt counters, and best-effort token spend. This is
+ * what the renderers (ui/renderer.ts, ui/treeRenderer.ts) draw from — it
+ * contains no ANSI, no console access, and never throws: an unknown step id
+ * is auto-added as a top-level node rather than crashing the workflow (the
+ * UI must never kill a run — see CLAUDE.md's never-throw contracts).
+ *
+ * Step identity is a string id ('capture', 'ci-watch', 'ci-watch/fix-2').
+ * Ids replaced the old hard-coded stage numbers ([7/14]) because the watch
+ * loop grows children dynamically — fix attempts, rebases — and stable ids
+ * don't need renumbering when a step is inserted.
+ */
+export type StepStatus = 'pending' | 'running' | 'done' | 'failed' | 'skipped';
+/** The whole run's terminal status, shown in the header line. */
+export type RunStatus = 'running' | 'done' | 'failed' | 'escalated' | 'interrupted';
+export interface StepNode {
+    /** Unique within the tree; children conventionally use 'parent/child' ids. */
+    id: string;
+    /** Short name in the left column: 'capture', 'ci-watch', 'fix 2'. */
+    label: string;
+    /** Right-hand description; mutable while the step runs (phase updates). */
+    detail: string;
+    status: StepStatus;
+    /** Epoch ms when the step entered 'running'. */
+    startedAt?: number;
+    /** Set when the step finishes ('done'/'failed'). */
+    durationMs?: number;
+    /** Best-effort agent tokens attributed to this step; absent means unknown, never zero. */
+    tokens?: number;
+    /** Rendered as 'attempt N/M' when both are present. */
+    attempt?: number;
+    maxAttempts?: number;
+    children: StepNode[];
+}
+/** What a skeleton declares per step up front — everything else starts pending/empty. */
+export interface StepSeed {
+    id: string;
+    label: string;
+    detail: string;
+}
+export interface RunHeader {
+    /** The run's name: initially generic, updated once intent names the branch. */
+    title: string;
+    /** Short worktree identifier (last hex chars of the temp-branch uuid). */
+    worktreeShortId?: string;
+    status: RunStatus;
+}
+export type TreeEvent = {
+    kind: 'add';
+    node: StepNode;
+} | {
+    kind: 'start';
+    node: StepNode;
+} | {
+    kind: 'finish';
+    node: StepNode;
+} | {
+    kind: 'update';
+    node: StepNode;
+} | {
+    kind: 'tokens';
+    node: StepNode;
+} | {
+    kind: 'header';
+};
+/** One renderable row of the flattened tree: the node, its depth, and whether it is the last sibling at each ancestor level (for branch glyphs). */
+export interface TreeRow {
+    node: StepNode;
+    depth: number;
+    /** isLast[d] — whether the chain through this row is the final sibling at depth d. Drives '├─' vs '└─' and '│' vs ' ' continuation. */
+    isLast: boolean[];
+}
+export declare class RunTree {
+    private readonly onChange;
+    readonly roots: StepNode[];
+    readonly header: RunHeader;
+    private readonly index;
+    /** Tokens spent before this tree existed (a resumed run's persisted total) — folded into totalTokens(). */
+    private seededTokens;
+    constructor(skeleton: StepSeed[], header: {
+        title: string;
+        worktreeShortId?: string;
+    }, onChange: (event: TreeEvent) => void);
+    private insert;
+    get(id: string): StepNode | undefined;
+    /**
+     * The never-throw guarantee: any operation on an id nobody declared falls
+     * back to materializing that id as a fresh top-level node, so the workflow
+     * keeps narrating instead of dying on a UI bookkeeping mismatch.
+     */
+    private getOrAdd;
+    /** Adds a child under parentId (or top-level when parentId is undefined). Adding an id that already exists is a no-op returning the existing node. */
+    add(parentId: string | undefined, seed: StepSeed, extras?: Partial<StepNode>): StepNode;
+    start(id: string, patch?: Partial<Pick<StepNode, 'detail' | 'attempt' | 'maxAttempts'>>): StepNode;
+    finish(id: string, status: 'done' | 'failed' | 'skipped', patch?: Partial<Pick<StepNode, 'detail'>>): StepNode;
+    update(id: string, patch: Partial<Pick<StepNode, 'detail' | 'attempt' | 'maxAttempts'>>): StepNode;
+    addTokens(id: string, tokens: number): void;
+    /** Registers tokens spent before this tree existed (a resumed run's persisted total). */
+    seedTokens(tokens: number): void;
+    setHeader(patch: Partial<RunHeader>): void;
+    /** The run's total spend: every node's tokens plus any seeded pre-resume total. */
+    totalTokens(): number;
+    /** Depth-first rows for rendering, with last-sibling flags per ancestor level for branch glyphs. */
+    flatten(): TreeRow[];
+}