Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

40.1 KB
Raw Blame
import { randomUUID } from 'node:crypto';
import type { CindyMakeTaskOptions } from '../../shared/cindyMakeDoctor.js';
import type { CindyMakeMergeState, MakeFeatureMergePlan } from '../../shared/cindyMakeMerge.js';
import { mergeError, mergeWorktree } from './upstreamMerge.js';

export interface SavedUpstreamMerge {
  state: CindyMakeMergeState;
  sessionOwner?: string;
}
export function parseSavedUpstreamMerge(raw: string, userData: string): SavedUpstreamMerge {
  const saved = JSON.parse(raw) as SavedUpstreamMerge;
  const state = saved?.state;
  if (
    !state ||
    typeof state.id !== 'string' ||
    ![
      'fetching',
      'merging',
      'conflict',
      'resolving',
      'checking',
      'merged',
      'failed',
      'cancelled',
    ].includes(state.status) ||
    typeof state.ref !== 'string' ||
    typeof state.upstreamCommit !== 'string' ||
    (state.upstreamCommit !== '' && !/^[0-9a-f]{40}$/i.test(state.upstreamCommit)) ||
    (state.baselineTree !== undefined && !/^[0-9a-f]{40,64}$/i.test(state.baselineTree)) ||
    (state.strategy !== undefined && state.strategy !== 'rebase' && state.strategy !== 'combine') ||
    (state.strategy === 'combine' && !state.remote) ||
    (state.rebaseBase !== undefined && !/^[0-9a-f]{40}$/i.test(state.rebaseBase)) ||
    (state.rebaseReview !== undefined && typeof state.rebaseReview !== 'boolean') ||
    (state.needsInput !== undefined && typeof state.needsInput !== 'boolean') ||
    (state.reminded !== undefined && typeof state.reminded !== 'boolean') ||
    (state.missing !== undefined &&
      (!state.missing ||
        !Number.isSafeInteger(state.missing.count) ||
        state.missing.count < 1 ||
        !Array.isArray(state.missing.commits) ||
        state.missing.commits.length > 50 ||
        state.missing.commits.length > state.missing.count ||
        !state.missing.commits.every((commit) => /^[0-9a-f]{40}$/i.test(commit)) ||
        (state.missing.result !== undefined && !/^[0-9a-f]{40}$/i.test(state.missing.result)))) ||
    (state.cancellationRequested !== undefined &&
      typeof state.cancellationRequested !== 'boolean') ||
    (state.cleanupPending !== undefined && typeof state.cleanupPending !== 'boolean') ||
    (state.taskOwned !== undefined &&
      (typeof state.taskOwned !== 'boolean' || (state.taskOwned && !saved.sessionOwner))) ||
    (state.feature !== undefined && (!validFeaturePlan(state.feature) || !saved.sessionOwner)) ||
    (state.remote !== undefined &&
      (!state.remote ||
        typeof state.remote.base !== 'string' ||
        !/^[0-9a-f]{40}$/i.test(state.remote.base) ||
        (state.remote.commit !== undefined &&
          (typeof state.remote.commit !== 'string' ||
            !/^[0-9a-f]{40}$/i.test(state.remote.commit))) ||
        state.feature !== undefined)) ||
    (state.tree !== undefined && !/^[0-9a-f]{40,64}$/i.test(state.tree)) ||
    (state.baselineCommit !== undefined && !/^[0-9a-f]{40}$/i.test(state.baselineCommit)) ||
    (state.sessionId !== undefined &&
      (typeof state.sessionId !== 'string' ||
        !/^[a-zA-Z0-9-]{1,128}$/.test(state.sessionId) ||
        !saved.sessionOwner)) ||
    (saved.sessionOwner !== undefined && typeof saved.sessionOwner !== 'string')
  )
    throw mergeError('unavailable');
  mergeWorktree(userData, state.id);
  return saved;
}
function validFeaturePlan(feature: MakeFeatureMergePlan): boolean {
  const id = /^[a-zA-Z0-9-]{1,128}$/;
  const hash = /^[a-f0-9]{40,64}$/i;
  return (
    !!feature &&
    id.test(feature.runId) &&
    id.test(feature.taskSessionId) &&
    ['integrate', 'revert', 'reapply'].includes(feature.action) &&
    hash.test(feature.taskTree) &&
    (feature.mergeCommit === undefined || hash.test(feature.mergeCommit)) &&
    (feature.awaitingResolution === undefined || typeof feature.awaitingResolution === 'boolean') &&
    Array.isArray(feature.steps) &&
    feature.steps.length <= 10000 &&
    (feature.mergeCommit === undefined || feature.steps.length === 0) &&
    feature.steps.every((step) => !!step && hash.test(step.before) && hash.test(step.after)) &&
    Number.isInteger(feature.nextStep) &&
    feature.nextStep >= 0 &&
    feature.nextStep <= (feature.mergeCommit ? 1 : feature.steps.length)
  );
}
/**
 * A retained candidate whose resolver task is not there: it never opened, failed to
 * open, or was removed. Sync opens (or reopens) it, keeping the candidate's work.
 */
export function resumable(state: CindyMakeMergeState): boolean {
  return (
    !state.feature &&
    !state.ownedByAnotherAccount &&
    !state.cancellationRequested &&
    !!state.hasWorkspace &&
    ((!state.sessionId &&
      (state.status === 'conflict' || (state.status === 'failed' && state.error === 'startFailed'))) ||
      (state.status === 'failed' && state.error === 'unavailable'))
  );
}

export interface UpstreamMergeDependencies {
  read: () => SavedUpstreamMerge | undefined;
  write: (saved: SavedUpstreamMerge) => void;
  publish: (state: CindyMakeMergeState | undefined) => void;
  owner: () => string;
  hasWorkspace: (state: CindyMakeMergeState) => boolean;
  exclusive: <T>(run: () => Promise<T>) => Promise<T>;
  latest: () => Promise<{ ref: string; commit: string }>;
  prepare: (
    state: CindyMakeMergeState,
    publish: (state: CindyMakeMergeState) => Promise<void>,
    isCurrent: () => boolean,
  ) => Promise<CindyMakeMergeState>;
  apply: (
    state: CindyMakeMergeState,
    isCurrent: () => boolean,
    publish?: (state: CindyMakeMergeState) => Promise<void>,
    /** The user chose to use a result that does not carry every change. */
    options?: { acceptMissing?: boolean },
  ) => Promise<CindyMakeMergeState>;
  prepareFeature?: (
    state: CindyMakeMergeState,
    plan: MakeFeatureMergePlan,
    publish: (state: CindyMakeMergeState) => Promise<void>,
    isCurrent: () => boolean,
  ) => Promise<CindyMakeMergeState>;
  applied?: (state: CindyMakeMergeState, isCurrent: () => boolean) => Promise<void>;
  /** Combine the fork's personal version with this computer's (see `preparePersonalCombine`). */
  prepareCombine?: (
    state: CindyMakeMergeState,
    publish: (state: CindyMakeMergeState) => Promise<void>,
    isCurrent: () => boolean,
  ) => Promise<CindyMakeMergeState>;
  session: (
    state: CindyMakeMergeState,
    options: CindyMakeTaskOptions | undefined,
    bind: (id: string) => void,
    isCurrent: () => boolean,
  ) => Promise<string>;
  running: (sessionId: string) => boolean;
  /** Ask the resolver, in its own task, to put the changes the result lost back. */
  remind?: (state: CindyMakeMergeState, isCurrent: () => boolean) => Promise<void>;
  /** Wait between terminal observation and the provider's idle state. */
  sleep?: (milliseconds: number) => Promise<void>;
  refresh: () => Promise<void>;
  cleanup: (state: CindyMakeMergeState, isCurrent: () => boolean) => Promise<boolean>;
  cancel: (state: CindyMakeMergeState, isCurrent: () => boolean) => Promise<void>;
  /** Explicit build cancellation: stop its resolver before discarding the candidate. No Git lock held. */
  discard?: (state: CindyMakeMergeState, isCurrent: () => boolean) => Promise<boolean>;
}
const FINISH_IDLE_RETRY_DELAY_MS = 50;
const FINISH_IDLE_RETRY_COUNT = 20;
const errors = new Set([
  'busy',
  'dirty',
  'localMain',
  'localMainAhead',
  'unavailable',
  'gitFailed',
  'baselineChanged',
  'checksFailed',
  'interrupted',
  'startFailed',
  'cancelFailed',
]);

/** Device-local Git operation, with an account-bound resolution task. Never resumes writes on boot. */
export class UpstreamMergeController {
  private saved?: SavedUpstreamMerge;
  private active?: Promise<unknown>;
  private cancelling?: Promise<CindyMakeMergeState | undefined>;
  private interruption?: { operationId: string };
  private stopGeneration = 0;
  private acceptedTurn = 0;
  private readonly waiters = new Set<() => void>();
  constructor(private readonly deps: UpstreamMergeDependencies) {
    this.saved = deps.read();
    if (this.saved) {
      const state = this.saved.state;
      const recovered = {
        ...state,
        hasWorkspace: deps.hasWorkspace(state),
        ...(state.cancellationRequested
          ? { status: 'failed' as const, error: 'cancelFailed' as const }
          : ['fetching', 'merging', 'checking', 'resolving'].includes(state.status)
            ? { status: 'failed' as const, error: 'interrupted' as const }
            : {}),
      };
      if (recovered.status === 'failed' && recovered.error === 'interrupted')
        this.interruption = { operationId: state.id };
      // A completed merge removes its candidate worktree. Recompute this bit on
      // every restore so an older state file cannot keep the UI looking busy.
      if (
        recovered.status !== state.status ||
        recovered.error !== state.error ||
        recovered.hasWorkspace !== state.hasWorkspace
      )
        this.save(recovered);
    }
    this.status();
  }
  status(): CindyMakeMergeState | undefined {
    const state = this.saved?.state;
    const other = !!this.saved?.sessionOwner && this.saved.sessionOwner !== this.deps.owner();
    const projected = state
      ? { ...state, ...(other ? { sessionId: undefined, ownedByAnotherAccount: true } : {}) }
      : undefined;
    this.deps.publish(projected);
    for (const notify of this.waiters) notify();
    return projected;
  }
  /** A build stays alive across the dedicated task, but never across cancellation or restart. */
  waitForCompletion(
    operationId: string,
    signal: AbortSignal,
    observe: (state: CindyMakeMergeState) => void = () => {},
  ): Promise<CindyMakeMergeState> {
    const owner = this.deps.owner();
    const stopGeneration = this.stopGeneration;
    let interrupted = this.interruption?.operationId === operationId;
    return new Promise<CindyMakeMergeState>((resolve, reject) => {
      const finish = (state?: CindyMakeMergeState, error?: unknown) => {
        this.waiters.delete(check);
        signal.removeEventListener('abort', check);
        if (error) reject(error);
        else resolve(state!);
      };
      const check = () => {
        if (signal.aborted) return finish(undefined, signal.reason);
        const state = this.saved?.state;
        if (
          !state ||
          state.id !== operationId ||
          this.deps.owner() !== owner ||
          (this.saved?.sessionOwner && this.saved.sessionOwner !== owner)
        )
          return finish(undefined, mergeError('unavailable'));
        try {
          observe(state);
        } catch (error) {
          return finish(undefined, error);
        }
        // A deliberate later message may resume the resolver, never the stopped operation.
        interrupted ||=
          this.stopGeneration !== stopGeneration || this.interruption?.operationId === operationId;
        // Adoption and cleanup share the active operation. Do not resume its caller between them.
        if (this.active) return;
        if (interrupted) finish(undefined, mergeError('interrupted'));
        else if (state.status === 'merged') finish(state);
        else if (state.status === 'failed' || state.status === 'cancelled')
          finish(undefined, mergeError(state.error ?? 'interrupted'));
      };
      this.waiters.add(check);
      signal.addEventListener('abort', check, { once: true });
      check();
    }).catch(async (error) => {
      // Only an owning preparation/build Stop carries this reason. Shutdown and an ordinary
      // resolver-task Stop preserve the resolver for a later visit and keep the caller waiting.
      if (signal.aborted && (signal.reason as { code?: string })?.code === 'cancelled')
        await this.cancelBuild(operationId);
      throw error;
    });
  }
  isApplying(sessionId: string): boolean {
    return (
      this.saved?.state.sessionId === sessionId &&
      (this.saved.state.cancellationRequested ||
        this.saved.state.status === 'cancelled' ||
        this.saved.state.status === 'checking' ||
        (!!this.active &&
          (this.saved.state.status === 'merged' ||
            this.interruption?.operationId === this.saved.state.id)))
    );
  }
  private save(state: CindyMakeMergeState): void {
    // A finished combine is stored like an official update: older clients reject
    // `combine`, and nothing of it remains to resume.
    if (
      state.strategy === 'combine' &&
      (state.status === 'merged' || state.status === 'cancelled') &&
      !state.hasWorkspace &&
      !state.cleanupPending &&
      !state.cancellationRequested
    )
      state = { ...state, strategy: 'rebase' };
    // In-flight Git/session callbacks cannot erase a persisted Stop decision.
    if (
      this.saved?.state.id === state.id &&
      this.saved.state.cancellationRequested &&
      state.status !== 'cancelled'
    )
      state = { ...state, cancellationRequested: true };
    if (
      this.interruption?.operationId === state.id &&
      !state.cancellationRequested &&
      state.status !== 'cancelled'
    )
      state = { ...state, status: 'failed', error: 'interrupted' };
    const saved = { ...this.saved, state };
    // Persist before publishing or performing the next mutation.
    this.deps.write(saved);
    this.saved = saved;
    this.status();
  }
  private fail(error: unknown): void {
    const state = this.saved?.state;
    if (!state) return;
    const code = (error as { code?: string })?.code;
    // A failure says what is missing now, never an older list.
    const missing = (error as { missing?: CindyMakeMergeState['missing'] })?.missing;
    this.save({
      ...state,
      status: 'failed',
      hasWorkspace: this.deps.hasWorkspace(state),
      error: errors.has(code ?? '') ? (code as CindyMakeMergeState['error']) : 'gitFailed',
      missing,
    });
  }
  private async acceptResult(result: CindyMakeMergeState, isCurrent: () => boolean): Promise<void> {
    if (result.feature && result.status === 'merged') {
      // A crash after Git adoption must resume receipt persistence, not masquerade as fully complete.
      this.save({ ...result, status: 'checking' });
      if (!isCurrent()) throw mergeError('busy');
      await this.deps.applied?.(result, isCurrent);
    }
    this.save(result);
  }
  private async cleanupCompleted(state: CindyMakeMergeState): Promise<void> {
    const owner = this.deps.owner();
    const isCurrent = () =>
      this.saved?.state.id === state.id &&
      this.deps.owner() === owner &&
      (!this.saved.sessionOwner || this.saved.sessionOwner === owner) &&
      (!state.sessionId || !this.deps.running(state.sessionId));
    if (!isCurrent()) return;
    this.save({ ...state, cleanupPending: true });
    const cleaned = await this.deps.cleanup(state, isCurrent).catch(() => false);
    // Cleanup may be deferred (for example after a crash). Read the actual
    // worktree state before clearing the persisted flag.
    if (!isCurrent() || this.saved?.state.status !== 'merged') return;
    const hasWorkspace = this.deps.hasWorkspace(state);
    this.save({ ...this.saved.state, hasWorkspace, cleanupPending: !cleaned || undefined });
  }
  async finishPreviousCleanup(): Promise<void> {
    const state = this.saved?.state;
    if ((state?.feature || state?.taskOwned) && state.cancellationRequested) {
      await this.cancelBuild(state.id);
      return;
    }
    if (state?.status !== 'merged' || (!state.hasWorkspace && !state.cleanupPending)) return;
    await this.run(async () => {});
    if (this.saved?.state.cleanupPending || this.saved?.state.hasWorkspace)
      throw mergeError('dirty');
  }
  private async run(work: () => Promise<void>): Promise<CindyMakeMergeState | undefined> {
    if (this.active) {
      await this.active.catch(() => undefined);
      return this.status();
    }
    let started = false;
    const pending = Promise.resolve().then(async () => {
      await this.deps.exclusive(async () => {
        started = true;
        await work();
      });
      // Runtime shutdown uses the shared recycle queue, which may itself need
      // the project lock. Release Git exclusivity before awaiting that queue.
      const state = this.saved?.state;
      if (
        state?.status === 'merged' &&
        !state.cancellationRequested &&
        this.interruption?.operationId !== state.id &&
        (state.hasWorkspace || state.cleanupPending)
      )
        await this.cleanupCompleted(state);
    });
    this.active = pending;
    try {
      await pending;
    } catch (error) {
      if (!started) throw error;
      this.fail(error);
    } finally {
      this.active = undefined;
      for (const notify of this.waiters) notify();
    }
    return this.status();
  }
  async update(
    options?: CindyMakeTaskOptions,
    signal?: AbortSignal,
    /**
     * `target` pins the official version the caller already chose; `autoResolve`
     * opens the resolution task on conflict without another decision (the user's
     * Sync is that decision). Task-owned updates always resolve automatically.
     */
    extra: { target?: { ref: string; commit: string }; autoResolve?: boolean } = {},
  ): Promise<CindyMakeMergeState | undefined> {
    signal?.throwIfAborted();
    await this.finishPreviousCleanup();
    const owner = this.deps.owner();
    // Task preparation may only wait on or cancel the source update it actually started.
    if (
      signal &&
      (!owner ||
        this.active ||
        this.saved?.state.cancellationRequested ||
        (this.saved?.state.hasWorkspace && this.saved.state.status !== 'merged'))
    )
      throw mergeError('busy');
    let operationId: string | undefined;
    const markCancelled = () => {
      if (
        operationId &&
        this.saved?.state.id === operationId &&
        this.deps.owner() === owner &&
        (signal?.reason as { code?: string })?.code === 'cancelled'
      ) {
        try {
          this.save({ ...this.saved.state, cancellationRequested: true });
          this.interruption = { operationId };
        } catch {
          // The awaited cancellation path retries the durable decision.
        }
      }
    };
    try {
      const result = await this.run(async () => {
        // A request stopped while waiting for the Git lock owns no new operation.
        // Leave any previous result intact.
        if (signal && (signal.aborted || this.deps.owner() !== owner)) return;
        if (
          this.saved?.state.cancellationRequested ||
          (this.saved?.state.hasWorkspace && this.saved.state.status !== 'merged')
        )
          return;
        this.saved = {
          sessionOwner: owner || undefined,
          state: {
            id: randomUUID(),
            status: 'fetching',
            ref: '',
            upstreamCommit: '',
            // Sync and task preparation own their candidate: either may abandon it.
            ...(signal || (extra.autoResolve && owner) ? { taskOwned: true } : {}),
          },
        };
        this.save(this.saved.state);
        operationId = this.saved.state.id;
        signal?.addEventListener('abort', markCancelled, { once: true });
        markCancelled();
        signal?.throwIfAborted();
        const latest = extra.target ?? (await this.deps.latest());
        signal?.throwIfAborted();
        if (signal && this.deps.owner() !== owner) throw mergeError('busy');
        this.save({ ...this.saved!.state, ref: latest.ref, upstreamCommit: latest.commit });
        // An in-flight adoption may finish on Stop, but never under another account.
        const result = await this.deps.prepare(
          this.saved!.state,
          async (next) => this.save(next),
          () => !signal || this.deps.owner() === owner,
        );
        this.save(result);
        // Task preparation and Sync authorize their dedicated conflict task.
        if (
          (signal || extra.autoResolve) &&
          !signal?.aborted &&
          this.deps.owner() === owner &&
          result.status === 'conflict'
        )
          await this.createResolutionTask(options, owner, signal);
        await this.deps.refresh().catch(() => undefined);
      });
      if ((signal || extra.autoResolve) && !operationId) {
        signal?.throwIfAborted();
        throw mergeError('busy');
      }
      return result;
    } finally {
      signal?.removeEventListener('abort', markCancelled);
      if (
        operationId &&
        signal?.aborted &&
        (signal.reason as { code?: string })?.code === 'cancelled'
      )
        await this.cancelBuild(operationId);
    }
  }
  async resolve(
    options?: CindyMakeTaskOptions,
    operationId?: string,
  ): Promise<CindyMakeMergeState | undefined> {
    const owner = this.deps.owner();
    const stopGeneration = this.stopGeneration;
    if (operationId !== undefined && this.saved?.state.id !== operationId) throw mergeError('busy');
    if (this.saved?.state.status === 'cancelled' || this.saved?.state.cancellationRequested)
      throw mergeError('busy');
    if (this.saved?.sessionOwner && this.saved.sessionOwner !== owner) throw mergeError('busy');
    return this.run(async () => {
      if (this.deps.owner() !== owner) throw mergeError('busy');
      if (this.stopGeneration !== stopGeneration) return;
      if (this.saved?.state.feature && !this.saved.state.feature.awaitingResolution) {
        // Explicit native retry after an interrupted receipt/check. Opening a
        // resolver below still requires a new dispatched message to resume it.
        this.interruption = undefined;
        const isCurrent = () =>
          this.deps.owner() === owner && this.stopGeneration === stopGeneration;
        let result: CindyMakeMergeState;
        if (this.saved.state.error === 'baselineChanged' && this.deps.prepareFeature) {
          // Keep the old candidate and its task for inspection; retry against the changed personal source.
          const plan = { ...this.saved.state.feature, nextStep: 0, awaitingResolution: false };
          this.save({
            id: randomUUID(),
            status: 'merging',
            ref: 'personal',
            upstreamCommit: '',
            feature: plan,
          });
          result = await this.deps.prepareFeature(
            this.saved.state,
            plan,
            async (next) => this.save(next),
            isCurrent,
          );
        } else
          result = await this.deps.apply(this.saved.state, isCurrent, async (next) =>
            this.save(next),
          );
        await this.acceptResult(result, isCurrent);
        if (result.status === 'merged') return;
      }
      await this.createResolutionTask(options, owner);
    });
  }
  async cancel(operationId: string): Promise<CindyMakeMergeState | undefined> {
    const state = this.saved?.state;
    if (
      state?.id === operationId &&
      (state.feature || state.taskOwned) &&
      state.cancellationRequested
    )
      return this.cancelBuild(operationId);
    const owner = this.deps.owner();
    if (
      this.active ||
      !state ||
      state.id !== operationId ||
      state.feature ||
      state.sessionId ||
      !['conflict', 'failed', 'cancelled'].includes(state.status) ||
      (this.saved?.sessionOwner && this.saved.sessionOwner !== owner)
    )
      throw mergeError('busy');
    return this.run(async () => {
      const isCurrent = () => this.saved?.state.id === operationId && this.deps.owner() === owner;
      if (!isCurrent()) throw mergeError('busy');
      if (state.status === 'cancelled' && !state.hasWorkspace) return;
      this.save({ ...state, cancellationRequested: true });
      try {
        await this.deps.cancel(state, isCurrent);
      } catch {
        // Retain the decision and recovery entry if Git could not reclaim the candidate.
        throw mergeError('cancelFailed');
      }
      this.save({
        ...state,
        status: 'cancelled',
        hasWorkspace: false,
        cancellationRequested: undefined,
        error: undefined,
      });
      await this.deps.refresh().catch(() => undefined);
    });
  }
  /** Bound to task preparation, never used for an ordinary session Stop or app exit. */
  async cancelBuild(operationId: string): Promise<CindyMakeMergeState | undefined> {
    const state = this.saved?.state;
    const owner = this.deps.owner();
    if (
      !(state?.feature || state?.taskOwned) ||
      state.id !== operationId ||
      this.saved?.sessionOwner !== owner ||
      !this.deps.discard
    )
      throw mergeError('busy');
    if (this.cancelling) return this.cancelling;
    if (state.status === 'cancelled' && !state.hasWorkspace) return this.status();
    this.save({ ...state, cancellationRequested: true });
    this.interruption = { operationId };
    const isCurrent = () =>
      this.saved?.state.id === operationId &&
      this.saved.sessionOwner === owner &&
      this.deps.owner() === owner;
    const pending = (async () => {
      await this.active?.catch(() => undefined);
      if (!isCurrent()) throw mergeError('busy');
      try {
        if (!(await this.deps.discard!(this.saved!.state, isCurrent)) || !isCurrent())
          throw mergeError('cancelFailed');
        this.save({
          ...this.saved!.state,
          status: 'cancelled',
          hasWorkspace: false,
          cleanupPending: undefined,
          cancellationRequested: undefined,
          error: undefined,
        });
        await this.deps.refresh().catch(() => undefined);
        return this.status();
      } catch {
        if (isCurrent()) this.fail(mergeError('cancelFailed'));
        throw mergeError('cancelFailed');
      }
    })();
    this.cancelling = pending;
    try {
      return await pending;
    } finally {
      this.cancelling = undefined;
    }
  }
  async feature(
    plan: MakeFeatureMergePlan,
    options?: CindyMakeTaskOptions,
    signal?: AbortSignal,
  ): Promise<CindyMakeMergeState | undefined> {
    signal?.throwIfAborted();
    if (!validFeaturePlan(plan) || !this.deps.prepareFeature) throw mergeError('unavailable');
    await this.finishPreviousCleanup();
    const owner = this.deps.owner();
    if (
      !owner ||
      this.active ||
      this.saved?.state.cancellationRequested ||
      (this.saved?.state.hasWorkspace && this.saved.state.status !== 'merged')
    )
      throw mergeError('busy');
    let operationId: string | undefined;
    const markCancelled = () => {
      if (
        !operationId ||
        this.saved?.state.id !== operationId ||
        this.deps.owner() !== owner ||
        !signal?.aborted ||
        (signal.reason as { code?: string })?.code !== 'cancelled'
      )
        return;
      try {
        this.save({ ...this.saved.state, cancellationRequested: true });
        this.interruption = { operationId };
      } catch {
        // The awaited cancellation path retries persistence before discarding anything.
      }
    };
    try {
      const result = await this.run(async () => {
        // A cancelled request queued behind another Git operation owns no candidate.
        if (signal?.aborted) return;
        // Let an in-flight Git adoption finish recording its receipt so rollback
        // can undo it. Cancellation prevents resolver dispatch after this step.
        const isCurrent = () => owner === this.deps.owner();
        if (!isCurrent()) throw mergeError('busy');
        this.saved = {
          sessionOwner: owner,
          state: {
            id: randomUUID(),
            status: 'merging',
            ref: 'personal',
            upstreamCommit: '',
            feature: plan,
          },
        };
        this.save(this.saved.state);
        operationId = this.saved.state.id;
        signal?.addEventListener('abort', markCancelled, { once: true });
        markCancelled();
        const result = await this.deps.prepareFeature!(
          this.saved.state,
          plan,
          async (next) => this.save(next),
          isCurrent,
        );
        await this.acceptResult(result, isCurrent);
        if (
          result.status === 'conflict' &&
          isCurrent() &&
          !signal?.aborted &&
          !this.saved?.state.cancellationRequested
        )
          await this.createResolutionTask(options, owner, signal);
        await this.deps.refresh().catch(() => undefined);
      });
      if (!operationId) {
        signal?.throwIfAborted();
        throw mergeError('busy');
      }
      return result;
    } finally {
      signal?.removeEventListener('abort', markCancelled);
    }
  }
  /**
   * Combine the GitHub version `remote.commit` with this computer's personal
   * version. A conflict opens its resolution task when `autoResolve` (Sync);
   * otherwise it waits for the explicit resolve decision.
   */
  async combine(
    remote: { commit: string; base: string },
    options?: CindyMakeTaskOptions,
    autoResolve = false,
  ): Promise<CindyMakeMergeState | undefined> {
    const hash = /^[0-9a-f]{40}$/i;
    if (!hash.test(remote.commit) || !hash.test(remote.base) || !this.deps.prepareCombine)
      throw mergeError('unavailable');
    await this.finishPreviousCleanup();
    const owner = this.deps.owner();
    if (
      !owner ||
      this.active ||
      this.saved?.state.cancellationRequested ||
      (this.saved?.state.hasWorkspace && this.saved.state.status !== 'merged')
    )
      throw mergeError('busy');
    let started = false;
    const result = await this.run(async () => {
      if (
        this.deps.owner() !== owner ||
        this.saved?.state.cancellationRequested ||
        (this.saved?.state.hasWorkspace && this.saved.state.status !== 'merged')
      )
        return;
      this.saved = {
        sessionOwner: owner,
        state: {
          id: randomUUID(),
          status: 'merging',
          ref: 'github',
          upstreamCommit: remote.commit,
          remote: { base: remote.base, commit: remote.commit },
          ...(autoResolve ? { taskOwned: true } : {}),
        },
      };
      this.save(this.saved.state);
      started = true;
      const result = await this.deps.prepareCombine!(
        this.saved.state,
        async (next) => this.save(next),
        () => this.deps.owner() === owner,
      );
      this.save(result);
      if (autoResolve && result.status === 'conflict' && this.deps.owner() === owner)
        await this.createResolutionTask(options, owner);
      await this.deps.refresh().catch(() => undefined);
    });
    if (!started) throw mergeError('busy');
    return result;
  }
  /**
   * Give up a source operation that waits for its conflict (Sync's Abandon): stop its
   * resolver and discard the candidate. Nothing is adopted; both versions stay as they were.
   */
  async abandon(operationId: string): Promise<CindyMakeMergeState | undefined> {
    const state = this.saved?.state;
    const owner = this.deps.owner();
    // While its result is being checked or adopted, Abandon could no longer promise that
    // nothing changes; it waits until that settles.
    if (
      !state ||
      state.id !== operationId ||
      state.feature ||
      state.status === 'merged' ||
      state.status === 'cancelled' ||
      state.status === 'checking' ||
      this.active ||
      (this.saved?.sessionOwner && this.saved.sessionOwner !== owner)
    )
      throw mergeError('busy');
    if (!state.sessionId && !state.cancellationRequested && !state.taskOwned)
      return this.cancel(operationId);
    // Stopping a resolver needs the owning account; never persist a half-owned state.
    if (!owner || this.saved?.sessionOwner !== owner) throw mergeError('busy');
    if (!state.taskOwned) this.save({ ...state, taskOwned: true });
    return this.cancelBuild(operationId);
  }
  /**
   * Sync finishes a retained source operation before anything else: an Abandon that
   * could not finish is completed, a conflict without a task gets its resolver. A
   * candidate interrupted before its rebase ran waits for Abandon instead of an Agent
   * that cannot act; everything else is returned as it is for Sync to show.
   */
  async resumeForSync(options?: CindyMakeTaskOptions): Promise<CindyMakeMergeState | undefined> {
    const state = this.status();
    if (!state || state.feature || state.ownedByAnotherAccount) return state;
    if (state.cancellationRequested)
      return state.taskOwned ? this.cancelBuild(state.id) : this.cancel(state.id);
    if (resumable(state)) return this.resolve(options, state.id);
    return state;
  }
  /**
   * The user chose to use a checked result although some of their changes are not in
   * it (Sync's "use it anyway"). Both original versions stay in backup refs.
   */
  async acceptMissing(operationId: string): Promise<CindyMakeMergeState | undefined> {
    const state = this.saved?.state;
    const owner = this.deps.owner();
    if (
      this.active ||
      !owner ||
      !state ||
      state.id !== operationId ||
      state.feature ||
      state.status !== 'failed' ||
      state.error !== 'checksFailed' ||
      !state.missing ||
      !state.sessionId ||
      !state.hasWorkspace ||
      state.cancellationRequested ||
      this.saved?.sessionOwner !== owner ||
      this.deps.running(state.sessionId)
    )
      throw mergeError('busy');
    const sessionId = state.sessionId;
    return this.run(async () => {
      const isCurrent = () =>
        this.saved?.state.id === operationId &&
        !this.saved.state.cancellationRequested &&
        this.saved.sessionOwner === owner &&
        this.deps.owner() === owner &&
        !this.deps.running(sessionId);
      if (!isCurrent()) throw mergeError('busy');
      this.interruption = undefined;
      this.save({ ...state, status: 'checking', error: undefined });
      const result = await this.deps.apply(state, isCurrent, async (next) => this.save(next), {
        acceptMissing: true,
      });
      await this.acceptResult(result, isCurrent);
      await this.deps.refresh().catch(() => undefined);
    });
  }
  private async createResolutionTask(
    options: CindyMakeTaskOptions | undefined,
    owner: string,
    signal?: AbortSignal,
  ): Promise<void> {
    const state = this.saved?.state;
    if (!state?.hasWorkspace || ['merged', 'cancelled'].includes(state.status))
      throw mergeError('unavailable');
    const stopGeneration = this.stopGeneration;
    const isCurrent = () =>
      this.saved?.state.id === state.id &&
      this.deps.owner() === owner &&
      this.stopGeneration === stopGeneration &&
      !signal?.aborted &&
      !this.saved.state.cancellationRequested;
    const bind = (sessionId: string) => {
      if (!isCurrent()) throw mergeError('busy');
      this.saved = { ...this.saved!, sessionOwner: owner };
      this.save({
        ...this.saved.state,
        sessionId,
        // Merely opening a retained task does not accept another turn.
        ...(this.interruption?.operationId === state.id
          ? {}
          : { status: 'resolving' as const, error: undefined }),
      });
    };
    if (!isCurrent()) throw mergeError('busy');
    const id = await this.deps.session(state, options, bind, isCurrent);
    bind(id);
  }
  async finish(sessionId: string): Promise<void> {
    const turn = this.acceptedTurn;
    if (this.active && this.saved?.state.sessionId === sessionId)
      await this.active.catch(() => undefined);
    const state = this.saved?.state;
    if (
      this.active ||
      !state ||
      state.sessionId !== sessionId ||
      state.status === 'merged' ||
      state.status === 'cancelled' ||
      state.cancellationRequested ||
      this.interruption?.operationId === state.id ||
      this.acceptedTurn !== turn ||
      this.saved?.sessionOwner !== this.deps.owner()
    )
      return;
    // Providers may retire their running flag after synchronous done listeners return.
    await Promise.resolve();
    const owner = this.deps.owner();
    const isOwned = () =>
      this.saved?.state.id === state.id &&
      !this.saved.state.cancellationRequested &&
      this.interruption?.operationId !== state.id &&
      this.acceptedTurn === turn &&
      this.saved.sessionOwner === owner &&
      this.deps.owner() === owner;
    const isCurrent = () => isOwned() && !this.deps.running(sessionId);
    const sleep =
      this.deps.sleep ??
      ((milliseconds: number) =>
        new Promise<void>((resolve) => {
          const timer = setTimeout(resolve, milliseconds);
          (timer as unknown as { unref?: () => void }).unref?.();
        }));
    // A successful terminal event can reach this hook before the provider has
    // retired its running flag. Keep the candidate untouched while waiting for
    // that transition, but bound the wait so a genuinely stuck session cannot
    // hold the merge operation forever.
    for (let attempt = 0; attempt < FINISH_IDLE_RETRY_COUNT; attempt += 1) {
      if (!isOwned()) return;
      if (!this.deps.running(sessionId)) break;
      await sleep(FINISH_IDLE_RETRY_DELAY_MS);
    }
    if (!isOwned()) return;
    if (!isCurrent()) {
      this.fail(mergeError('busy'));
      return;
    }
    await this.run(async () => {
      if (!isCurrent()) return;
      this.save({ ...state, status: 'checking', error: undefined });
      const canFinishAdoption = () =>
        this.saved?.state.cancellationRequested
          ? this.saved.state.id === state.id &&
            this.saved.sessionOwner === owner &&
            this.deps.owner() === owner &&
            !this.deps.running(sessionId)
          : isCurrent();
      let result: CindyMakeMergeState;
      try {
        result = await this.deps.apply(state, canFinishAdoption, async (next) => this.save(next));
      } catch (error) {
        const missing = (error as { missing?: CindyMakeMergeState['missing'] })?.missing;
        // The result lost changes: the resolver is asked once, in its task, to put them back.
        if (!missing || state.reminded || !this.deps.remind || !isCurrent()) throw error;
        this.save({ ...state, status: 'resolving', missing, reminded: true, error: undefined });
        await this.deps.remind(this.saved!.state, isCurrent);
        return;
      }
      await this.acceptResult(result, canFinishAdoption);
      if (result.feature && result.status === 'conflict' && isCurrent()) {
        // Unresolved files from this turn are not a new conflict. Stop waiting
        // and retain the task instead of repeatedly spawning another resolver.
        if (!state.feature || result.feature.nextStep <= state.feature.nextStep)
          throw mergeError('checksFailed');
        // Only a later delta continues automatically, in the same task/worktree.
        await this.createResolutionTask(undefined, owner);
      }
      await this.deps.refresh().catch(() => undefined);
    });
  }
  async interrupt(sessionId: string): Promise<void> {
    const state = this.saved?.state;
    if (
      !state ||
      state.sessionId !== sessionId ||
      this.saved?.sessionOwner !== this.deps.owner() ||
      state.cancellationRequested ||
      state.status === 'cancelled' ||
      state.status === 'merged'
    )
      return;
    const interruption = { operationId: state.id };
    this.interruption = interruption;
    this.stopGeneration += 1;
    this.fail(mergeError('interrupted'));
    await this.active?.catch(() => undefined);
    if (
      this.interruption !== interruption ||
      this.saved?.state.sessionId !== sessionId ||
      this.saved.sessionOwner !== this.deps.owner() ||
      this.saved.state.cancellationRequested ||
      this.saved.state.status === 'cancelled' ||
      this.saved.state.status === 'merged'
    )
      return;
    this.fail(mergeError('interrupted'));
  }
  /** Capture before async dispatch; a pre-Stop acceptance cannot resume the task. */
  prepareTurn(sessionId: string): () => void {
    const operationId = this.saved?.state.id;
    const owner = this.deps.owner();
    const stopGeneration = this.stopGeneration;
    let accepted = false;
    return () => {
      const state = this.saved?.state;
      if (
        accepted ||
        !state ||
        state.id !== operationId ||
        this.stopGeneration !== stopGeneration ||
        !state.hasWorkspace ||
        state.status === 'merged' ||
        state.status === 'cancelled' ||
        state.cancellationRequested ||
        state.sessionId !== sessionId ||
        this.saved?.sessionOwner !== owner ||
        this.deps.owner() !== owner
      )
        return;
      accepted = true;
      this.acceptedTurn += 1;
      this.interruption = undefined;
      // The user answered the resolver, or continued it after an interruption or a failed check.
      if (
        (state.status === 'failed' && state.error === 'interrupted') ||
        state.needsInput ||
        (state.status === 'failed' && state.missing)
      )
        this.save({
          ...state,
          status: 'resolving',
          error: undefined,
          needsInput: undefined,
          missing: undefined,
        });
    };
  }
}