@fluado/enmetu 0.0.0-stage → 0.1.0

package/dist/commit/commitLocalChangesController.js

@@ -0,0 +1,358 @@
+import { EnmetuError, GitCommandError } from '../contracts/errors.js';
+import { withLastMove } from '../core/commit/commitMemory.js';
+import { gitBoolean } from '../core/commit/commitMessage.js';
+import { repairStaleIndexController } from './repairStaleIndexController.js';
+import { stageGuardedChanges } from './stageGuardedChanges.js';
+/** An unchanged tree a hook rejected is offered to the hooks again after this long (design 12.7). */
+export const HOOK_RETRY_MS = 600000;
+/**
+ * Controller: enmetu's commit without touching the person's index (design
+ * 12.7, Decisions 72 to 74, 80, 81).
+ *
+ * 1. before = fs.identity(realIndex), read first, so the staged-selection
+ *    verdict below still holds when the identity is unchanged under the lock.
+ *    Staged selection: git.hasStagedChanges() on the real index. When it
+ *    differs and memory.lastMove is set, repairStaleIndexController first
+ *    (Decision 98): moved, repaired or reverted (Decision 108) forgets lastMove; repaired reads
+ *    before and the verdict again, so a stale index is never taken for a
+ *    person's selection. "wait"
+ *    without a reached cap returns waiting PARTIAL_SELECTION_STAGED; a reached
+ *    cap logs SELECTION_WAIT_ENDED and goes on; "commit" goes on.
+ * 2. Build: parent = git.headCommit(); fs.copy(realIndex, commit index);
+ *    committer.seedFrom(parent); stageGuardedChanges on the commit index.
+ *    Nothing staged returns nothing.
+ * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing;
+ *    equal to memory.rejection.tree within HOOK_RETRY_MS returns waiting
+ *    COMMIT_HOOK_REJECTED without running a hook.
+ * 4. commitHooks: pre-commit on the commit index (rejected, timed out or
+ *    killed: HOOK_REJECTED, waiting, rejection remembered); then re-stage and
+ *    write the tree again, so a formatter's rewrite is in this commit. The
+ *    message is commitSubject plus a newline, with or without hooks; the
+ *    message hooks do not run (Decision 80). The re-stage logs through
+ *    residueLogger: its EXCLUDED lines repeat the first build's.
+ * 5. commit = committer.commitTree({ tree, parent, message, sign: gitBoolean(commit.gpgSign) }).
+ * 6. Critical section: indexLock.acquire(commit) (false: busy);
+ *    6.1 repositoryState() with an operation: release, paused; HEAD naming
+ *    anything but input.branchRef: release, busy (Decision 121);
+ *    6.2 fs.identity(realIndex) differing from before: release, busy;
+ *    6.3 indexLock.install(commit index);
+ *    6.4 writer.updateRef(input.branchRef, commit, parent) (a mismatch:
+ *    restore, release, COMMIT_DISCARDED, busy; any other throw: restore,
+ *    release, rethrow);
+ *    6.4b HEAD naming input.branchRef, or else resolving to the commit, keeps
+ *    it; otherwise writer.updateRef(input.branchRef, parent, commit),
+ *    restore, COMMIT_DISCARDED, busy (a roll-back failing with GIT_FAILED
+ *    restores and returns busy the same way; any other throw restores and
+ *    rethrows); release.
+ * 7. COMMITTED; with hooks: when realHooks.hookExists says post-index-change
+ *    or post-commit exists, a build with residueLogger before the hooks;
+ *    post-index-change "0 0" and post-commit on the real index (git ignores
+ *    both exit codes, so does enmetu); then, only when such a hook exists and
+ *    the build before found nothing uncommitted, a fresh build whose tree,
+ *    when it differs from the commit's, becomes residueTree (Decision 90).
+ */
+export async function commitLocalChangesController(input, deps) {
+    const { cycleId } = input;
+    const { settings } = deps;
+    const now = deps.clock.now();
+    // --- Step 1: identity first, then the person's staged selection ---
+    let memory = input.memory;
+    let before = await deps.fs.identity(settings.realIndex);
+    let staged = await deps.git.hasStagedChanges();
+    if (staged && memory.lastMove !== null) {
+        const repair = await repairStaleIndexController({ cycleId, lastMove: memory.lastMove, before }, deps);
+        // reverted is forgotten too, so its STAGED_REVERT line comes once (Decision 108).
+        if (repair.kind === 'moved' ||
+            repair.kind === 'repaired' ||
+            repair.kind === 'reverted') {
+            memory = withLastMove(memory, null);
+        }
+        if (repair.kind === 'repaired') {
+            before = await deps.fs.identity(settings.realIndex);
+            staged = await deps.git.hasStagedChanges();
+        }
+    }
+    let since = null;
+    if (staged) {
+        if (settings.stagedSelection === 'wait') {
+            since = memory.stagedSelectionSince ?? now;
+            const cap = settings.stagedSelectionMaxWaitMs;
+            if (cap === null || now - since < cap) {
+                return {
+                    kind: 'waiting',
+                    reason: 'PARTIAL_SELECTION_STAGED',
+                    memory: rememberSince(memory, since),
+                };
+            }
+            deps.logger.log({
+                level: 'WARN',
+                code: 'SELECTION_WAIT_ENDED',
+                message: `a staged selection waited ${cap} ms, the configured cap; committing everything, the selection included`,
+                cycleId,
+            });
+        }
+    }
+    const unchanged = rememberSince(memory, since);
+    // --- Step 2: build on the commit index, seeded from HEAD ---
+    const parent = await deps.git.headCommit();
+    if (parent === null) {
+        // The preflight refuses an unborn HEAD; this guards the type.
+        throw new EnmetuError('HEAD is unborn; there is nothing to commit onto', 'HEAD_UNBORN', cycleId);
+    }
+    if (!(await build(parent, cycleId, deps.logger, deps))) {
+        return { kind: 'nothing', memory: unchanged };
+    }
+    // --- Step 3: trees enmetu already knows ---
+    let tree = await deps.commitIndex.committer.writeTree();
+    if (tree === memory.residueTree) {
+        return { kind: 'nothing', memory: unchanged };
+    }
+    const rejection = memory.rejection;
+    if (rejection !== null &&
+        tree === rejection.tree &&
+        now - rejection.at < HOOK_RETRY_MS) {
+        return {
+            kind: 'waiting',
+            reason: 'COMMIT_HOOK_REJECTED',
+            memory: unchanged,
+        };
+    }
+    // --- Step 4: pre-commit on the commit index, then re-stage its rewrites ---
+    if (settings.commitHooks) {
+        const preCommit = await deps.commitIndex.committer.runHook('pre-commit', []);
+        if (preCommit.kind === 'rejected') {
+            deps.logger.log({
+                level: 'WARN',
+                code: 'HOOK_REJECTED',
+                message: `pre-commit rejected the commit (${firstLine(preCommit.detail)}); enmetu offers it again when the files change, or after ${HOOK_RETRY_MS} ms`,
+                cycleId,
+            });
+            return {
+                kind: 'waiting',
+                reason: 'COMMIT_HOOK_REJECTED',
+                memory: {
+                    stagedSelectionSince: since,
+                    rejection: { tree, at: now },
+                    residueTree: memory.residueTree,
+                    lastMove: memory.lastMove,
+                },
+            };
+        }
+        const restaged = await stageGuardedChanges({ cycleId }, {
+            git: deps.commitIndex.reader,
+            writer: deps.commitIndex.writer,
+            logger: deps.residueLogger,
+            skipJsonCheck: settings.skipJsonCheck,
+        });
+        if (!restaged.staged) {
+            return { kind: 'nothing', memory: unchanged };
+        }
+        tree = await deps.commitIndex.committer.writeTree();
+    }
+    // --- Step 5: the commit object; HEAD is its only parent, never MERGE_HEAD ---
+    // The subject is the whole message: no path ever reaches it (D1).
+    const commit = await deps.commitIndex.committer.commitTree({
+        tree,
+        parent,
+        message: `${settings.commitSubject}\n`,
+        sign: gitBoolean(await deps.git.configValue('commit.gpgSign')),
+    });
+    // --- Step 6: critical section under git's own index.lock ---
+    const swap = await installAndSwap(commit, parent, before, input, deps);
+    if (swap !== 'committed') {
+        return swap === 'busy'
+            ? { kind: 'busy', memory: unchanged }
+            : { kind: 'paused', reason: 'FOREIGN_OPERATION', memory: unchanged };
+    }
+    // --- Step 7: after the lock ---
+    deps.logger.log({
+        level: 'INFO',
+        code: 'COMMITTED',
+        message: 'local changes',
+        cycleId,
+    });
+    let residueTree = null;
+    if (settings.commitHooks) {
+        residueTree = await runPostCommitHooks(commit, tree, cycleId, deps);
+    }
+    return {
+        kind: 'committed',
+        memory: {
+            stagedSelectionSince: null,
+            rejection: null,
+            residueTree,
+            lastMove: { from: parent, to: commit },
+        },
+    };
+}
+/**
+ * Step 7 with hooks: post-index-change and post-commit on the real index, and
+ * the residue they leave (Decision 90). A residue is built only when one of
+ * them exists, so a repository without such hooks never mistakes a person's
+ * write for hook output. A build before the
+ * hooks tells what was already uncommitted: anything there (a person's write
+ * since the commit's build) means no residue at all, so the next cycle
+ * commits that write together with whatever the hooks wrote, and the cycle
+ * after it finds the residue alone.
+ */
+async function runPostCommitHooks(commit, tree, cycleId, deps) {
+    const mayWrite = (await deps.realHooks.hookExists('post-index-change')) ||
+        (await deps.realHooks.hookExists('post-commit'));
+    const pendingBefore = mayWrite && (await build(commit, cycleId, deps.residueLogger, deps));
+    // Both run through `git hook run --ignore-missing` whatever hookExists
+    // said, so what runs is git's decision alone; git ignores both exit codes,
+    // and so does enmetu.
+    await deps.realHooks.runHook('post-index-change', ['0', '0']);
+    await deps.realHooks.runHook('post-commit', []);
+    if (!mayWrite || pendingBefore) {
+        return null;
+    }
+    if (!(await build(commit, cycleId, deps.residueLogger, deps))) {
+        return null;
+    }
+    const residue = await deps.commitIndex.committer.writeTree();
+    return residue === tree ? null : residue;
+}
+/**
+ * Step 2 of the chain: copy the real index (git's stat data and skip-worktree
+ * bits, so add -A does not re-hash every file), seed it with the commit's
+ * tree, stage the guarded working tree. true when anything is staged.
+ */
+async function build(seed, cycleId, logger, deps) {
+    const { commitIndex } = deps;
+    if (!(await deps.fs.copy(deps.settings.realIndex, commitIndex.path))) {
+        // No real index (git reads a missing index like an empty one): a leftover commit index must
+        // not lend its stat data.
+        await deps.fs.remove(commitIndex.path);
+    }
+    await commitIndex.committer.seedFrom(seed);
+    const { staged } = await stageGuardedChanges({ cycleId }, {
+        git: commitIndex.reader,
+        writer: commitIndex.writer,
+        logger,
+        skipJsonCheck: deps.settings.skipJsonCheck,
+    });
+    return staged;
+}
+/**
+ * Step 6: under index.lock, in this order (Decisions 72, 81, 121):
+ *
+ * 6.1 repositoryState(): an operation pauses; HEAD naming anything but
+ *     branchRef (a person's git switch -c or --detach, which git lets through
+ *     a held index.lock) is busy, nothing installed.
+ * 6.2 The real index's identity still equals before, else busy.
+ * 6.3 Install the commit index, so a git commit that reads enmetu's branch
+ *     also reads enmetu's index.
+ * 6.4 Compare-and-swap of branchRef, not HEAD: a swap through HEAD would
+ *     follow a switch made after 6.1 onto the person's branch.
+ * 6.4b HEAD still names branchRef, or resolves to the commit (a branch
+ *     created or a detach made after the swap carries the commit along);
+ *     otherwise the swap is undone by compare-and-swap and the index restored.
+ *
+ * The lock is released on every path.
+ */
+async function installAndSwap(commit, parent, before, input, deps) {
+    const { cycleId, branchRef } = input;
+    if (!(await deps.indexLock.acquire(commit))) {
+        return 'busy';
+    }
+    let installing = false;
+    let settled = false;
+    try {
+        // --- 6.1 ---
+        const state = await deps.git.repositoryState();
+        if (state.operation !== null) {
+            return 'paused';
+        }
+        if (state.branchRef !== branchRef) {
+            return 'busy';
+        }
+        // --- 6.2: a write of a person's git to the real index since step 1
+        // replaced the file; installing over it would discard what they staged ---
+        if ((await deps.fs.identity(deps.settings.realIndex)) !== before) {
+            return 'busy';
+        }
+        // --- 6.3 ---
+        installing = true;
+        await deps.indexLock.install(deps.commitIndex.path);
+        // --- 6.4 ---
+        try {
+            await deps.writer.updateRef(branchRef, commit, parent);
+        }
+        catch (error) {
+            settled = true;
+            await deps.indexLock.restore();
+            if (error instanceof GitCommandError && error.code === 'GIT_FAILED') {
+                deps.logger.log({
+                    level: 'INFO',
+                    code: 'COMMIT_DISCARDED',
+                    message: 'a concurrent commit moved HEAD first; enmetu discards its commit and commits again on a later cycle',
+                    cycleId,
+                });
+                return 'busy';
+            }
+            throw error;
+        }
+        // From here the branch holds the commit and the installed index matches
+        // it; only a roll-back puts the person's index back, so a failed read
+        // below never leaves the index behind the branch.
+        settled = true;
+        // --- 6.4b ---
+        if (await headStillOnCommit(branchRef, commit, deps.git)) {
+            return 'committed';
+        }
+        await rollBack(branchRef, commit, parent, cycleId, deps);
+        return 'busy';
+    }
+    catch (error) {
+        if (installing && !settled) {
+            await deps.indexLock.restore();
+        }
+        throw error;
+    }
+    finally {
+        await deps.indexLock.release();
+    }
+}
+/** 6.4b: HEAD names branchRef, or, asked only when it does not, resolves to the commit. */
+async function headStillOnCommit(branchRef, commit, git) {
+    if ((await git.repositoryState()).branchRef === branchRef) {
+        return true;
+    }
+    return (await git.headCommit()) === commit;
+}
+/**
+ * 6.4b's compensation: branchRef back from the commit to its parent by
+ * compare-and-swap, then the person's index. A roll-back git refuses
+ * (GIT_FAILED: another command moved the branch after the swap) leaves the
+ * branch where that command put it; any other throw restores and rethrows.
+ */
+async function rollBack(branchRef, commit, parent, cycleId, deps) {
+    try {
+        await deps.writer.updateRef(branchRef, parent, commit);
+    }
+    catch (error) {
+        if (!(error instanceof GitCommandError && error.code === 'GIT_FAILED')) {
+            await deps.indexLock.restore();
+            throw error;
+        }
+    }
+    await deps.indexLock.restore();
+    deps.logger.log({
+        level: 'INFO',
+        code: 'COMMIT_DISCARDED',
+        message: `HEAD left ${branchRef} while enmetu moved it to its commit (a git switch of yours, most likely); enmetu put ${branchRef} and the index back and commits again on a later cycle`,
+        cycleId,
+    });
+}
+function rememberSince(memory, since) {
+    return {
+        stagedSelectionSince: since,
+        rejection: memory.rejection,
+        residueTree: memory.residueTree,
+        lastMove: memory.lastMove,
+    };
+}
+function firstLine(text) {
+    return (text.trim().split('\n')[0] ?? '').trim();
+}

package/dist/commit/gitIndexLock.d.ts

@@ -0,0 +1,36 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IGitIndexLock, StaleIndexLock } from '../contracts/IGitIndexLock.js';
+import type { IProcessHost } from '../contracts/IProcessHost.js';
+/** index.lock's content while enmetu holds it: `${INDEX_LOCK_MARKER}<pid>, commit <commit>\n`. */
+export declare const INDEX_LOCK_MARKER = "enmetu index lock, pid ";
+/** The person's index, kept under a second name while enmetu's commit index is installed. */
+export declare const INDEX_BEFORE_FILE = "index.before";
+/**
+ * Service: <gitDir>/index.lock (design 12.7, Decision 81).
+ * acquire(commit) is createExclusive(index.lock, the marker with pid and
+ * commit). install(prepared) removes a leftover <stateDir>/index.before, links
+ * <gitDir>/index to it (no link when there is no real index), then renames the
+ * prepared index over <gitDir>/index. restore() renames index.before back over
+ * <gitDir>/index. release() removes index.before, then the lock, and only when
+ * this instance holds it. releaseStale(head) reads the lock: not the marker, or
+ * a live pid: none. Otherwise HEAD equal to the marker's commit means the
+ * install happened before the crash (it precedes the swap): index.before is
+ * removed, kept. Any other HEAD: index.before, when present, is renamed back,
+ * restored. Then the lock is removed.
+ */
+export declare class GitIndexLock implements IGitIndexLock {
+    private readonly fs;
+    private readonly processHost;
+    private readonly gitDir;
+    private readonly stateDir;
+    private held;
+    constructor(fs: IFileSystem, processHost: IProcessHost, gitDir: string, stateDir: string);
+    acquire(commit: string): Promise<boolean>;
+    install(preparedIndex: string): Promise<void>;
+    restore(): Promise<void>;
+    release(): Promise<void>;
+    releaseStale(head: string | null): Promise<StaleIndexLock>;
+    private lockPath;
+    private indexPath;
+    private beforePath;
+}

package/dist/commit/gitIndexLock.js

@@ -0,0 +1,90 @@
+import { join } from 'node:path';
+/** index.lock's content while enmetu holds it: `${INDEX_LOCK_MARKER}<pid>, commit <commit>\n`. */
+export const INDEX_LOCK_MARKER = 'enmetu index lock, pid ';
+/** The person's index, kept under a second name while enmetu's commit index is installed. */
+export const INDEX_BEFORE_FILE = 'index.before';
+const MARKER_LINE = /^enmetu index lock, pid ([0-9]+), commit (\S+)\n?$/;
+/**
+ * Service: <gitDir>/index.lock (design 12.7, Decision 81).
+ * acquire(commit) is createExclusive(index.lock, the marker with pid and
+ * commit). install(prepared) removes a leftover <stateDir>/index.before, links
+ * <gitDir>/index to it (no link when there is no real index), then renames the
+ * prepared index over <gitDir>/index. restore() renames index.before back over
+ * <gitDir>/index. release() removes index.before, then the lock, and only when
+ * this instance holds it. releaseStale(head) reads the lock: not the marker, or
+ * a live pid: none. Otherwise HEAD equal to the marker's commit means the
+ * install happened before the crash (it precedes the swap): index.before is
+ * removed, kept. Any other HEAD: index.before, when present, is renamed back,
+ * restored. Then the lock is removed.
+ */
+export class GitIndexLock {
+    fs;
+    processHost;
+    gitDir;
+    stateDir;
+    held = false;
+    constructor(fs, processHost, gitDir, stateDir) {
+        this.fs = fs;
+        this.processHost = processHost;
+        this.gitDir = gitDir;
+        this.stateDir = stateDir;
+    }
+    async acquire(commit) {
+        const created = await this.fs.createExclusive(this.lockPath(), `${INDEX_LOCK_MARKER}${this.processHost.pid}, commit ${commit}\n`);
+        this.held = created;
+        return created;
+    }
+    async install(preparedIndex) {
+        // A leftover from a section that ended without release would make link(2)
+        // fail with EEXIST.
+        await this.fs.remove(this.beforePath());
+        // false: the repository has no index yet (git reads a missing index like an empty one), so
+        // there is nothing of the person's to keep.
+        await this.fs.link(this.indexPath(), this.beforePath());
+        await this.fs.rename(preparedIndex, this.indexPath());
+    }
+    async restore() {
+        await this.fs.rename(this.beforePath(), this.indexPath());
+    }
+    async release() {
+        if (!this.held) {
+            return;
+        }
+        await this.fs.remove(this.beforePath());
+        await this.fs.remove(this.lockPath());
+        this.held = false;
+    }
+    async releaseStale(head) {
+        const content = await this.fs.readText(this.lockPath());
+        if (content === null) {
+            return { kind: 'none' };
+        }
+        const match = MARKER_LINE.exec(content);
+        const pid = match?.[1];
+        const commit = match?.[2];
+        if (pid === undefined || commit === undefined) {
+            return { kind: 'none' };
+        }
+        if (this.processHost.isAlive(Number(pid))) {
+            return { kind: 'none' };
+        }
+        if (head === commit) {
+            await this.fs.remove(this.beforePath());
+            await this.fs.remove(this.lockPath());
+            return { kind: 'released', index: 'kept' };
+        }
+        // false when the crash came before the link: nothing was installed.
+        await this.fs.rename(this.beforePath(), this.indexPath());
+        await this.fs.remove(this.lockPath());
+        return { kind: 'released', index: 'restored' };
+    }
+    lockPath() {
+        return join(this.gitDir, 'index.lock');
+    }
+    indexPath() {
+        return join(this.gitDir, 'index');
+    }
+    beforePath() {
+        return join(this.stateDir, INDEX_BEFORE_FILE);
+    }
+}

package/dist/commit/repairStaleIndexController.d.ts

@@ -0,0 +1,90 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IGitIndexLock } from '../contracts/IGitIndexLock.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { HeadMove } from '../contracts/syncTypes.js';
+/** At most this many repaired paths are named in the log line; the count is always exact. */
+export declare const MAX_REPAIRED_PATHS_LOGGED = 20;
+export interface RepairStaleIndexInput {
+    readonly cycleId: string;
+    readonly lastMove: HeadMove;
+    /** fs.identity(realIndex), read before the staged paths, so an unchanged identity under the lock means they still hold. */
+    readonly before: string | null;
+}
+export interface RepairStaleIndexDeps {
+    /** The real index and HEAD. */
+    readonly git: IGitReader;
+    readonly commitIndex: {
+        /** Behind HaltGuardGitWriter; its unstage sets entries back to HEAD's on the commit index. */
+        readonly writer: IGitWriter;
+        /** <stateDir>/commit-index */
+        readonly path: string;
+    };
+    readonly indexLock: IGitIndexLock;
+    readonly fs: IFileSystem;
+    readonly logger: ILogger;
+    readonly settings: {
+        /** The working tree root, to read a path's working-tree side. */
+        readonly root: string;
+        /** <gitDir>/index */
+        readonly realIndex: string;
+    };
+}
+export type RepairStaleIndexResult = 
+/** HEAD is no longer lastMove.to: the memory has nothing left to repair against. */
+{
+    readonly kind: 'moved';
+}
+/** No staged path carries the stale signature: nothing touched, the memory stays. */
+ | {
+    readonly kind: 'none';
+}
+/** index.lock held, an operation started or the real index changed meanwhile: nothing touched, tried again next cycle. */
+ | {
+    readonly kind: 'busy';
+} | {
+    readonly kind: 'repaired';
+    readonly paths: readonly string[];
+}
+/**
+ * No stale path, but staged paths whose index entry AND working tree are
+ * lastMove.from's: a failed git merge's restore_state left them (design
+ * 13.2, Decision 108), or the person reverted them. Named once in
+ * STAGED_REVERT, nothing written; the caller forgets lastMove, so the line
+ * is not repeated. A cycle that also repairs returns repaired and logs both.
+ */
+ | {
+    readonly kind: 'reverted';
+    readonly paths: readonly string[];
+};
+/**
+ * Controller: sets back index entries that a person's git command wrote back
+ * from before enmetu's last move of HEAD, its commit or its pull (design
+ * 12.7, Decision 98). A command that read the real index before the move and
+ * writes it after (measured for git merge against enmetu's commit section;
+ * seen in the stress scenario against enmetu's rebase) leaves HEAD at
+ * lastMove.to and lastMove.from's entries in the index, which would revert
+ * the move in the person's next commit.
+ *
+ * 1. HEAD differs from lastMove.to: moved.
+ * 2. Candidates: git.stagedPaths() (index against HEAD), in git's order. A
+ *    path is stale when its index entry equals lastMove.from's (both absent
+ *    for a path the move added) while the working tree does not (absent, or
+ *    a regular file whose filtered blob is not from's; a link or a directory
+ *    is never stale). A path the move did not change has from's entry in
+ *    HEAD, so it differs from HEAD only with another entry and never matches.
+ *    Reverted: index entry and working tree both from's (design 13.2,
+ *    Decision 108). Neither: none. Only reverted: STAGED_REVERT once, nothing
+ *    written, reverted.
+ * 3. Prepare: fs.copy(realIndex, commit index), so every other entry, the
+ *    person's staged selection included, stays unchanged; commitIndex.writer
+ *    .unstage(stale) sets exactly those entries to HEAD's.
+ * 4. Critical section, shaped like the commit's (Decision 81): indexLock.acquire
+ *    (false: busy); an operation in progress or the real index's identity
+ *    differing from before: release, busy; HEAD moved: release, moved;
+ *    indexLock.install(commit index); release on every path.
+ * 5. INDEX_REPAIRED once, naming the paths, then STAGED_REVERT for reverted
+ *    paths; repaired. Busy or moved names nothing, so the next cycle does.
+ */
+export declare function repairStaleIndexController(input: RepairStaleIndexInput, deps: RepairStaleIndexDeps): Promise<RepairStaleIndexResult>;