@cleocode/core 2026.10.25 → 2026.10.26

package/dist/resources/tool-groups.d.ts

@@ -28,9 +28,12 @@ export declare function isProbeableId(id: unknown): id is number;
  * process groups) and for an id that is not probeable.
  *
  * @param pgid - The group id: the pid of a child spawned with `detached: true`.
- * @returns Marks the group as no longer running (idempotent).
+ * @returns Marks the group as no longer running (idempotent). Every slot this
+ *   process holds is told, so its record drops the group: a finished group id
+ *   that the system later reuses never keeps a dead holder's charge (T14066).
  *
  * @task T12963
+ * @task T14066
  */
 export declare function trackToolGroup(pgid: number | undefined): () => void;
 /**
@@ -42,16 +45,17 @@ export declare function trackToolGroup(pgid: number | undefined): () => void;
  */
 export declare function activeToolGroups(): number[];
 /**
- * Follow the tool groups started while a slot is held: seeded with the groups
- * already running, then `onNew` is called with the full list each time
- * another one starts.
+ * Follow the tool groups running while a slot is held: seeded with the groups
+ * already running, then `onChange` is called with the full list each time one
+ * starts or finishes.
  *
- * @param onNew - Called with every group recorded so far, after each new one.
- * @returns The groups recorded so far (kept up to date) and `stop`.
+ * @param onChange - Called with every group still running, after each change.
+ * @returns The groups running now (kept up to date) and `stop`.
  *
  * @task T12963
+ * @task T14066
  */
-export declare function followToolGroups(onNew: (groups: readonly number[]) => void): {
+export declare function followToolGroups(onChange: (groups: readonly number[]) => void): {
     groups: readonly number[];
     stop: () => void;
 };

package/dist/resources/tool-groups.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-groups.d.ts","sourceRoot":"","sources":["../../src/resources/tool-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,IAAI,CASnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,GAAG;IAC5E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAcA;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAU5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}
+{"version":3,"file":"tool-groups.d.ts","sourceRoot":"","sources":["../../src/resources/tool-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,IAAI,CAUnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,GAAG;IAC/E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAgBA;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAU5E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/dist/resources/tool-groups.js

@@ -32,9 +32,12 @@ export function isProbeableId(id) {
  * process groups) and for an id that is not probeable.
  *
  * @param pgid - The group id: the pid of a child spawned with `detached: true`.
- * @returns Marks the group as no longer running (idempotent).
+ * @returns Marks the group as no longer running (idempotent). Every slot this
+ *   process holds is told, so its record drops the group: a finished group id
+ *   that the system later reuses never keeps a dead holder's charge (T14066).
  *
  * @task T12963
+ * @task T14066
  */
 export function trackToolGroup(pgid) {
     if (process.platform === 'win32' || !isProbeableId(pgid) || _active.has(pgid)) {
@@ -42,9 +45,12 @@ export function trackToolGroup(pgid) {
     }
     _active.add(pgid);
     for (const listener of _listeners)
-        listener(pgid);
+        listener(pgid, true);
     return () => {
-        _active.delete(pgid);
+        if (!_active.delete(pgid))
+            return;
+        for (const listener of _listeners)
+            listener(pgid, false);
     };
 }
 /**
@@ -58,22 +64,27 @@ export function activeToolGroups() {
     return [..._active];
 }
 /**
- * Follow the tool groups started while a slot is held: seeded with the groups
- * already running, then `onNew` is called with the full list each time
- * another one starts.
+ * Follow the tool groups running while a slot is held: seeded with the groups
+ * already running, then `onChange` is called with the full list each time one
+ * starts or finishes.
  *
- * @param onNew - Called with every group recorded so far, after each new one.
- * @returns The groups recorded so far (kept up to date) and `stop`.
+ * @param onChange - Called with every group still running, after each change.
+ * @returns The groups running now (kept up to date) and `stop`.
  *
  * @task T12963
+ * @task T14066
  */
-export function followToolGroups(onNew) {
+export function followToolGroups(onChange) {
     const groups = activeToolGroups();
-    const listener = (pgid) => {
-        if (groups.includes(pgid))
+    const listener = (pgid, running) => {
+        const at = groups.indexOf(pgid);
+        if (running === at >= 0)
             return;
-        groups.push(pgid);
-        onNew(groups);
+        if (running)
+            groups.push(pgid);
+        else
+            groups.splice(at, 1);
+        onChange(groups);
     };
     _listeners.add(listener);
     return {

package/dist/resources/tool-groups.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-groups.js","sourceRoot":"","sources":["../../src/resources/tool-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;AAClC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,KAAK,MAAM,QAAQ,IAAI,UAAU;QAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,GAAG,EAAE;QACV,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA0C;IAIzE,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAQ,EAAE;QACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO;QAClC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,KAAK,CAAC,MAAM,CAAC,CAAC;IAChB,CAAC,CAAC;IACF,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,OAAO;QACL,MAAM;QACN,IAAI,EAAE,GAAG,EAAE;YACT,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvB,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC;QACpC,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"tool-groups.js","sourceRoot":"","sources":["../../src/resources/tool-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;AAClC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA4C,CAAC;AAEvE;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9E,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,KAAK,MAAM,QAAQ,IAAI,UAAU;QAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACxD,OAAO,GAAG,EAAE;QACV,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO;QAClC,KAAK,MAAM,QAAQ,IAAI,UAAU;YAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA6C;IAI5E,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,OAAgB,EAAQ,EAAE;QACxD,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,OAAO,KAAK,EAAE,IAAI,CAAC;YAAE,OAAO;QAChC,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnB,CAAC,CAAC;IACF,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,OAAO;QACL,MAAM;QACN,IAAI,EAAE,GAAG,EAAE;YACT,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvB,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC;QACpC,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}

package/dist/spawn/branch-integration.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Branch integration for agent worktrees (T10862): default-branch resolution,
+ * upstream fetch and landed-detection, the merge decision, the `--no-ff` merge
+ * of `task/<id>` into the local target branch (ADR-062) and its audit row.
+ *
+ * Owns merge / fetch / checkout policy only. Worktree add, remove, list and
+ * lock stay in the lifecycle module ({@link ./branch-lock.ts}) and the
+ * `@cleocode/worktree` facade; this module calls {@link pruneWorktree} after a
+ * merge and never touches `git worktree` itself.
+ *
+ * @task T10862
+ * @task T10863
+ * @task T10864
+ * @adr ADR-062
+ */
+import type { EvidenceAtom, WorktreeIntegrationOutcome, WorktreeIntegrationPlan, WorktreeMergeResult } from '@cleocode/contracts';
+/**
+ * Resolve the project's default integration branch in a project-agnostic way.
+ *
+ * Resolution order (per ADR-062):
+ *
+ * 1. `.cleo/config.json::git.defaultBranch` (explicit override).
+ * 2. `git symbolic-ref refs/remotes/origin/HEAD` (what the remote calls
+ *    default — works for `master`, `main`, `trunk`, etc.).
+ * 3. Probe local branches in order: `main`, `master`, `develop`, `trunk`.
+ * 4. Fallback to `'main'`.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @returns The resolved default branch name (never throws).
+ *
+ * @task T1587
+ * @adr ADR-062
+ */
+export declare function getDefaultBranch(projectRoot: string): string;
+/**
+ * Verdict of {@link assessUpstreamIntegration}.
+ *
+ * - `landed` — the task branch is already on the upstream default branch
+ *   (ancestor of it, or its changes are fully contained in it). No local
+ *   merge may run.
+ * - `nothing` — the task branch has no commits beyond the local default
+ *   branch (e.g. a worktree that was never committed to). There is nothing to
+ *   integrate, and it is NOT reported as landed upstream.
+ * - `stale-target` — the local default branch is behind the upstream default
+ *   branch (possibly also ahead of it — diverged); a merge there would fork it
+ *   from upstream. No local merge may run.
+ * - `proceed` — no upstream to compare against, or the local default branch is
+ *   current; the ADR-062 local `--no-ff` integration may run.
+ *
+ * @task T12773
+ */
+export type UpstreamIntegrationKind = 'landed' | 'nothing' | 'stale-target' | 'proceed';
+/**
+ * Result of {@link assessUpstreamIntegration}.
+ *
+ * @task T12773
+ */
+export interface UpstreamIntegrationAssessment {
+    /** What the caller may do next. */
+    kind: UpstreamIntegrationKind;
+    /** Remote-tracking ref compared against (e.g. `refs/remotes/origin/main`), or null. */
+    upstreamRef: string | null;
+    /**
+     * True when this assessment ran `git fetch <remote> <targetBranch>` (whether
+     * or not it succeeded), so a later integration step need not fetch again.
+     */
+    fetched: boolean;
+    /** Commits on the upstream ref missing from the local default branch. */
+    behind: number;
+    /** Commits on the local default branch missing from the upstream ref. */
+    ahead: number;
+    /**
+     * Exact shell command that syncs the local default branch with upstream,
+     * or empty when no sync is needed. NEVER run by CLEO — the operator's
+     * checkout is never moved (hint-only policy).
+     */
+    syncCommand: string;
+    /** Operator-facing explanation / next step (empty for `proceed`). */
+    hint: string;
+}
+/**
+ * Default timeout for the upstream `git fetch` in
+ * {@link assessUpstreamIntegration}. Short on purpose: the fetch is
+ * best-effort, and a hung network or credential prompt must never stall
+ * `cleo done` for the 180s generic git timeout.
+ *
+ * @task T12773
+ */
+export declare const UPSTREAM_FETCH_TIMEOUT_MS = 20000;
+/**
+ * Decide whether a local ADR-062 `--no-ff` integration of `branch` into
+ * `targetBranch` is safe, by comparing against the upstream default branch
+ * (`<remote>/<targetBranch>`).
+ *
+ * T12773: `cleo done --pr <n>` for a task whose PR had already merged on
+ * origin ran `git merge --no-ff task/<id>` into a local `main` that was 199
+ * commits behind origin, creating a local merge commit that forked `main`
+ * from `origin/main`. This check runs BEFORE any checkout or merge:
+ *
+ * - branch has no commits beyond the local default branch → `nothing`.
+ * - branch already on upstream → `landed`; when the local default branch is
+ *   behind, the hint names the exact sync command. The checkout is never
+ *   moved (hint-only).
+ * - local default branch behind upstream → `stale-target`; a distinct hint
+ *   when it is also ahead (diverged: unpushed local commits).
+ * - otherwise (no remote, no upstream ref, current target) → `proceed`.
+ *
+ * The fetch is best-effort, non-interactive (`GIT_TERMINAL_PROMPT=0`, ssh
+ * `BatchMode`) and bounded by {@link UPSTREAM_FETCH_TIMEOUT_MS}; offline, the
+ * last-known remote-tracking ref is used. Never creates a commit and never
+ * moves any ref other than the remote-tracking one the fetch updates.
+ *
+ * @param gitRoot - Absolute git root of the project checkout.
+ * @param branch - Task branch (e.g. `task/T123`).
+ * @param targetBranch - Resolved default branch (e.g. `main`).
+ * @param opts.skipFetch - Skip `git fetch <remote> <targetBranch>` (fixtures).
+ * @param opts.remote - Remote name (default `origin`).
+ * @param opts.fetchTimeoutMs - Fetch timeout (default {@link UPSTREAM_FETCH_TIMEOUT_MS}).
+ * @returns The assessment.
+ *
+ * @task T12773
+ * @adr ADR-062
+ */
+export declare function assessUpstreamIntegration(gitRoot: string, branch: string, targetBranch: string, opts?: {
+    skipFetch?: boolean;
+    remote?: string;
+    fetchTimeoutMs?: number;
+}): UpstreamIntegrationAssessment;
+/**
+ * Options for {@link planWorktreeIntegration} and the merge run that shares
+ * its decision (T14053).
+ */
+export interface WorktreeIntegrationDecisionOptions {
+    /** Override the resolved default branch. */
+    targetBranch?: string;
+    /**
+     * Set when integration is switched off (`cleo complete --no-integrate`,
+     * `CLEO_NO_AUTO_WORKTREE_COMPLETE`): the decision is `skip` with this reason.
+     */
+    disabledReason?: string;
+    /** Skip the upstream `git fetch` (the plan never fetches). */
+    skipFetch?: boolean;
+    /** Timeout for the upstream fetch. */
+    fetchTimeoutMs?: number;
+}
+/**
+ * Preview what completing `taskId` does with its worktree branch, without
+ * changing git: the same decision the merge run makes, from local refs only
+ * (no fetch). Shown by `cleo done --plan` (T14053).
+ *
+ * @param taskId - The CLEO task ID.
+ * @param projectRoot - Absolute path to the project root.
+ * @param opts - Target override and the switched-off reason, if any.
+ * @returns Branch, worktree path, target branch, `merge`/`skip`/`refuse` and why.
+ *
+ * @example
+ * ```ts
+ * planWorktreeIntegration('T123', root).action; // 'skip' for a task merged by PR
+ * ```
+ * @task T14053
+ */
+export declare function planWorktreeIntegration(taskId: string, projectRoot: string, opts?: Omit<WorktreeIntegrationDecisionOptions, 'skipFetch' | 'fetchTimeoutMs'>): WorktreeIntegrationPlan;
+/**
+ * Complete a worker task's worktree via `git merge --no-ff` (ADR-062).
+ *
+ * Canonical worktree integration per ADR-062. Preserves the full agent
+ * commit graph instead of rewriting SHAs, so `git log --grep "T<id>"`
+ * returns the originating commits with their original authorship.
+ *
+ * Steps performed inside the worktree at
+ * `~/.local/share/cleo/worktrees/<projectHash>/<taskId>/`:
+ *
+ * 1. Resolve target branch via {@link getDefaultBranch} (or `opts.targetBranch`
+ *    override). NEVER hardcodes "main".
+ * 1. T14053: {@link decideWorktreeIntegration} first — the same decision
+ *    `cleo done --plan` shows. A branch CLEO did not provision is skipped
+ *    (`notProvisioned`), never merged; a main checkout on another branch,
+ *    with uncommitted tracked changes, or a linked worktree is refused
+ *    (`rootRefused`) without switching or merging anything.
+ * 1a. T12773: {@link assessUpstreamIntegration} — when `task/<id>` already
+ *    landed on `origin/<targetBranch>` the merge is skipped
+ *    (`landedUpstream: true`); when it has no commits beyond the local
+ *    target it is `nothingToIntegrate` without `landedUpstream`; when the
+ *    local target is behind (or diverged from) origin the merge is refused
+ *    (`staleTarget: true`) with a `hint`. None of these paths creates a
+ *    commit or moves the operator's checkout — syncing is hint-only.
+ * 2. Optionally `git fetch` (skipped when step 1a already fetched), then
+ *    `git checkout <targetBranch>` in the project's git root. The task
+ *    branch is NOT rebased — agent SHAs are preserved.
+ * 3. Run `git merge --no-ff task/<taskId> -m "<taskId>: <title> (worktree
+ *    merge)"`; a failed merge is aborted so the repo is left clean, and the
+ *    worktree is preserved.
+ * 4. Capture the merge commit SHA and report it.
+ * 5. Delegate worktree+branch removal to {@link pruneWorktree} (T1462).
+ *
+ * Project-agnostic: no string in this function hardcodes "main", "master",
+ * or any other branch name. Test fixtures pass arbitrary `targetBranch`.
+ *
+ * @param taskId - The CLEO task ID (e.g. `"T1587"`).
+ * @param projectRoot - Absolute path to the project root.
+ * @param opts.targetBranch - Override the resolved default branch.
+ * @param opts.taskTitle - Task title used in the merge commit message subject.
+ * @param opts.skipFetch - Skip every `git fetch` (test fixtures).
+ * @param opts.evidence - The task's evidence atoms; the prune keeps a worktree holding the only copy (T13696).
+ * @param opts.fetchTimeoutMs - Timeout for the upstream fetch (default
+ *   {@link UPSTREAM_FETCH_TIMEOUT_MS}).
+ * @param opts.disabledReason - Integration is switched off; nothing is touched (T14053).
+ * @returns Merge integration result, with the decision it acted on in `plan`.
+ *
+ * @task T1587
+ * @task T14053
+ * @adr ADR-062
+ */
+export declare function completeAgentWorktreeViaMerge(taskId: string, projectRoot: string, opts?: {
+    targetBranch?: string;
+    disabledReason?: string;
+    taskTitle?: string;
+    skipFetch?: boolean;
+    fetchTimeoutMs?: number;
+    evidence?: readonly EvidenceAtom[];
+}): WorktreeMergeResult;
+/**
+ * Result of a complete post-merge worktree integration.
+ *
+ * Extends `WorktreeMergeResult` with an additional audit log path field.
+ *
+ * @task T9043
+ * @adr ADR-062
+ */
+export interface WorktreeIntegrationResult extends WorktreeMergeResult {
+    /** Path to the audit log entry that was written (if any). */
+    auditLogEntry: string | null;
+}
+/**
+ * Complete a worker task's worktree integration via merge, cleanup, and audit log.
+ *
+ * This is the orchestrator-facing convenience wrapper around
+ * `completeAgentWorktreeViaMerge`. In addition to the merge+prune steps it:
+ *
+ * 1. Delegates all merge and cleanup to `completeAgentWorktreeViaMerge`.
+ * 2. Appends a structured entry to `.cleo/audit/worktree-integration.jsonl`
+ *    recording the merge commit, task ID, and cleanup outcome.
+ *
+ * Orchestrators MUST call this (not `completeAgentWorktreeViaMerge` directly)
+ * so every integration is auditable.
+ *
+ * @param taskId - The CLEO task ID (e.g. `"T1587"`).
+ * @param projectRoot - Absolute path to the project root.
+ * @param opts.targetBranch - Override the resolved default branch.
+ * @param opts.taskTitle - Task title used in the merge commit message subject.
+ * @param opts.skipFetch - Skip the `git fetch origin` step (test fixtures).
+ * @param opts.auditLogPath - Override the audit JSONL path (testing).
+ * @param opts.evidence - The task's evidence atoms; the prune keeps a worktree holding the only copy (T13696).
+ * @returns Integration result including audit log path.
+ *
+ * @task T9043
+ * @adr ADR-062
+ */
+export declare function completeAgentWorktreeIntegration(taskId: string, projectRoot: string, opts?: {
+    targetBranch?: string;
+    taskTitle?: string;
+    skipFetch?: boolean;
+    auditLogPath?: string;
+    evidence?: readonly EvidenceAtom[];
+}): WorktreeIntegrationResult;
+/**
+ * The single integration result for a completion envelope (T14053): what the
+ * run actually did, so it can never contradict the merge. `merge` only when a
+ * merge commit was made; a decided merge that failed reads as `refuse`.
+ *
+ * @param result - The merge run's result (its `plan` is the decision it acted on).
+ * @returns `{branch, worktreePath, targetBranch, action, reason, mergeCommit?, pushed: false}`.
+ *
+ * @example
+ * ```ts
+ * integrationOutcome(completeAgentWorktreeIntegration('T1', root)).action; // 'skip'
+ * ```
+ * @task T14053
+ */
+export declare function integrationOutcome(result: WorktreeMergeResult): WorktreeIntegrationOutcome;
+//# sourceMappingURL=branch-integration.d.ts.map

package/dist/spawn/branch-integration.d.ts.map

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