@gitkraken/compose-tools 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,12 +6,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and this
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-11
+
+### Added
+
+- Adds an optional `maxTokens` field to every task input (`analyze`, `group`, `compose-group`, `order`, `partition`, `quick-compose`) and to the top-level `ComposeInput`, `ComposePlanInput`, and `SplitInput`. Forwarded to `runAiLoop` → `model.generate`. Defaults stay at 16384; bump on very large diffs whose structured output overflows the cap.
+- Adds optional `includeWorkdir` to the `{ type: 'commit-range' }` source, with three independent flags — `includeStaged`, `includeUnstaged`, `includeUntracked`. Combines a contiguous commit range with the user's working changes in a single composed input. Constraint: `to` must equal the current branch tip (including-workdir on a mid-range slice has no defined WIP basis); the library validates this and throws `ComposeWorkflowInputError` otherwise.
+- Adds `applyUpTo` partial-apply on `ComposeInput` and `ApplyComposePlanInput`. `{ kind: 'all' }` (default) applies the entire plan; `{ kind: 'count', count: N }` applies the first `N` commits in plan order; `{ kind: 'commitId', id }` applies up to and including the named commit. Hunks not covered by the applied prefix become uncommitted leftover in the worktree. Incompatible with `target: 'auto'`; throws `ComposeWorkflowInputError` on combination.
+- Adds `stashLabel` on `ComposeInput` and `ApplyComposePlanInput`. Custom message for the safety stash the apply step creates when the worktree is dirty; defaults to `compose backup`. Consumers wanting their own abandoned-stash recovery UX use a stable prefix here and scan `git stash list` for it after process kills.
+- Adds new fields on apply results — `appliedCommitIds` (the prefix of `plan.allOrderedCommits.map(c => c.id)` actually written; same as the full plan when `applyUpTo` is unset or `'all'`), `unappliedHunkIndices` (hunk indices from the plan not covered by the applied commits), and `stashConflict` (set when the post-apply stash pop hit conflicts — apply itself succeeded and the named stash is preserved for manual recovery). Type exports: `ApplyUpTo`, `StashConflict`.
+- Adds optional `applyPatchToWorkdir` op on `ComposeGitOps` — worktree-only `git apply` (no `--cached`). The library uses it to write leftover hunks during partial apply. CLI / hybrid consumers fall through to `exec(['apply', ...])` automatically; libgit2-style consumers should provide a libgit2-backed implementation.
+- Adds `withIndex?: boolean` on the `stashPop` op via a new `StashPopOptions` argument (`stashPop?: (opts?: StashPopOptions) => Promise<void>`). Maps to `git stash pop --index` so originally-staged content is restored as staged after the apply. The previous signature was `(opts?: OpOptions)`; `StashPopOptions` extends `OpOptions`, so existing implementations remain type-compatible. Ops-only consumers should honor `withIndex` to preserve the user's pre-stash staging.
+- Adds optional `hunkFilter` on `ApplyComposePlanInput`. Required to match the filter passed to `composePlan` when the plan was originally created &mdash; the library re-applies the filter to the freshly collected hunks before its drift check. Plans created with a filter that are applied without the equivalent filter will fail the drift check (or, in degenerate cases, apply with the filter silently ignored, reintroducing excluded content as leftover). Consumers that serialize plans across processes should record the filter spec (e.g. excluded file names) alongside the plan and reconstruct the filter on apply.
+
+### Changed
+
+- **Breaking:** Renames the workflow error classes to compose-scoped names &mdash; `WorkflowError` &rarr; `ComposeWorkflowError`, `WorkflowInputError` &rarr; `ComposeWorkflowInputError`, `WorkflowErrorCode` &rarr; `ComposeWorkflowErrorCode`. The shape and codes are unchanged; consumers only need to update import / `instanceof` sites.
+- **Breaking:** Renames the cancellation field on workflow and task inputs from `signal` to `cancellation` to make the contract clear: this token only flows into the AI loop, not into git operations. Mid-flight cancellation of a git op risks a half-mutated repo, so by design git operations always run to completion.
+- **Breaking:** Removes the `signal` field from `OpOptions` and from `ApplyComposePlanInput`, `UndoComposeInput`, `ValidateUndoComposeInput`, and `listUndoIds` &mdash; those are git-only paths and run to completion.
+- The AI loop now throws a native `AbortError` on cancellation; workflows translate it into `ComposeWorkflowError('CANCELLED')` for consumers via the new `rethrowAsWorkflowError` helper.
+- The apply step now backs up pending workdir state via `git stash push --include-untracked` before mutating, and pops it back afterward. Conflicts during the post-apply pop surface as `result.stashConflict` rather than throwing &mdash; apply itself succeeded, the named stash is preserved, and consumers handle restoration through their own UX. Set `stashLabel` for a stable prefix consumers can recognize in `git stash list` for abandoned-stash recovery flows. Apply-time observers will see new stash entries created and (on success) immediately popped; if you've been scanning the reflog or the stash list around an apply, expect this entry pair.
+- Tightens upfront guidance against duplicate hunks in the `group`, `compose-group`, and `quick-compose` system prompts &mdash; an explicit "Critical constraints" section spells out the four hard rules and asks the model to self-check the hunk count before producing the output tag.
+- Sharpens the default commit-message guidance to require both a summary line and a description body separated by a blank line.
+- Validation error feedback now shows where each duplicated hunk landed (`hunk N → branch-1/commit-2, branch-2/commit-3`) and reports the total reference count vs the expected count, so duplicate / drift / truncation patterns are obvious at a glance.
+- JSON-parse failures in validators now include the underlying error message and a 300-character tail of the model's output, making it obvious when a response was truncated by `maxTokens` rather than malformed.
+
+### Fixed
+
+- `applyComposePlan` now correctly handles plans created with a `hunkFilter` that dropped hunks. The drift check applies the same filter to the fresh collection before comparing diff hashes, and falls back to source-state hashes (filter-agnostic) when diff hashes mismatch on any verify path. Previously this surfaced as a spurious `SAFETY_CHECK_FAILED` even when the user hadn't drifted; now requires the consumer to pass the same `hunkFilter` to `applyComposePlan` &mdash; see the "Added" entry for `hunkFilter` on `ApplyComposePlanInput`.
+- The `rewrite-range` and `branch-replace` apply paths now capture the user's pre-apply state with a single top-level stash that runs before any branch ref movement. Previously the stash could be taken after the ref move had already shifted HEAD's effective SHA, producing a stash whose recorded parent disagreed with its content; on pop this could surface as reverse-staged changes ("staged: file added/removed" the user never staged) or `would be overwritten by merge` / `untracked working tree files would be overwritten` failures.
+- The apply step's leftover-patch now covers only `branch`-source hunks when a stash backup was taken; WIP-source restoration (modified files via 3-way merge, originally-staged content via index restore, untracked files via `u`-commit checkout) is now left entirely to the post-apply pop. Avoids the dual-write that produced `untracked already exists` and `would be overwritten` failures in earlier versions.
+
 ## [0.1.0] - 2026-04-23
 
 ### Added
 
 - Adds `compose(input)` &mdash; one-call sugar that runs planning and apply together; ideal when the consumer does not need to surface the plan for review
-- Adds `composePlan(input)` and `applyComposePlan(input)` &mdash; a two-phase API for consumers (e.g. GitLens's webview) that surface the plan for user review or editing before applying; `applyComposePlan` reverifies the workdir matches the plan's snapshot before mutating
+- Adds `composePlan(input)` and `applyComposePlan(input)` &mdash; a two-phase API for consumers that surface the plan for user review or editing before applying; `applyComposePlan` reverifies the workdir matches the plan's snapshot before mutating
 - Adds `split(input)` &mdash; partitions an existing multi-commit branch into a stack of smaller, reviewable branches
 - Adds `undoCompose(input)` and `validateUndoCompose(input)` &mdash; surgical reversal of only the git mutations a compose operation recorded, plus a dry-run validator that reports blockers and warnings without mutating the repo
 - Adds `ComposeGitPort` &mdash; the git surface used by every workflow; accepts raw `exec`, a hybrid of `exec` plus targeted high-level op overrides (e.g. a signing-aware `commitTree`), or an ops-only implementation for libgit2-backed consumers; missing ops throw `ComposeGitPortMissingOpError` naming the missing op

package/README.md

@@ -66,7 +66,9 @@ const git: ComposeGitPort = {
 
 **Libgit2-style — high-level ops only, no `exec`.** A libgit2-backed consumer implements the specific ops used by its flow. If a flow needs an op the consumer didn't provide and `exec` isn't available either, the library throws `ComposeGitPortMissingOpError` naming the missing op.
 
-The full list of high-level ops is in the `ComposeGitOps` type; the most commonly overridden are `commitTree`, `readTree`, `writeTree`, `applyPatchToIndex`, `diffTree`, `stageAll`. Every op takes an `OpOptions` with `signal?: AbortSignal`.
+The full list of high-level ops is in the `ComposeGitOps` type; the most commonly overridden are `commitTree`, `readTree`, `writeTree`, `applyPatchToIndex`, `applyPatchToWorkdir`, `diffTree`, `stageAll`. `OpOptions` is currently empty — git operations are not cancellable in this library; they always run to completion to avoid leaving the repo half-mutated. Cancellation flows only into the AI loop (see [`cancellation`](#cancellation) below).
+
+`stashPop` accepts a `StashPopOptions` argument with `withIndex?: boolean` (maps to `git stash pop --index`); ops-only consumers should honor `withIndex` to preserve the user's pre-stash staging after the apply step's safety stash is popped.
 
 ### `AiModelPort`
 
@@ -122,7 +124,7 @@ const result = await compose({
 
 ### `composePlan(input)` + `applyComposePlan(input)` — two-phase
 
-Returns the plan without mutating the repo, lets the user review/edit it, then applies. This is the shape GitLens-style UIs use (plan → webview → user edits → apply).
+Returns the plan without mutating the repo, lets the user review/edit it, then applies. This is the shape interactive review UIs use (plan → review surface → user edits → apply).
 
 ```typescript
 import { composePlan, applyComposePlan } from '@gitkraken/compose-tools';
@@ -148,7 +150,7 @@ const applied = await applyComposePlan({
 });
 ```
 
-`applyComposePlan` reverifies the workdir matches `snapshot` before mutating. If it drifted between plan and apply, it throws `WorkflowError('SAFETY_CHECK_FAILED')`.
+`applyComposePlan` reverifies the workdir matches `snapshot` before mutating. If it drifted between plan and apply, it throws `ComposeWorkflowError('SAFETY_CHECK_FAILED')`.
 
 ### `split(input)`
 
@@ -181,7 +183,7 @@ See [Undo](#undo) below.
 |---|---|
 | `{ type: 'workdir', stagedOnly?, noUntracked? }` | Collects staged, unstaged, and untracked changes. `stagedOnly: true` limits to the index; `noUntracked: true` skips untracked files. |
 | `{ type: 'branch', name, mergeTarget? }` | Collects `mergeBase(mergeTarget, name) → name` as one combined diff. `mergeTarget` defaults to `'main'`. |
-| `{ type: 'commit-range', branch, from, to }` | Collects a contiguous range on `branch` with per-hunk author info. `from` is **exclusive** (parent of the first commit to include); `to` is **inclusive**. For a single-commit recompose: `from = parent(sha), to = sha`. |
+| `{ type: 'commit-range', branch, from, to, includeWorkdir? }` | Collects a contiguous range on `branch` with per-hunk author info. `from` is **exclusive** (parent of the first commit to include); `to` is **inclusive**. For a single-commit recompose: `from = parent(sha), to = sha`. Pass `includeWorkdir: { includeStaged?, includeUnstaged?, includeUntracked? }` to combine the range with the user's working changes in a single composed input — useful for "rewrite recent commits and the WIP on top of them" flows. When set, `to` must equal the current branch tip; the library throws `ComposeWorkflowInputError` otherwise. |
 
 ## Targets
 
@@ -257,7 +259,7 @@ Consumers build their own per-call telemetry from these. No built-in telemetry i
 
 ### `onBeforePrompt`
 
-Gating hook — run immediately before each `model.generate`. Returning `false` aborts the workflow with `WorkflowError('CANCELLED')`. Use for large-prompt confirmations, cost warnings, org policy checks.
+Gating hook — run immediately before each `model.generate`. Returning `false` aborts the workflow with `ComposeWorkflowError('CANCELLED')`. Use for large-prompt confirmations, cost warnings, org policy checks.
 
 ```typescript
 onBeforePrompt: async ({ phase, attempt, tokenEstimate, charCount, messageCount }) => {
@@ -278,6 +280,8 @@ hunkFilter: async (hunks) => hunks.filter(h => !isAiIgnored(h.fileName)),
 
 The filter must preserve the original `index` values on remaining hunks (only drop entries, never renumber). The library rebuilds the safety snapshot to reflect just the filtered subset, so `verifyResultingDiff` still has a correct expectation. `result.hunksFilteredCount` tells the consumer how many were dropped.
 
+**`hunkFilter` and the two-phase `composePlan` / `applyComposePlan` flow:** `applyComposePlan` accepts the same `hunkFilter` field. **You must pass an equivalent filter at apply time** — the library re-applies it to the freshly collected hunks before the drift check, otherwise the cached (filtered) snapshot's diff hash won't match the (unfiltered) fresh diff. For consumers that serialize the plan across processes (e.g. CLI save-to-JSON workflows), record the filter spec — the list of excluded file names, the AIIgnore glob set, etc. — alongside the plan and reconstruct the function on apply. The filter function itself isn't serializable; its inputs typically are.
+
 ### `signing`
 
 GPG signing for produced commits. Typically derived from `git config commit.gpgsign` + `user.signingkey`.
@@ -300,9 +304,56 @@ How the primary author is picked when a commit's hunks come from multiple origin
 | `'first-hunk'` | Use the first hunk's author; other distinct authors become `Co-authored-by:` trailers |
 | function | Fully custom — inspect the hunks and return the primary identity (or `undefined` to use the commit creator's identity). Co-authors are still derived from the union of remaining authors |
 
-### `signal`
+### `cancellation`
+
+Standard `AbortSignal`, but with a deliberately narrow scope: it is forwarded **only into the AI loop** — every `model.generate` call and the prompt-gate hook. Git operations (collection, snapshot verification, applying, undo manifest persistence) run to completion regardless of whether `cancellation` was aborted; mid-flight cancellation of a git op risks a half-mutated repo, so by design only the AI loop is cancellable.
+
+On AI-loop abort, the workflow translates the native `AbortError` into `ComposeWorkflowError('CANCELLED')` so consumers only have to check for the workflow-domain shape.
+
+```typescript
+const controller = new AbortController();
+const result = await compose({ git, model, cancellation: controller.signal });
+// later: controller.abort() — interrupts the next AI call; any git op already in
+// flight finishes normally, then the workflow throws ComposeWorkflowError('CANCELLED').
+```
+
+`applyComposePlan`, `undoCompose`, `validateUndoCompose`, and `listUndoIds` do **not** accept `cancellation` — they are git-only and run to completion.
+
+### `applyUpTo`
+
+Apply only a prefix of the planned commits. Hunks not covered by the applied prefix become uncommitted leftover in the worktree (modified for tracked files, untracked for new files; the user's pre-apply staging on those hunks is preserved by the post-apply stash restore).
+
+```typescript
+applyUpTo: { kind: 'all' }                          // default — apply the entire plan
+applyUpTo: { kind: 'count', count: 2 }              // first 2 in plan order
+applyUpTo: { kind: 'commitId', id: 'commit-3' }     // up to and including commit-3
+```
+
+Incompatible with `target: 'auto'` — the library throws `ComposeWorkflowInputError` on that combination. Compatible with `head`, `branch`, `branch-replace`, and `rewrite-range`.
+
+The result includes `appliedCommitIds` (the SHAs that were actually written, a prefix of `plan.allOrderedCommits.map(c => c.id)`) and `unappliedHunkIndices` (the hunk indices the partial apply left behind).
+
+### `stashLabel`
+
+Custom message for the safety stash the apply step creates when the worktree is dirty. Defaults to `compose backup`.
 
-Standard `AbortSignal`. Threaded through every AI call, every git operation, and every hook. On abort, the workflow throws `WorkflowError('CANCELLED')`.
+```typescript
+stashLabel: `myapp-compose-${new Date().toISOString()}`
+```
+
+The apply step always stashes pending workdir state via `git stash push --include-untracked` before mutating, and pops it back after. If the post-apply pop hits conflicts, the result includes `stashConflict: { stashLabel, conflictedFiles }` — apply itself succeeded, the named stash is preserved, and the consumer surfaces recovery UX (typical pattern: scan `git stash list` for a stable prefix on next mode-entry to detect abandoned stashes after process kills).
+
+### `maxTokens`
+
+Output-token cap forwarded to every `model.generate` call in the pipeline. Defaults to `runAiLoop`'s 16384.
+
+Bump it on very large diffs whose structured output (e.g. analyze's per-hunk annotations) overflows the cap mid-JSON. When that happens, the validator surfaces a JSON-parse failure with a `Response tail: …` preview of the last 300 characters of the model's output, so it's obvious the response was truncated rather than malformed.
+
+```typescript
+const result = await compose({ git, model, maxTokens: 32_000 });
+```
+
+`maxTokens` is also accepted on every individual task (`analyze`, `group`, `compose-group`, `order`, `partition`, `quick-compose`) for the same reason.
 
 ### `session` (resumable workflows)
 
@@ -385,6 +436,9 @@ Every top-level entry point returns an object with these common fields:
 | `commitShas` | apply paths | `{ commitId: sha }` mapping for every commit written |
 | `undoId` | apply paths | Pass to `undoCompose()` to reverse |
 | `partitions` / `partitionGroups` | apply paths with partitioning | Applied partition info |
+| `appliedCommitIds` | apply paths | Plan commit IDs actually written. Same as `plan.allOrderedCommits.map(c => c.id)` for full apply; a prefix when `applyUpTo` is set. |
+| `unappliedHunkIndices` | apply paths | Hunk indices from the plan not covered by `appliedCommitIds`. Empty for full apply. |
+| `stashConflict` | apply paths | `{ stashLabel, conflictedFiles }` set when the post-apply stash pop hit conflicts. Apply itself succeeded; the named stash is preserved for the consumer's recovery UX. |
 
 ## Undo
 
@@ -437,7 +491,19 @@ for (const warning of validation.warnings) console.warn(`Warning: ${warning.type
 await undoCompose({ git, undoId, force: true });
 ```
 
-Downgrades the "branch has new commits" blocker to a warning. The `dirty_workdir` blocker is never force-able.
+Downgrades the "branch has new commits" blocker to a warning. Equivalent to `force: { branchHasNewCommits: true }`.
+
+For finer control, pass an object form:
+
+```typescript
+await undoCompose({
+    git,
+    undoId,
+    force: { branchHasNewCommits: true, dirtyWorkdir: true },
+});
+```
+
+`dirtyWorkdir: true` allows undo to proceed despite uncommitted changes — the HEAD restore step does a `reset --hard`, so anything in the worktree is clobbered. Use only when the dirty state is a known artifact of the operation being undone (e.g. a failed stash pop after a successful apply where the consumer chose to roll back) and the caller has confirmed work loss with the user. `head_sha_unreachable` and `manifest_not_found` are never force-able regardless of flags.
 
 ### List all undo IDs
 
@@ -462,21 +528,21 @@ The AI pipeline is built from composable task functions. Call them individually
 | `composeGroup(input)` | Combined analyze + group in a single AI call (used by `balanced` / `quick` depths) |
 | `quickCompose(input)` | Full pipeline (analyze + group + order + optional partition) in a single AI call |
 
-Each task accepts an optional `session` to maintain AI conversation context (or to resume from cached `completedSteps`), and returns an updated session in its output. Each task also accepts `promptOverride`, `onBeforeModelCall`, `onAfterModelCall`, `onBeforePrompt`, and `signal` for the same behaviors as the top-level entry points.
+Each task accepts an optional `session` to maintain AI conversation context (or to resume from cached `completedSteps`), and returns an updated session in its output. Each task also accepts `promptOverride`, `maxTokens`, `onBeforeModelCall`, `onAfterModelCall`, `onBeforePrompt`, and `cancellation` for the same behaviors as the top-level entry points.
 
 ## Error handling
 
 | Error | Codes |
 |---|---|
 | `GitError` | `NO_CHANGES`, `BRANCH_NOT_FOUND`, `OPERATION_FAILED`, `SAFETY_CHECK_FAILED`, `CHERRY_PICK_CONFLICT` |
-| `WorkflowError` | `SAFETY_CHECK_FAILED` (workdir changed between plan and apply), `INTERNAL`, `CANCELLED` |
-| `WorkflowInputError` | Invalid workflow input (missing `model`, incompatible source/target combination, etc.) |
+| `ComposeWorkflowError` | `SAFETY_CHECK_FAILED` (workdir changed between plan and apply), `INTERNAL`, `CANCELLED` |
+| `ComposeWorkflowInputError` | Invalid workflow input (missing `model`, incompatible source/target combination, etc.) |
 | `TaskInputError` | Invalid task input |
 | `AIError` | AI output failed schema validation after all retries. Code: `VALIDATION_EXHAUSTED` |
 | `ComposeGitPortMissingOpError` | A flow needs a `ComposeGitOps` method the consumer didn't provide and `exec` isn't available either. Has `.op` (missing op name) and `.hint`. |
 
 ```typescript
-import { compose, GitError, WorkflowError, AIError } from '@gitkraken/compose-tools';
+import { compose, GitError, ComposeWorkflowError, AIError } from '@gitkraken/compose-tools';
 
 try {
     await compose({ git, model });
@@ -487,9 +553,9 @@ try {
         console.error(`Conflict cherry-picking ${error.detail?.sha}`);
     } else if (error instanceof AIError) {
         console.error('AI could not produce valid output after retries');
-    } else if (error instanceof WorkflowError && error.code === 'CANCELLED') {
+    } else if (error instanceof ComposeWorkflowError && error.code === 'CANCELLED') {
         console.log('Operation cancelled');
-    } else if (error instanceof WorkflowError) {
+    } else if (error instanceof ComposeWorkflowError) {
         console.error(`Workflow failed: ${error.code} — ${error.message}`);
     }
 }

package/dist/errors/workflow.d.ts

@@ -1,13 +1,23 @@
 //#region src/errors/workflow.d.ts
-type WorkflowErrorCode = 'SAFETY_CHECK_FAILED' | 'INTERNAL' | 'CANCELLED';
-declare class WorkflowInputError extends Error {
+type ComposeWorkflowErrorCode = 'SAFETY_CHECK_FAILED' | 'INTERNAL' | 'CANCELLED';
+/**
+ * Thrown when a workflow input is malformed or self-inconsistent (e.g. a
+ * source/target combination that cannot apply, or a session with mismatched
+ * commit-message format).
+ */
+declare class ComposeWorkflowInputError extends Error {
   constructor(message: string);
 }
-declare class WorkflowError extends Error {
-  readonly code: WorkflowErrorCode;
-  constructor(code: WorkflowErrorCode, message: string, options?: {
+/**
+ * Thrown when a workflow fails at a domain checkpoint — safety verification
+ * drift, internal invariant violation, or cancellation. Carries a `code` so
+ * consumers can branch on the failure mode.
+ */
+declare class ComposeWorkflowError extends Error {
+  readonly code: ComposeWorkflowErrorCode;
+  constructor(code: ComposeWorkflowErrorCode, message: string, options?: {
     cause?: unknown;
   });
 }
 //#endregion
-export { WorkflowError, WorkflowErrorCode, WorkflowInputError };
+export { ComposeWorkflowError, ComposeWorkflowErrorCode, ComposeWorkflowInputError };

package/dist/errors/workflow.js

@@ -1 +1 @@
-var e=class extends Error{constructor(e){super(e),this.name=`WorkflowInputError`}},t=class extends Error{code;constructor(e,t,n){super(t,n),this.name=`WorkflowError`,this.code=e}};export{t as WorkflowError,e as WorkflowInputError};
+var e=class extends Error{constructor(e){super(e),this.name=`ComposeWorkflowInputError`}},t=class extends Error{code;constructor(e,t,n){super(t,n),this.name=`ComposeWorkflowError`,this.code=e}};export{t as ComposeWorkflowError,e as ComposeWorkflowInputError};

package/dist/git/apply-branches.d.ts

@@ -8,7 +8,6 @@ interface ApplyBranchStructureParams {
   branches: ApplyBranchEntry[];
   originalBranchName?: string;
   originalBranchSha?: string;
-  signal?: AbortSignal;
 }
 interface ApplyBranchEntry {
   /** The partition(s) for this branch group. Each partition becomes a git branch. */
@@ -22,7 +21,6 @@ declare function createStackedBranches(params: {
   partitions: BranchPartition[];
   originalBranchName?: string;
   originalBranchSha?: string;
-  signal?: AbortSignal;
 }): Promise<void>;
 //#endregion
 export { ApplyBranchEntry, ApplyBranchStructureParams, applyBranchStructure, createStackedBranches };

package/dist/git/apply-branches.js

@@ -1 +1 @@
-import{checkout as e,createBranch as t,currentBranch as n,deleteBranch as r}from"./port-dispatch.js";async function i(i){let{git:a,branches:o,originalBranchName:s,originalBranchSha:c,signal:l}=i;if(l?.throwIfAborted(),s&&c){let i=await n(a,{signal:l})===s;i&&await e(a,c,{detach:!0,signal:l}),await r(a,s,{force:!0,signal:l});for(let e of o)for(let n of e.partitions){l?.throwIfAborted();let e=n.commitIds[n.commitIds.length-1];await t(a,n.branchName,e,{signal:l})}if(i&&o.length>0){let t=o[o.length-1],n=t.partitions[t.partitions.length-1];await e(a,n.branchName,{signal:l})}}else for(let e of o)for(let n of e.partitions){l?.throwIfAborted();let e=n.commitIds[n.commitIds.length-1];await t(a,n.branchName,e,{signal:l})}}async function a(e){return i({git:e.git,branches:[{partitions:e.partitions,tipSha:e.partitions[e.partitions.length-1].commitIds[e.partitions[e.partitions.length-1].commitIds.length-1]}],originalBranchName:e.originalBranchName,originalBranchSha:e.originalBranchSha,signal:e.signal})}export{i as applyBranchStructure,a as createStackedBranches};
+import{checkout as e,createBranch as t,currentBranch as n,deleteBranch as r}from"./port-dispatch.js";async function i(i){let{git:a,branches:o,originalBranchName:s,originalBranchSha:c}=i;if(s&&c){let i=await n(a)===s;i&&await e(a,c,{detach:!0}),await r(a,s,{force:!0});for(let e of o)for(let n of e.partitions){let e=n.commitIds[n.commitIds.length-1];await t(a,n.branchName,e)}if(i&&o.length>0){let t=o[o.length-1],n=t.partitions[t.partitions.length-1];await e(a,n.branchName)}}else for(let e of o)for(let n of e.partitions){let e=n.commitIds[n.commitIds.length-1];await t(a,n.branchName,e)}}async function a(e){return i({git:e.git,branches:[{partitions:e.partitions,tipSha:e.partitions[e.partitions.length-1].commitIds[e.partitions[e.partitions.length-1].commitIds.length-1]}],originalBranchName:e.originalBranchName,originalBranchSha:e.originalBranchSha})}export{i as applyBranchStructure,a as createStackedBranches};

package/dist/git/apply-target.d.ts

@@ -2,7 +2,7 @@ import { ComposeGitPort, SigningConfig } from "../ports/git.js";
 import { BranchGroup, BranchPartition, CommitSuggestion, ComposeHunk } from "../tasks/types.js";
 import { PartitionResult } from "../tasks/partition/types.js";
 import { ComposeTarget } from "../workflows/types.js";
-import { ApplyMutations, SafetySnapshot } from "./types.js";
+import { ApplyMutations, SafetySnapshot, StashConflict } from "./types.js";
 import { CollectionResult } from "./diff-collector.js";
 
 //#region src/git/apply-target.d.ts
@@ -19,12 +19,22 @@ interface ApplyToTargetParams {
   hunks: ComposeHunk[];
   snapshot: SafetySnapshot;
   collection: CollectionResult;
-  signal?: AbortSignal;
   signing?: SigningConfig;
   authorAttribution?: 'plurality' | 'first-hunk' | ((hunks: ComposeHunk[]) => {
     name: string;
     email: string;
   } | undefined);
+  /** Stash message used by the apply helpers when stashing pending workdir state. */
+  stashLabel?: string;
+  /** Patch applied to the worktree after the chain is reset. Used to restore the unapplied
+   *  hunks of a partial apply so the user's content isn't lost when their leftover hunks lived in
+   *  commits being rewritten (commits-only / commit-range+workdir partial apply). */
+  leftoverPatch?: string;
+  /** Variant of {@link leftoverPatch} containing only branch-source hunks. Applied instead of
+   *  the full leftover patch when stashing happens — WIP-source leftover hunks are restored
+   *  by the stash pop's 3-way merge / index restore / untracked checkout, so writing them
+   *  to the worktree pre-pop causes "would be overwritten" or "already exists" errors. */
+  leftoverPatchBranchOnly?: string;
 }
 interface ApplyToTargetResult {
   partitions?: BranchPartition[];
@@ -33,6 +43,7 @@ interface ApplyToTargetResult {
   commitShas: Record<string, string>;
   /** Git mutations performed during apply, for undo manifest construction. */
   mutations: ApplyMutations;
+  stashConflict?: StashConflict;
 }
 declare function applyToTarget(params: ApplyToTargetParams): Promise<ApplyToTargetResult>;
 //#endregion

package/dist/git/apply-target.js

@@ -1 +1 @@
-import{GitError as e}from"../errors/git.js";import{cleanWorkdir as t,discardWorkdirChanges as n,revParse as r}from"./port-dispatch.js";import{applyBranchStructure as i}from"./apply-branches.js";import{applyCommitChain as a,applyRangeRewrite as o,applyRecompose as s,buildCommitChain as c}from"./commit-chain.js";import{verifyMultiBranchDiff as l,verifyResultingDiff as u}from"./safety.js";async function d(t){let{git:n,target:l,branchPlans:d,allOrderedCommits:m,hunks:h,snapshot:v,collection:y,signal:b,signing:x,authorAttribution:S}=t;if(b?.throwIfAborted(),l.type===`rewrite-range`){if(!y.branchName||!y.branchSha)throw new e(`OPERATION_FAILED`,`rewrite-range target requires a source that records branchName and branchSha (branch or commit-range).`);let{headSha:t,shaMap:r}=await c({git:n,baseSha:l.rangeFrom,commits:m,hunks:h,signal:b,signing:x,authorAttribution:S}),i=await o({git:n,branch:l.branch,rangeFrom:l.rangeFrom,rangeTo:l.rangeTo,newHeadSha:t,originalBranchSha:y.branchSha,preserveSuffix:l.preserveSuffix,signal:b});return{commitShas:Object.fromEntries(r),mutations:{createdBranches:[],deletedBranches:[],movedBranches:[{name:l.branch,previousSha:y.branchSha,newSha:i.finalTipSha}]}}}if(y.branchName&&!y.mergeBaseSha)throw new e(`OPERATION_FAILED`,`Branch source is missing mergeBaseSha — cannot determine base commit`);let C=y.mergeBaseSha??await r(n,`HEAD`,{signal:b});if(l.type===`auto`&&d.length>1)return f(n,C,d,h,v,y,l.preserveOriginal,b,x,S);if(l.type===`auto`&&d.length===1&&d[0].partitioning)return p(n,C,d[0],h,v,y,l.preserveOriginal,b,x,S);let{headSha:w,shaMap:T}=await c({git:n,baseSha:C,commits:m,hunks:h,signal:b,signing:x,authorAttribution:S}),E=Object.fromEntries(T),D=await u(n,C,w,v,b);if(!D.valid)throw new e(`SAFETY_CHECK_FAILED`,`Diff verification failed: ${D.error}`);if(l.type===`branch-replace`){if(!y.branchName||!y.branchSha)throw new e(`OPERATION_FAILED`,`branch-replace target requires a branch source with branchName and branchSha`);return await s({git:n,branchName:y.branchName,newHeadSha:w,originalBranchSha:y.branchSha,signal:b}),{commitShas:E,mutations:{createdBranches:[],deletedBranches:[],movedBranches:[{name:y.branchName,previousSha:y.branchSha,newSha:w}]}}}if(l.type===`branch`)return await a({git:n,newHeadSha:w,branchName:l.name,untrackedIncluded:y.untrackedIncluded,signal:b}),{commitShas:E,mutations:{createdBranches:[{name:l.name,sha:w}],deletedBranches:[],movedBranches:[]}};if(l.type===`auto`){let e=d[0]?.branchGroup.name||y.branchName;if(e){let t=!l.preserveOriginal&&y.branchName&&y.branchSha?{originalBranchName:y.branchName,originalBranchSha:y.branchSha}:{},r={branchName:e,title:d[0]?.branchGroup.title??``,description:d[0]?.branchGroup.description??``,commitIds:m.map(e=>e.id)};await i({git:n,branches:[{partitions:[r],tipSha:w}],...t,signal:b});let a=_([r],E,t.originalBranchName,t.originalBranchSha);return{partitions:[r],commitShas:E,mutations:a}}return await a({git:n,newHeadSha:w,untrackedIncluded:y.untrackedIncluded,signal:b}),{commitShas:E,mutations:g()}}return await a({git:n,newHeadSha:w,untrackedIncluded:y.untrackedIncluded,signal:b}),{commitShas:E,mutations:g()}}async function f(r,a,o,s,u,d,f,p,g,v){let y=[],b=[],x=[],S=[],C={};for(let e of o){p?.throwIfAborted();let t=m(e),{headSha:n,shaMap:i}=await c({git:r,baseSha:a,commits:t,hunks:s,signal:p,signing:g,authorAttribution:v});x.push(n);for(let[e,t]of i)C[e]=t;if(e.partitioning&&e.partitioning.partitions.length>1){let t=h(e.partitioning.partitions,i);y.push(...t),b.push(t),S.push({partitions:t,tipSha:n})}else{let r={branchName:e.branchGroup.name,title:e.branchGroup.title,description:e.branchGroup.description,commitIds:t.map(e=>i.get(e.id)??e.id)};y.push(r),b.push([r]),S.push({partitions:[r],tipSha:n})}}let w=await l(r,a,x,u,p);if(!w.valid)throw new e(`SAFETY_CHECK_FAILED`,`Diff verification failed: ${w.error}`);let T=!f&&d.branchName&&d.branchSha?{originalBranchName:d.branchName,originalBranchSha:d.branchSha}:{};return await i({git:r,branches:S,...T,signal:p}),!d.branchName&&!f&&(await n(r,void 0,{signal:p}),d.untrackedIncluded&&await t(r,{signal:p})),{partitions:y,partitionGroups:b,commitShas:C,mutations:_(y,C,T.originalBranchName,T.originalBranchSha)}}async function p(r,o,s,l,d,f,p,v,y,b){let{headSha:x,shaMap:S}=await c({git:r,baseSha:o,commits:m(s),hunks:l,signal:v,signing:y,authorAttribution:b}),C=await u(r,o,x,d,v);if(!C.valid)throw new e(`SAFETY_CHECK_FAILED`,`Diff verification failed: ${C.error}`);let w=h(s.partitioning.partitions,S),T=Object.fromEntries(S);if(w.length>1){let e=!p&&f.branchName&&f.branchSha?{originalBranchName:f.branchName,originalBranchSha:f.branchSha}:{};return await i({git:r,branches:[{partitions:w,tipSha:x}],...e,signal:v}),!f.branchName&&!p&&(await n(r,void 0,{signal:v}),f.untrackedIncluded&&await t(r,{force:!0,directories:!0,signal:v})),{partitions:w,commitShas:T,mutations:_(w,T,e.originalBranchName,e.originalBranchSha)}}return await a({git:r,newHeadSha:x,untrackedIncluded:f.untrackedIncluded,signal:v}),{partitions:w,commitShas:T,mutations:g()}}function m(t){return t.orderedCommitIds.map(n=>{let r=t.branchGroup.commits.find(e=>e.id===n);if(!r)throw new e(`OPERATION_FAILED`,`Commit ${n} not found in branch '${t.branchGroup.id}'`);return r})}function h(t,n){return t.map(t=>({...t,commitIds:t.commitIds.map(t=>{let r=n.get(t);if(!r)throw new e(`OPERATION_FAILED`,`No SHA found for commit ID '${t}'`);return r})}))}function g(){return{createdBranches:[],deletedBranches:[],movedBranches:[]}}function _(e,t,n,r){let i=e.map(e=>{let n=e.commitIds[e.commitIds.length-1];return{name:e.branchName,sha:t[n]??n}}),a=[];return n&&r&&a.push({name:n,sha:r}),{createdBranches:i,deletedBranches:a,movedBranches:[]}}export{d as applyToTarget};
+import{GitError as e}from"../errors/git.js";import{cleanWorkdir as t,discardWorkdirChanges as n,revParse as r}from"./port-dispatch.js";import{applyBranchStructure as i}from"./apply-branches.js";import{applyCommitChain as a,applyRangeRewrite as o,applyRecompose as s,buildCommitChain as c}from"./commit-chain.js";import{verifyMultiBranchDiff as l,verifyResultingDiff as u}from"./safety.js";async function d(t){let{git:n,target:l,branchPlans:d,allOrderedCommits:m,hunks:h,snapshot:v,collection:y,signing:b,authorAttribution:x,stashLabel:S,leftoverPatch:C,leftoverPatchBranchOnly:w}=t;if(l.type===`rewrite-range`){if(!y.branchName||!y.branchSha)throw new e(`OPERATION_FAILED`,`rewrite-range target requires a source that records branchName and branchSha (branch or commit-range).`);let{headSha:t,shaMap:r}=await c({git:n,baseSha:l.rangeFrom,commits:m,hunks:h,signing:b,authorAttribution:x}),i=await o({git:n,branch:l.branch,rangeFrom:l.rangeFrom,rangeTo:l.rangeTo,newHeadSha:t,originalBranchSha:y.branchSha,preserveSuffix:l.preserveSuffix,stashLabel:S,leftoverPatch:C,leftoverPatchBranchOnly:w});return{commitShas:Object.fromEntries(r),mutations:{createdBranches:[],deletedBranches:[],movedBranches:[{name:l.branch,previousSha:y.branchSha,newSha:i.finalTipSha}]},stashConflict:i.stashConflict}}if(y.branchName&&!y.mergeBaseSha)throw new e(`OPERATION_FAILED`,`Branch source is missing mergeBaseSha — cannot determine base commit`);let T=y.mergeBaseSha??await r(n,`HEAD`);if(l.type===`auto`&&d.length>1)return f(n,T,d,h,v,y,l.preserveOriginal,b,x);if(l.type===`auto`&&d.length===1&&d[0].partitioning)return p(n,T,d[0],h,v,y,l.preserveOriginal,b,x);let{headSha:E,shaMap:D}=await c({git:n,baseSha:T,commits:m,hunks:h,signing:b,authorAttribution:x}),O=Object.fromEntries(D),k=await u(n,T,E,v);if(!k.valid)throw new e(`SAFETY_CHECK_FAILED`,`Diff verification failed: ${k.error}`);if(l.type===`branch-replace`){if(!y.branchName||!y.branchSha)throw new e(`OPERATION_FAILED`,`branch-replace target requires a branch source with branchName and branchSha`);let t=await s({git:n,branchName:y.branchName,newHeadSha:E,originalBranchSha:y.branchSha,stashLabel:S,leftoverPatch:C,leftoverPatchBranchOnly:w});return{commitShas:O,mutations:{createdBranches:[],deletedBranches:[],movedBranches:[{name:y.branchName,previousSha:y.branchSha,newSha:E}]},stashConflict:t.stashConflict}}if(l.type===`branch`){let e=await a({git:n,newHeadSha:E,branchName:l.name,untrackedIncluded:y.untrackedIncluded,stashLabel:S,leftoverPatch:C,leftoverPatchBranchOnly:w});return{commitShas:O,mutations:{createdBranches:[{name:l.name,sha:E}],deletedBranches:[],movedBranches:[]},stashConflict:e.stashConflict}}if(l.type===`auto`){let e=d[0]?.branchGroup.name||y.branchName;if(e){let t=!l.preserveOriginal&&y.branchName&&y.branchSha?{originalBranchName:y.branchName,originalBranchSha:y.branchSha}:{},r={branchName:e,title:d[0]?.branchGroup.title??``,description:d[0]?.branchGroup.description??``,commitIds:m.map(e=>e.id)};await i({git:n,branches:[{partitions:[r],tipSha:E}],...t});let a=_([r],O,t.originalBranchName,t.originalBranchSha);return{partitions:[r],commitShas:O,mutations:a}}let t=await a({git:n,newHeadSha:E,untrackedIncluded:y.untrackedIncluded,stashLabel:S});return{commitShas:O,mutations:g(),stashConflict:t.stashConflict}}let A=await a({git:n,newHeadSha:E,untrackedIncluded:y.untrackedIncluded,stashLabel:S,leftoverPatch:C,leftoverPatchBranchOnly:w});return{commitShas:O,mutations:g(),stashConflict:A.stashConflict}}async function f(r,a,o,s,u,d,f,p,g){let v=[],y=[],b=[],x=[],S={};for(let e of o){let t=m(e),{headSha:n,shaMap:i}=await c({git:r,baseSha:a,commits:t,hunks:s,signing:p,authorAttribution:g});b.push(n);for(let[e,t]of i)S[e]=t;if(e.partitioning&&e.partitioning.partitions.length>1){let t=h(e.partitioning.partitions,i);v.push(...t),y.push(t),x.push({partitions:t,tipSha:n})}else{let r={branchName:e.branchGroup.name,title:e.branchGroup.title,description:e.branchGroup.description,commitIds:t.map(e=>i.get(e.id)??e.id)};v.push(r),y.push([r]),x.push({partitions:[r],tipSha:n})}}let C=await l(r,a,b,u);if(!C.valid)throw new e(`SAFETY_CHECK_FAILED`,`Diff verification failed: ${C.error}`);let w=!f&&d.branchName&&d.branchSha?{originalBranchName:d.branchName,originalBranchSha:d.branchSha}:{};return await i({git:r,branches:x,...w}),!d.branchName&&!f&&(await n(r),d.untrackedIncluded&&await t(r)),{partitions:v,partitionGroups:y,commitShas:S,mutations:_(v,S,w.originalBranchName,w.originalBranchSha)}}async function p(r,o,s,l,d,f,p,v,y){let{headSha:b,shaMap:x}=await c({git:r,baseSha:o,commits:m(s),hunks:l,signing:v,authorAttribution:y}),S=await u(r,o,b,d);if(!S.valid)throw new e(`SAFETY_CHECK_FAILED`,`Diff verification failed: ${S.error}`);let C=h(s.partitioning.partitions,x),w=Object.fromEntries(x);if(C.length>1){let e=!p&&f.branchName&&f.branchSha?{originalBranchName:f.branchName,originalBranchSha:f.branchSha}:{};return await i({git:r,branches:[{partitions:C,tipSha:b}],...e}),!f.branchName&&!p&&(await n(r),f.untrackedIncluded&&await t(r,{force:!0,directories:!0})),{partitions:C,commitShas:w,mutations:_(C,w,e.originalBranchName,e.originalBranchSha)}}return await a({git:r,newHeadSha:b,untrackedIncluded:f.untrackedIncluded}),{partitions:C,commitShas:w,mutations:g()}}function m(t){return t.orderedCommitIds.map(n=>{let r=t.branchGroup.commits.find(e=>e.id===n);if(!r)throw new e(`OPERATION_FAILED`,`Commit ${n} not found in branch '${t.branchGroup.id}'`);return r})}function h(t,n){return t.map(t=>({...t,commitIds:t.commitIds.map(t=>{let r=n.get(t);if(!r)throw new e(`OPERATION_FAILED`,`No SHA found for commit ID '${t}'`);return r})}))}function g(){return{createdBranches:[],deletedBranches:[],movedBranches:[]}}function _(e,t,n,r){let i=e.map(e=>{let n=e.commitIds[e.commitIds.length-1];return{name:e.branchName,sha:t[n]??n}}),a=[];return n&&r&&a.push({name:n,sha:r}),{createdBranches:i,deletedBranches:a,movedBranches:[]}}export{d as applyToTarget};

package/dist/git/commit-chain.d.ts

@@ -1,5 +1,6 @@
 import { ComposeGitPort, SigningConfig } from "../ports/git.js";
 import { CommitSuggestion, ComposeHunk } from "../tasks/types.js";
+import { StashConflict } from "./types.js";
 
 //#region src/git/commit-chain.d.ts
 type AuthorAttributionStrategy = 'plurality' | 'first-hunk' | ((hunks: ComposeHunk[]) => {
@@ -11,7 +12,6 @@ interface BuildCommitChainParams {
   baseSha: string;
   commits: CommitSuggestion[];
   hunks: ComposeHunk[];
-  signal?: AbortSignal;
   signing?: SigningConfig;
   authorAttribution?: AuthorAttributionStrategy;
 }
@@ -31,17 +31,33 @@ interface ApplyCommitChainParams {
    * conflicts between stash pop and the newly committed tree.
    */
   untrackedIncluded?: boolean;
-  signal?: AbortSignal;
+  /** Stash message used when a backup stash is needed. */
+  stashLabel?: string;
+  /** Patch applied to the worktree (no staging) after the chain is reset and before the stash is popped.
+   *  Used when no stash backup is taken (workdir was clean pre-apply). */
+  leftoverPatch?: string;
+  /** Branch-source-only variant of {@link leftoverPatch}. Used when a stash IS taken: WIP-source
+   *  leftover (modified/untracked files the user had pre-apply) is restored by the pop's 3-way
+   *  merge, index restore, and untracked checkout. Writing those hunks pre-pop causes git to
+   *  reject the pop ("would be overwritten" / "already exists"). Branch-source leftover is the
+   *  only category the stash has no record of, so it must still go through the patch path. */
+  leftoverPatchBranchOnly?: string;
 }
-declare function applyCommitChain(params: ApplyCommitChainParams): Promise<void>;
+interface ApplyChainResult {
+  stashConflict?: StashConflict;
+}
+declare function applyCommitChain(params: ApplyCommitChainParams): Promise<ApplyChainResult>;
 interface ApplyRecomposeParams {
   git: ComposeGitPort;
   branchName: string;
   newHeadSha: string;
   originalBranchSha: string;
-  signal?: AbortSignal;
+  stashLabel?: string;
+  leftoverPatch?: string;
+  /** See {@link ApplyCommitChainParams.leftoverPatchBranchOnly}. */
+  leftoverPatchBranchOnly?: string;
 }
-declare function applyRecompose(params: ApplyRecomposeParams): Promise<void>;
+declare function applyRecompose(params: ApplyRecomposeParams): Promise<ApplyChainResult>;
 interface ApplyRangeRewriteParams {
   git: ComposeGitPort;
   /** Branch whose tip will be updated to the result. */
@@ -56,13 +72,17 @@ interface ApplyRangeRewriteParams {
   originalBranchSha: string;
   /** When true (default), cherry-pick commits in `rangeTo..originalBranchSha` onto `newHeadSha`. */
   preserveSuffix?: boolean;
-  signal?: AbortSignal;
+  stashLabel?: string;
+  leftoverPatch?: string;
+  /** See {@link ApplyCommitChainParams.leftoverPatchBranchOnly}. */
+  leftoverPatchBranchOnly?: string;
 }
 interface ApplyRangeRewriteResult {
   /** Final branch tip SHA after range rewrite + (optional) suffix cherry-picks. */
   finalTipSha: string;
   /** SHAs that were successfully cherry-picked, in order applied. Empty when preserveSuffix=false or no suffix. */
   preservedSuffixShas: string[];
+  stashConflict?: StashConflict;
 }
 /**
  * Rewrite a contiguous range of commits on a branch in-place.
@@ -84,4 +104,4 @@ interface ApplyRangeRewriteResult {
  */
 declare function applyRangeRewrite(params: ApplyRangeRewriteParams): Promise<ApplyRangeRewriteResult>;
 //#endregion
-export { ApplyCommitChainParams, ApplyRangeRewriteParams, ApplyRangeRewriteResult, ApplyRecomposeParams, AuthorAttributionStrategy, BuildCommitChainParams, BuildCommitChainResult, applyCommitChain, applyRangeRewrite, applyRecompose, buildCommitChain };
+export { ApplyChainResult, ApplyCommitChainParams, ApplyRangeRewriteParams, ApplyRangeRewriteResult, ApplyRecomposeParams, AuthorAttributionStrategy, BuildCommitChainParams, BuildCommitChainResult, applyCommitChain, applyRangeRewrite, applyRecompose, buildCommitChain };

package/dist/git/commit-chain.js

@@ -1,6 +1,8 @@
-import{GitError as e}from"../errors/git.js";import{applyPatchToIndex as t,checkout as n,cherryPick as r,cherryPickAbort as i,commitTree as a,currentBranch as o,listUntracked as s,log as c,readTree as l,reset as u,revParse as d,stageAll as f,stashPop as p,stashPush as m,statusPorcelain as h,updateRef as g,writeTree as _}from"./port-dispatch.js";import{buildPatchForCommit as v}from"./utils/patch-builder.js";import{randomUUID as y}from"node:crypto";import*as b from"node:fs";import*as x from"node:os";import*as S from"node:path";async function C(n){let{git:r,baseSha:i,commits:o,hunks:s,signal:c,signing:u,authorAttribution:d=`plurality`}=n;c?.throwIfAborted();let f=S.join(x.tmpdir(),`compose-idx-${y()}`),p=i,m=new Map,h=new Set;try{for(let n of o){c?.throwIfAborted();let i=n.hunkIndices.map(t=>{let n=s.find(e=>e.index===t);if(!n)throw new e(`OPERATION_FAILED`,`Hunk index ${t} not found`);return n}),o=v(i.map(e=>h.has(e.diffHeader)?{...e,diffHeader:P(e.diffHeader,e.fileName)}:e));if(!o.trim())throw new e(`OPERATION_FAILED`,`Empty patch for commit: ${n.message}`);let g={GIT_INDEX_FILE:f};await l(r,p,{indexEnv:g,signal:c});try{await t(r,o,{indexEnv:g,signal:c})}catch(t){let r=t instanceof Error?t.message:String(t);throw new e(`OPERATION_FAILED`,`git apply failed for commit '${n.message.split(`
-`)[0]}': ${r}`,{cause:t})}for(let e of i)e.originalFileName&&e.diffHeader.includes(`rename from`)&&h.add(e.diffHeader);let y=await _(r,{indexEnv:g,signal:c}),b=A(i,d),x=M(n.message,b.coAuthors),S=await a(r,y,[p],x,{signal:c,signing:u,author:b.author});m.set(n.id,S),p=S}return{headSha:p,shaMap:m}}finally{N(f)}}async function w(e){let{git:t,newHeadSha:r,branchName:i,untrackedIncluded:a,signal:o}=e;o?.throwIfAborted(),a&&await T(t,o);let s=await O(t,o);try{i?await n(t,i,{createBranch:!0,startPoint:r,signal:o}):await u(t,r,`hard`,{signal:o})}catch(e){throw s&&await k(t,o),e}s&&await k(t,o)}async function T(e,t){let n=await s(e,{signal:t});n.length>0&&await f(e,{paths:n,signal:t})}async function E(e){let{git:t,branchName:n,newHeadSha:r,signal:i}=e;if(i?.throwIfAborted(),await g(t,`refs/heads/${n}`,r,{signal:i}),await o(t,{signal:i})===n){let e=await O(t,i);try{await u(t,r,`hard`,{signal:i})}catch(n){throw e&&await k(t,i),n}e&&await k(t,i)}}async function D(t){let{git:a,branch:s,rangeTo:l,newHeadSha:f,originalBranchSha:p,preserveSuffix:m=!0,signal:h}=t;h?.throwIfAborted();let _=await o(a,{signal:h})===s,v=[],y=f;if(m&&l!==p){let t=(await c(a,{format:`%H`,range:`${l}..${p}`,reverse:!0,signal:h})).trim().split(`
-`).filter(Boolean);if(t.length>0){let o=await O(a,h);try{await n(a,f,{detach:!0,signal:h});for(let n of t){h?.throwIfAborted();try{await r(a,n,{signal:h}),v.push(n)}catch(t){throw await i(a,{signal:h}).catch(()=>{}),new e(`CHERRY_PICK_CONFLICT`,`Could not preserve commit ${n.slice(0,8)} after rewriting the range. Cherry-pick aborted; no changes were made to the branch.`,{cause:t,detail:{conflictingCommit:n,successfullyCherryPicked:[...v]}})}}y=await d(a,`HEAD`,{signal:h})}finally{o&&await k(a,h)}}}if(await g(a,`refs/heads/${s}`,y,{signal:h}),_){let e=await O(a,h);try{await n(a,s,{signal:h}),await u(a,y,`hard`,{signal:h})}finally{e&&await k(a,h)}}return{finalTipSha:y,preservedSuffixShas:v}}async function O(e,t){return(await h(e,{signal:t})).trim()?(await m(e,{message:`compose backup`,includeUntracked:!0,signal:t}),!0):!1}async function k(e,t){try{await p(e,{signal:t})}catch{}}function A(e,t){let n=e.filter(e=>e.author!=null);if(n.length===0)return{author:void 0,coAuthors:[]};let r;if(typeof t==`function`)r=t(e);else if(t===`first-hunk`)r=n[0].author;else{let e=new Map;for(let t of n){let n=j(t.author),r=e.get(n);r?r.count++:e.set(n,{identity:t.author,count:1})}let t=0;for(let{identity:n,count:i}of e.values())i>t&&(r=n,t=i)}let i=new Map;for(let t of e){t.author&&i.set(j(t.author),t.author);for(let e of t.coAuthors??[])i.set(j(e),e)}let a=r?j(r):null,o=[];for(let[e,t]of i)e!==a&&o.push(t);return{author:r,coAuthors:o}}function j(e){return`${e.name.toLowerCase()}\0${e.email.toLowerCase()}`}function M(e,t){if(t.length===0)return e;let n=t.map(e=>`Co-authored-by: ${e.name} <${e.email}>`).join(`
-`);return`${e.trimEnd()}\n\n${n}\n`}function N(e){try{b.unlinkSync(e)}catch{}}function P(e,t){let n=e.split(`
+import{GitError as e}from"../errors/git.js";import{applyPatchToIndex as t,applyPatchToWorkdir as n,checkout as r,cherryPick as i,cherryPickAbort as a,commitTree as o,currentBranch as s,listUntracked as c,localeNeutralEnv as l,log as u,readTree as d,reset as f,revParse as p,stageAll as m,stashDrop as h,stashPop as g,stashPush as _,statusPorcelain as v,updateRef as y,writeTree as b}from"./port-dispatch.js";import{buildPatchForCommit as x}from"./utils/patch-builder.js";import{randomUUID as S}from"node:crypto";import*as C from"node:fs";import*as w from"node:os";import*as T from"node:path";async function E(n){let{git:r,baseSha:i,commits:a,hunks:s,signing:c,authorAttribution:l=`plurality`}=n,u=T.join(w.tmpdir(),`compose-idx-${S()}`),f=i,p=new Map,m=new Set;try{for(let n of a){let i=n.hunkIndices.map(t=>{let n=s.find(e=>e.index===t);if(!n)throw new e(`OPERATION_FAILED`,`Hunk index ${t} not found`);return n}),a=x(i.map(e=>m.has(e.diffHeader)?{...e,diffHeader:H(e.diffHeader,e.fileName)}:e));if(!a.trim())throw new e(`OPERATION_FAILED`,`Empty patch for commit: ${n.message}`);let h={GIT_INDEX_FILE:u};await d(r,f,{indexEnv:h});try{await t(r,a,{indexEnv:h})}catch(t){let r=t instanceof Error?t.message:String(t);throw new e(`OPERATION_FAILED`,`git apply failed for commit '${n.message.split(`
+`)[0]}': ${r}`,{cause:t})}for(let e of i)e.originalFileName&&e.diffHeader.includes(`rename from`)&&m.add(e.diffHeader);let g=await b(r,{indexEnv:h}),_=R(i,l),v=B(n.message,_.coAuthors),y=await o(r,g,[f],v,{signing:c,author:_.author});p.set(n.id,y),f=y}return{headSha:f,shaMap:p}}finally{V(u)}}async function D(e){let{git:t,newHeadSha:i,branchName:a,untrackedIncluded:o,stashLabel:s,leftoverPatch:c,leftoverPatchBranchOnly:l}=e;o&&await O(t);let u=s??j,d=await M(t,u),p=d==null?c:l;try{a?await r(t,a,{createBranch:!0,startPoint:i}):await f(t,i,`hard`),p&&await n(t,p)}catch(e){throw d!=null&&await P(t,d,u),e}if(d!=null){let e=await P(t,d,u);if(e.conflicted)return{stashConflict:{stashLabel:u,conflictedFiles:e.conflictedFiles}}}return{}}async function O(e){let t=await c(e);t.length>0&&await m(e,{paths:t})}async function k(e){let{git:t,branchName:r,newHeadSha:i,stashLabel:a,leftoverPatch:o,leftoverPatchBranchOnly:c}=e,l=await s(t)===r,u=a??j,d=l?await M(t,u):null,p;try{if(await y(t,`refs/heads/${r}`,i),l){let e=d==null?o:c;await f(t,i,`hard`),e&&await n(t,e)}}catch(e){throw d!=null&&await P(t,d,u),e}if(d!=null){let e=await P(t,d,u);e.conflicted&&(p={stashLabel:u,conflictedFiles:e.conflictedFiles})}return{stashConflict:p}}async function A(t){let{git:o,branch:c,rangeTo:l,newHeadSha:d,originalBranchSha:m,preserveSuffix:h=!0,stashLabel:g,leftoverPatch:_,leftoverPatchBranchOnly:v}=t,b=await s(o)===c,x=[],S=d,C=g??j,w=[];h&&l!==m&&(w=(await u(o,{format:`%H`,range:`${l}..${m}`,reverse:!0})).trim().split(`
+`).filter(Boolean));let T=b||w.length>0?await M(o,C):null,E;try{if(w.length>0){await r(o,d,{detach:!0});for(let t of w)try{await i(o,t),x.push(t)}catch(n){throw await a(o).catch(()=>{}),new e(`CHERRY_PICK_CONFLICT`,`Could not preserve commit ${t.slice(0,8)} after rewriting the range. Cherry-pick aborted; no changes were made to the branch.`,{cause:n,detail:{conflictingCommit:t,successfullyCherryPicked:[...x]}})}S=await p(o,`HEAD`)}if(await y(o,`refs/heads/${c}`,S),b){let e=T==null?_:v;await r(o,c),await f(o,S,`hard`),e&&await n(o,e)}}catch(e){throw T!=null&&await P(o,T,C),e}if(T!=null){let e=await P(o,T,C);e.conflicted&&(E={stashLabel:C,conflictedFiles:e.conflictedFiles})}return{finalTipSha:S,preservedSuffixShas:x,stashConflict:E}}const j=`compose backup`;async function M(e,t){if(!(await v(e)).trim())return null;await _(e,{message:t,includeUntracked:!0});try{let t=(await p(e,`stash@{0}`)).trim();return t.length>0?t:null}catch{return null}}async function N(e,t){if(!e.exec)return null;let n;try{n=await e.exec([`stash`,`list`,`--format=%H %gd`],{env:l})}catch{return null}for(let e of n.split(`
+`)){let n=e.indexOf(` `);if(!(n<0)&&e.slice(0,n)===t){let t=e.slice(n+1).trim();return t.length>0?t:null}}return null}async function P(e,t,n){let r=await N(e,t);if(r==null)return{conflicted:!0,conflictedFiles:[]};let i;try{return await g(e,{withIndex:!0,ref:r}),{conflicted:!1,conflictedFiles:[]}}catch(e){i=e}let a=await L(e);if(a.length>0)return{conflicted:!0,conflictedFiles:a};if(F(i)){let n=await N(e,t);if(n!=null)try{await h(e,n)}catch{}return{conflicted:!1,conflictedFiles:[]}}return{conflicted:!0,conflictedFiles:[]}}function F(e){let t=I(e);return t.includes(`already exists, no checkout`)||t.includes(`could not restore untracked files from stash`)}function I(e){if(e==null)return``;if(e instanceof Error){let t=e.stderr;return t!=null&&t.length>0?`${e.message}\n${t}`:e.message}return String(e)}async function L(e){try{let t=await v(e),n=[];for(let e of t.split(`
+`))/^(UU|AA|DD|AU|UA|UD|DU) /.test(e)&&n.push(e.slice(3).trim());return n}catch{return[]}}function R(e,t){let n=e.filter(e=>e.author!=null);if(n.length===0)return{author:void 0,coAuthors:[]};let r;if(typeof t==`function`)r=t(e);else if(t===`first-hunk`)r=n[0].author;else{let e=new Map;for(let t of n){let n=z(t.author),r=e.get(n);r?r.count++:e.set(n,{identity:t.author,count:1})}let t=0;for(let{identity:n,count:i}of e.values())i>t&&(r=n,t=i)}let i=new Map;for(let t of e){t.author&&i.set(z(t.author),t.author);for(let e of t.coAuthors??[])i.set(z(e),e)}let a=r?z(r):null,o=[];for(let[e,t]of i)e!==a&&o.push(t);return{author:r,coAuthors:o}}function z(e){return`${e.name.toLowerCase()}\0${e.email.toLowerCase()}`}function B(e,t){if(t.length===0)return e;let n=t.map(e=>`Co-authored-by: ${e.name} <${e.email}>`).join(`
+`);return`${e.trimEnd()}\n\n${n}\n`}function V(e){try{C.unlinkSync(e)}catch{}}function H(e,t){let n=e.split(`
 `),r=[];for(let e of n)e.startsWith(`diff --git `)?r.push(`diff --git a/${t} b/${t}`):e.startsWith(`similarity index`)||e.startsWith(`rename from`)||e.startsWith(`rename to`)||(e.startsWith(`--- a/`)?r.push(`--- a/${t}`):r.push(e));return r.join(`
-`)}export{w as applyCommitChain,D as applyRangeRewrite,E as applyRecompose,C as buildCommitChain};
+`)}export{D as applyCommitChain,A as applyRangeRewrite,k as applyRecompose,E as buildCommitChain};

package/dist/git/diff-collector.d.ts

@@ -36,16 +36,13 @@ interface CollectionResult {
   mergeBaseSha?: string;
   untrackedIncluded: boolean;
 }
-interface CollectOptions {
-  signal?: AbortSignal;
-}
-declare function collectFromSource(git: ComposeGitPort, source: ComposeSource, options?: CollectOptions): Promise<CollectionResult>;
+declare function collectFromSource(git: ComposeGitPort, source: ComposeSource): Promise<CollectionResult>;
 interface WorkingDiffOptions {
   includeUnstaged: boolean;
   includeUntracked: boolean;
 }
-declare function collectWorkingDiffs(git: ComposeGitPort, options: WorkingDiffOptions, signal?: AbortSignal): Promise<WorkingDiffResult>;
-declare function collectBranchDiffs(git: ComposeGitPort, branchName: string, baseBranch: string, signal?: AbortSignal): Promise<BranchDiffResult>;
+declare function collectWorkingDiffs(git: ComposeGitPort, options: WorkingDiffOptions): Promise<WorkingDiffResult>;
+declare function collectBranchDiffs(git: ComposeGitPort, branchName: string, baseBranch: string): Promise<BranchDiffResult>;
 /**
  * Collect hunks from a contiguous range of commits on a branch, tagging each
  * hunk with the author of the commit that introduced it.
@@ -59,8 +56,37 @@ declare function collectBranchDiffs(git: ComposeGitPort, branchName: string, bas
  * The snapshot records `branchSha = to` and `baseSha = from` so the apply
  * phase can re-verify the range state hasn't drifted.
  */
-declare function collectCommitRangeDiffs(git: ComposeGitPort, branchName: string, from: string, to: string, signal?: AbortSignal): Promise<BranchDiffResult>;
-declare function collectCommitsForSplit(git: ComposeGitPort, branchName: string, baseBranch: string, signal?: AbortSignal): Promise<SplitCollectionResult>;
+declare function collectCommitRangeDiffs(git: ComposeGitPort, branchName: string, from: string, to: string): Promise<BranchDiffResult>;
+/**
+ * Collect a commit-range plus selected portions of the working directory as one combined input.
+ *
+ * Range hunks come first (with per-commit author info preserved), then workdir hunks in stable
+ * order. The safety snapshot covers only the requested portions, so unstaged drift cannot block
+ * an apply that didn't include unstaged.
+ *
+ * Requires `to` to equal both the branch tip and HEAD — the workdir basis is `to`.
+ */
+declare function collectCommitRangeWithWorkdir(git: ComposeGitPort, branchName: string, from: string, to: string, options: {
+  includeStaged: boolean;
+  includeUnstaged: boolean;
+  includeUntracked: boolean;
+}): Promise<BranchDiffResult>;
+/**
+ * Build a tree representing HEAD plus the requested workdir portions, and return the
+ * workdir-only hunks (relative to HEAD) parsed from the same tree-to-tree diff.
+ *
+ * Each portion is staged into a temp index in dependency order: staged first (HEAD→index),
+ * then unstaged (index→worktree-tracked), then untracked (intent-to-add + content).
+ */
+declare function collectWorkdirPortionForRange(git: ComposeGitPort, headSha: string, options: {
+  includeStaged: boolean;
+  includeUnstaged: boolean;
+  includeUntracked: boolean;
+}): Promise<{
+  workdirHunks: ComposeHunk[];
+  finalTreeSha: string;
+}>;
+declare function collectCommitsForSplit(git: ComposeGitPort, branchName: string, baseBranch: string): Promise<SplitCollectionResult>;
 /**
  * Compute per-source content hashes alongside the authoritative combined hash.
  *
@@ -73,8 +99,9 @@ declare function collectCommitsForSplit(git: ComposeGitPort, branchName: string,
  * verify path with a generic error message.
  */
 declare function collectSourceHashes(git: ComposeGitPort, options: {
+  includeStaged?: boolean;
   includeUnstaged: boolean;
   includeUntracked: boolean;
-}, signal?: AbortSignal): Promise<SafetySnapshot['sourceHashes']>;
+}): Promise<SafetySnapshot['sourceHashes']>;
 //#endregion
-export { BranchCommitInfo, BranchDiffResult, CollectOptions, CollectionResult, SplitCollectionResult, WorkingDiffOptions, WorkingDiffResult, collectBranchDiffs, collectCommitRangeDiffs, collectCommitsForSplit, collectFromSource, collectSourceHashes, collectWorkingDiffs };
+export { BranchCommitInfo, BranchDiffResult, CollectionResult, SplitCollectionResult, WorkingDiffOptions, WorkingDiffResult, collectBranchDiffs, collectCommitRangeDiffs, collectCommitRangeWithWorkdir, collectCommitsForSplit, collectFromSource, collectSourceHashes, collectWorkdirPortionForRange, collectWorkingDiffs };