@fluado/enmetu 0.0.0-stage → 0.1.0

package/dist/recovery/enmetuRebaseAbort.js

@@ -0,0 +1,302 @@
+import { findContentViolation } from '../core/content/contentRules.js';
+import { writesDuringStoppedRebase } from '../core/git/stoppedRebaseWrites.js';
+import { recordHalt } from '../halt/recordHalt.js';
+/**
+ * Capture, abort and verify (1.11 abort-and-verify, 1.14 step 2): the one
+ * implementation for the live cycle and for startup recovery. The caller has
+ * already proven the rebase in progress is enmetu's (HEAD's reflog carries the
+ * attempt's token, or, without a reflog, orig-head and onto match; Decision 104).
+ *
+ * 0a. branchRef = git.rebaseHeadName(): the branch the rebase returns to,
+ *    null for a rebase started on a detached HEAD (Decision 122).
+ * 0. Read the writes that landed during the stop (Decision 45).
+ * 0b. Name: every staged path the abort resets that is not written, not
+ *    changed by the stopped commit and not orig-head's version is logged
+ *    STAGED_RESET with its stage-0 blob (Decisions 105, 115); nothing is
+ *    written for it.
+ * 0c. Capture, the last step before the abort: the status is read again, the
+ *    writes go through quarantine.extend, and the status is read again after
+ *    each capture, up to MAX_CAPTURE_ROUNDS captures, so a write that landed
+ *    while enmetu was naming or capturing is held too (Decision 113). A
+ *    written path the stopped commit changes that holds git's conflict
+ *    markers is not captured but named, and the abort resets it (Decision
+ *    118). A refused capture halts REBASE_ABORT_UNVERIFIED with the rebase
+ *    left in progress.
+ * 1a. A commit made on the rebase's detached HEAD (HEAD's newest reflog
+ *    entry is not the attempt's, and the attempt's last HEAD is an ancestor
+ *    of HEAD) is left on no branch by step 1 and its changes leave the disk:
+ *    COMMIT_ORPHANED names it with the remedy (Decision 124), and deps.orphans
+ *    records it for `enmetu status` (design 14.15).
+ * 1. tip = git.resolveCommit(branchRef), the last read before git's write. A
+ *    tip other than origHead (a commit moved the branch while the rebase
+ *    ran): writer.endRebaseAtBranch(branchRef) and REBASE_BRANCH_MOVED;
+ *    otherwise writer.abortRebase() (Decision 122).
+ * 2. Verify: no operation, nothing unmerged, HEAD at the moved tip or at
+ *    origHead and, with a branchRef, HEAD naming it; a failure halts
+ *    REBASE_ABORT_UNVERIFIED, none clears the journal. branchMovedTo carries
+ *    the tip step 1 ended at.
+ */
+export async function abortEnmetuRebase(input, deps) {
+    const { cycleId, origHead, onto } = input;
+    // --- Step 0a: the branch the rebase returns to (Decision 122) ---
+    const branchRef = await deps.git.rebaseHeadName();
+    // --- Step 0: the abort resets every tracked file; these were written ---
+    const written = writesDuringStoppedRebase(await deps.git.status());
+    const pickPaths = await stoppedCommitPaths(deps);
+    // --- Step 0b: a person's staged write is reset by the abort; name its blob ---
+    await nameStagedWrites(input, written, pickPaths, deps);
+    // --- Step 0c: hold every write aside, reading again until none is new ---
+    const capture = await captureWrites(input, pickPaths, deps);
+    if (capture.kind === 'refused') {
+        // Aborting would discard the write; the rebase stays for a person to end.
+        const reason = capture.result.kind === 'unsupported'
+            ? `${capture.result.path} was written while the rebase was stopped and cannot be held (a symlink or a directory); end the rebase by hand once that path is safe`
+            : 'the quarantine memento cannot be read, so the writes made while the rebase was stopped cannot be held; end the rebase by hand once those paths are safe';
+        await recordHalt({
+            code: 'REBASE_ABORT_UNVERIFIED',
+            message: `enmetu's rebase of ${origHead} onto ${onto} was left in progress: ${reason}; the rebase journal and any held paths are kept`,
+            cycleId,
+        }, deps);
+        return {
+            verdict: 'unverified',
+            captured: capture.captured,
+            branchMovedTo: null,
+        };
+    }
+    const { captured } = capture;
+    // --- Step 1a: a commit on the rebase's detached HEAD is named, not kept ---
+    await nameOrphanedCommits(input, deps);
+    // --- Step 1: the branch's tip, the last read before git's write; a moved
+    // branch ends the rebase there, since git rebase --abort would reset the
+    // branch to orig-head with no old-value check and drop the commit that
+    // moved it. Neither exit code says anything the verification does not ---
+    const tip = branchRef === null ? null : await deps.git.resolveCommit(branchRef);
+    const branchMovedTo = branchRef !== null && tip !== null && tip !== origHead ? tip : null;
+    if (branchRef !== null && branchMovedTo !== null) {
+        await deps.writer.endRebaseAtBranch(branchRef);
+        deps.logger.log({
+            level: 'WARN',
+            code: 'REBASE_BRANCH_MOVED',
+            message: `${branchRef} moved from ${shortSha(origHead)} to ${shortSha(branchMovedTo)} while enmetu's rebase onto ${shortSha(onto)} ran (a commit made meanwhile); git rebase --abort would have reset it to ${shortSha(origHead)} and dropped that commit, so enmetu ended its rebase at ${shortSha(branchMovedTo)} and rebases again on the next cycle`,
+            cycleId,
+        });
+    }
+    else {
+        await deps.writer.abortRebase();
+    }
+    // --- Step 2: verify HEAD and, with a head-name, the branch HEAD names ---
+    const failure = await rebaseEndFailure({ head: branchMovedTo ?? origHead, branchRef }, deps);
+    if (failure !== null) {
+        await recordAbortUnverified(input, failure, deps);
+        return { verdict: 'unverified', captured, branchMovedTo };
+    }
+    await deps.journal.clear();
+    return { verdict: 'verified', captured, branchMovedTo };
+}
+/**
+ * Step 1a (design 14.14, Decision 124). A person's `git commit` (or merge)
+ * while enmetu's rebase is in progress lands on the rebase's detached HEAD:
+ * status is clean afterwards, so step 0 captures nothing and step 0b names
+ * nothing, and both `git rebase --abort` and endRebaseAtBranch leave that
+ * commit on no branch and set the tree to the branch's version. Keeping it
+ * would mean replaying it onto the branch, a conflict wherever it holds git's
+ * markers from the stopped pick (a `git add -A`), so it is named instead, as
+ * step 0b names a staged write: the commit stays in HEAD's reflog until git
+ * gc expires it. Only commits built on the rebase's own last HEAD are named;
+ * HEAD moved anywhere else (a checkout, a reset) made no commit to lose.
+ */
+async function nameOrphanedCommits(input, deps) {
+    if (input.reflogAction === null) {
+        return;
+    }
+    const move = await deps.git.headMovedSince(input.reflogAction);
+    if (move === null ||
+        move.from === move.to ||
+        !(await deps.git.isAncestor(move.from, move.to))) {
+        return;
+    }
+    deps.logger.log({
+        level: 'WARN',
+        code: 'COMMIT_ORPHANED',
+        message: `HEAD moved from ${shortSha(move.from)} to ${move.to} while enmetu's rebase onto ${shortSha(input.onto)} was in progress (a commit made on the rebase's detached HEAD, a git commit of yours most likely); ending the rebase leaves that commit on no branch and takes its changes off disk; git cherry-pick -x ${move.from}..${move.to} puts it on your branch (a file the rebase stopped on may hold git's conflict markers in that commit: keep your branch's version with git checkout --ours -- <path>), and git reflog keeps it until git gc expires it; enmetu status lists it until a local branch has it`,
+        cycleId: input.cycleId,
+    });
+    if (deps.orphans !== undefined) {
+        await deps.orphans.orphaned({
+            commit: move.to,
+            base: move.from,
+            subject: await subjectOrNothing(move.to, deps),
+        });
+    }
+}
+/**
+ * The subject only labels the status line; a failed read (a git timeout) must
+ * not keep step 1 from ending the rebase, so it records no subject instead.
+ */
+async function subjectOrNothing(commit, deps) {
+    try {
+        return await deps.git.commitSubject(commit);
+    }
+    catch {
+        return '';
+    }
+}
+const SHORT_SHA_LENGTH = 7;
+function shortSha(sha) {
+    return sha.slice(0, SHORT_SHA_LENGTH);
+}
+/**
+ * How many captures step 0c runs at most before the abort. Each capture takes
+ * a few git spawns; a write that lands during one is found by the next status
+ * read. The bound keeps a file saved over and over from holding the abort
+ * back for ever; what stays open is the time between the last status read and
+ * the reset inside `git rebase --abort` (design 13.11).
+ */
+export const MAX_CAPTURE_ROUNDS = 3;
+/**
+ * Step 0c (Decision 113). `git rebase --abort` resets every tracked file to
+ * orig-head whatever it holds, so a write that lands after the capture read
+ * the status, and before the abort, is overwritten without a record; the
+ * status is read again after every capture, and new writes are captured too.
+ * Git's own conflict markers in a path the stopped commit changes are not
+ * captured (Decision 118, splitMarkerLeftovers).
+ */
+async function captureWrites(input, pickPaths, deps) {
+    const leftovers = new Set();
+    // Read afresh, not reused from step 0: step 0b's spawns ran since.
+    let pending = await splitMarkerLeftovers(input, pickPaths, leftovers, deps);
+    let captured = false;
+    for (let round = 0; round < MAX_CAPTURE_ROUNDS && pending.length > 0; round += 1) {
+        const result = await deps.quarantine.extend(pending);
+        if (result.kind !== 'held') {
+            return { kind: 'refused', result, captured };
+        }
+        captured = true;
+        pending = await splitMarkerLeftovers(input, pickPaths, leftovers, deps);
+    }
+    return { kind: 'captured', captured };
+}
+/**
+ * The writes to capture, read from a fresh status, without git's leftovers
+ * (design 13.11, Decision 118). A person's git command that writes the index
+ * while enmetu's rebase is stopped (a `git merge` that read HEAD before
+ * enmetu's checkout and writes its index back) turns the conflicted path into
+ * a stage-0 entry and leaves git's conflict markers on disk, so the path looks
+ * like a person's write. Captured and restored after the abort, the markers would make
+ * enmetu exclude the path (CONFLICT_MARKERS) and the pre-commit hook refuse
+ * every commit. A written path the stopped commit changes whose bytes carry
+ * conflict markers (D11's rule) is therefore left to the abort, which resets
+ * it to orig-head, and its bytes are stored and named once in a
+ * QUARANTINE_KEPT line. A written path of the stopped commit without markers
+ * is captured; checking it costs two spawns per round (store, read).
+ */
+async function splitMarkerLeftovers(input, pickPaths, leftovers, deps) {
+    const pending = [];
+    for (const path of writesDuringStoppedRebase(await deps.git.status())) {
+        if (leftovers.has(path)) {
+            continue;
+        }
+        if (pickPaths.includes(path)) {
+            const blobId = await deps.writer.storeBlob(path);
+            const content = await deps.git.readBlob(blobId);
+            if (findContentViolation({ path, content }, [])?.rule === 'CONFLICT_MARKERS') {
+                leftovers.add(path);
+                deps.logger.log({
+                    level: 'WARN',
+                    code: 'QUARANTINE_KEPT',
+                    message: `${path} holds git's conflict markers from enmetu's stopped rebase but is no longer unmerged (a git command wrote the index meanwhile), so git rebase --abort resets it instead of enmetu writing the markers back; the version on disk is blob ${blobId} (git cat-file -p ${blobId}), kept until git gc prunes it`,
+                    cycleId: input.cycleId,
+                });
+                continue;
+            }
+        }
+        pending.push(path);
+    }
+    return pending;
+}
+/** The paths the stopped pick changes (REBASE_HEAD^..REBASE_HEAD); none when either commit is missing. */
+async function stoppedCommitPaths(deps) {
+    const pick = await deps.git.resolveCommit('REBASE_HEAD');
+    const parent = await deps.git.resolveCommit('REBASE_HEAD^');
+    return pick === null || parent === null
+        ? []
+        : deps.git.changedPaths(parent, pick);
+}
+/**
+ * The verification's checks, read without halting: no operation in progress, nothing
+ * unmerged, HEAD back at origHead. Returns the failure's detail, or null when
+ * all three hold. It records nothing, so a caller can ask who started the
+ * rebase before it decides on a halt (design 13.2).
+ */
+export async function rebaseAbortFailure(input, deps) {
+    return rebaseEndFailure({ head: input.origHead, branchRef: null }, deps);
+}
+/**
+ * Step 2's checks (design 14.4): no operation, nothing unmerged, HEAD at
+ * expected.head, and HEAD naming expected.branchRef when it is set, so a HEAD
+ * left detached by a switch that never ran is not taken for an ended rebase.
+ */
+async function rebaseEndFailure(expected, deps) {
+    const state = await deps.git.repositoryState();
+    const unmerged = await deps.git.hasUnmergedPaths();
+    const head = await deps.git.headCommit();
+    const onBranch = expected.branchRef === null || state.branchRef === expected.branchRef;
+    if (state.operation === null &&
+        !unmerged &&
+        head === expected.head &&
+        onBranch) {
+        return null;
+    }
+    const named = expected.branchRef === null
+        ? ''
+        : `, HEAD names ${state.branchRef ?? 'no branch'} (expected ${expected.branchRef})`;
+    return `operation ${state.operation ?? 'none'}, unmerged paths ${unmerged ? 'present' : 'none'}, HEAD ${head ?? 'unborn'} (expected ${expected.head})${named}`;
+}
+/**
+ * Halts REBASE_ABORT_UNVERIFIED and keeps the journal and any memento, which
+ * are what a person needs to finish by hand.
+ */
+export async function recordAbortUnverified(input, failure, deps) {
+    await recordHalt({
+        code: 'REBASE_ABORT_UNVERIFIED',
+        message: `enmetu's rebase of ${input.origHead} onto ${input.onto} could not be confirmed aborted (${failure}); the rebase journal and any held paths are kept`,
+        cycleId: input.cycleId,
+    }, deps);
+}
+/**
+ * Step 0b (Decision 105). The capture reads the worktree column, and a
+ * person's `git add` leaves it clean like the rebase's own staging, so a
+ * staged write is not captured and `git rebase --abort` resets it. Restoring
+ * it would need telling it from the stopped pick's merge result, which an
+ * upstream rename stages outside the pick's paths (probe C2), so it is named
+ * instead: the person's `git add` wrote the blob, and the line carries its id.
+ * The pick's own paths are skipped (their entries are the merge's result), and
+ * so are captured paths, unmerged paths and staged deletions (no stage-0 blob).
+ * So is an entry whose blob is orig-head's version of the path: the abort
+ * resets it to that same blob, which is in enmetu's own history, so nothing
+ * is lost. A refused `git merge` that started from orig-head leaves exactly
+ * such entries when its restore_state (`git read-tree --reset -u <orig-head>`)
+ * runs during the stop (design 13.11, Decision 115).
+ */
+async function nameStagedWrites(input, captured, pickPaths, deps) {
+    const staged = await deps.git.stagedPaths();
+    if (staged.length === 0) {
+        return;
+    }
+    for (const path of staged) {
+        if (pickPaths.includes(path) || captured.includes(path)) {
+            continue;
+        }
+        const blobId = await deps.git.entryBlobId(path, null);
+        if (blobId === null ||
+            blobId === (await deps.git.entryBlobId(path, input.origHead))) {
+            continue;
+        }
+        deps.logger.log({
+            level: 'WARN',
+            code: 'STAGED_RESET',
+            message: `${path} was staged while enmetu's rebase was stopped, and git rebase --abort resets it; the staged version is blob ${blobId} (git cat-file -p ${blobId}), kept until git gc prunes it`,
+            cycleId: input.cycleId,
+        });
+    }
+}

package/dist/recovery/operationJournal.d.ts

@@ -0,0 +1,13 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IOperationJournal, RebaseJournal } from '../contracts/IOperationJournal.js';
+export declare const JOURNAL_FILE_NAME = "rebase-journal.json";
+/** Service: <stateDir>/rebase-journal.json, written before every rebase (Decision 14). */
+export declare class OperationJournal implements IOperationJournal {
+    private readonly fs;
+    private readonly stateDir;
+    constructor(fs: IFileSystem, stateDir: string);
+    read(): Promise<RebaseJournal | null>;
+    begin(entry: RebaseJournal): Promise<void>;
+    clear(): Promise<void>;
+    private path;
+}

package/dist/recovery/operationJournal.js

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { parseRebaseJournal } from '../core/state/stateGuards.js';
+export const JOURNAL_FILE_NAME = 'rebase-journal.json';
+/** Service: <stateDir>/rebase-journal.json, written before every rebase (Decision 14). */
+export class OperationJournal {
+    fs;
+    stateDir;
+    constructor(fs, stateDir) {
+        this.fs = fs;
+        this.stateDir = stateDir;
+    }
+    async read() {
+        const text = await this.fs.readText(this.path());
+        // Unparseable gives null: recovery never aborts a rebase it cannot prove
+        // is its own, and the preflight then refuses to start, so a person decides.
+        return text === null ? null : parseRebaseJournal(text);
+    }
+    async begin(entry) {
+        // Built field by field in interface order, so the file is byte-stable.
+        const persisted = {
+            origHead: entry.origHead,
+            onto: entry.onto,
+            cycleId: entry.cycleId,
+            at: entry.at,
+        };
+        await this.fs.writeAtomic(this.path(), `${JSON.stringify(persisted)}\n`, {
+            executable: false,
+            tempDir: this.stateDir,
+        });
+    }
+    async clear() {
+        await this.fs.remove(this.path());
+    }
+    path() {
+        return join(this.stateDir, JOURNAL_FILE_NAME);
+    }
+}

package/dist/recovery/recoveryController.d.ts

@@ -0,0 +1,48 @@
+import type { IClock } from '../contracts/IClock.js';
+import type { RecoveryResult } from '../contracts/IDaemon.js';
+import type { IGitIndexLock } from '../contracts/IGitIndexLock.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { IHaltStore } from '../contracts/IHaltStore.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { IOperationJournal } from '../contracts/IOperationJournal.js';
+import type { IPathQuarantine } from '../contracts/IPathQuarantine.js';
+import type { IOrphanedCommitRecorder } from '../contracts/IStateRecorder.js';
+export type { RecoveryResult };
+export interface RecoveryInput {
+    /** Always 'recovery'. */
+    readonly cycleId: string;
+}
+export interface RecoveryDeps {
+    readonly git: IGitReader;
+    readonly writer: IGitWriter;
+    readonly journal: IOperationJournal;
+    readonly quarantine: IPathQuarantine;
+    readonly halt: IHaltStore;
+    readonly logger: ILogger;
+    readonly clock: IClock;
+    /** Finishes or undoes an index.lock left by a crashed enmetu commit, step 0 (design 12.7). */
+    readonly indexLock: IGitIndexLock;
+    /** Passed to the rebase abort, which reports each commit it orphans (design 14.15). */
+    readonly orphans?: IOrphanedCommitRecorder | undefined;
+}
+/**
+ * Controller: startup recovery after a crash (design 1.14).
+ *
+ * 0. indexLock.releaseStale(git.headCommit()); released adds
+ *    INDEX_LOCK_RELEASED, its message saying whether the real index was kept
+ *    (the crashed commit is on the branch) or restored (design 12.7, Decision 81).
+ * 1. journal.read(); none: go to 4.
+ * 2. A rebase in progress whose orig-head AND onto equal the journal's is enmetu's
+ *    unless HEAD's newest start entry names another owner (rebaseOwner 'other',
+ *    Decision 104: clear the journal, STALE_JOURNAL_CLEARED, leave it):
+ *    abortEnmetuRebase (capture, name staged writes, abort, verify; a refused capture
+ *    or an unverified abort halts REBASE_ABORT_UNVERIFIED). No rebase in progress:
+ *    STALE_JOURNAL_CLEARED. Any other rebase is a person's: clear the journal, leave it.
+ * 3. A verified abort has cleared the journal (REBASE_ABORTED); a rebase
+ *    ended at a branch a commit moved meanwhile is recorded with that tip
+ *    (design 14.4, Decision 122).
+ * 4. quarantine.restore(): restored adds QUARANTINE_RESTORED; failed halts QUARANTINE_RESTORE_FAILED.
+ * Each action is logged RECOVERED once, here, with the recovery cycle id.
+ */
+export declare function recoveryController(input: RecoveryInput, deps: RecoveryDeps): Promise<RecoveryResult>;

package/dist/recovery/recoveryController.js

@@ -0,0 +1,112 @@
+import { withCycleId } from '../core/errors/withCycleId.js';
+import { rebaseOwner, rebaseReflogAction } from '../core/git/rebaseOwnership.js';
+import { logRestoreWarnings } from '../core/quarantine/restoreWarnings.js';
+import { recordHalt } from '../halt/recordHalt.js';
+import { abortEnmetuRebase } from './enmetuRebaseAbort.js';
+/**
+ * Controller: startup recovery after a crash (design 1.14).
+ *
+ * 0. indexLock.releaseStale(git.headCommit()); released adds
+ *    INDEX_LOCK_RELEASED, its message saying whether the real index was kept
+ *    (the crashed commit is on the branch) or restored (design 12.7, Decision 81).
+ * 1. journal.read(); none: go to 4.
+ * 2. A rebase in progress whose orig-head AND onto equal the journal's is enmetu's
+ *    unless HEAD's newest start entry names another owner (rebaseOwner 'other',
+ *    Decision 104: clear the journal, STALE_JOURNAL_CLEARED, leave it):
+ *    abortEnmetuRebase (capture, name staged writes, abort, verify; a refused capture
+ *    or an unverified abort halts REBASE_ABORT_UNVERIFIED). No rebase in progress:
+ *    STALE_JOURNAL_CLEARED. Any other rebase is a person's: clear the journal, leave it.
+ * 3. A verified abort has cleared the journal (REBASE_ABORTED); a rebase
+ *    ended at a branch a commit moved meanwhile is recorded with that tip
+ *    (design 14.4, Decision 122).
+ * 4. quarantine.restore(): restored adds QUARANTINE_RESTORED; failed halts QUARANTINE_RESTORE_FAILED.
+ * Each action is logged RECOVERED once, here, with the recovery cycle id.
+ */
+export async function recoveryController(input, deps) {
+    try {
+        return await recover(input, deps);
+    }
+    catch (error) {
+        throw withCycleId(error, input.cycleId);
+    }
+}
+async function recover(input, deps) {
+    const { cycleId } = input;
+    const actions = [];
+    const record = (action, message) => {
+        actions.push(action);
+        deps.logger.log({
+            level: 'INFO',
+            code: 'RECOVERED',
+            message: `${action}: ${message}`,
+            cycleId,
+        });
+    };
+    // --- Step 0: finish or undo a commit section a crash left under index.lock ---
+    const stale = await deps.indexLock.releaseStale(await deps.git.headCommit());
+    if (stale.kind === 'released') {
+        record('INDEX_LOCK_RELEASED', stale.index === 'kept'
+            ? 'removed the index.lock of a crashed enmetu commit; the commit is on the branch and the real index matches it'
+            : 'removed the index.lock of a crashed enmetu commit; HEAD never moved to it, so the real index is back to what it was before');
+    }
+    // --- Step 1: a journal means a rebase was started and not seen to finish ---
+    const journal = await deps.journal.read();
+    if (journal !== null) {
+        // --- Step 2: abort the rebase only when it is provably enmetu's ---
+        const origHead = await deps.git.rebaseOrigHead();
+        const onto = await deps.git.rebaseOnto();
+        if (origHead === null && onto === null) {
+            await deps.journal.clear();
+            record('STALE_JOURNAL_CLEARED', `no rebase is in progress; the journal of cycle ${journal.cycleId} was stale`);
+        }
+        else if (origHead !== journal.origHead || onto !== journal.onto) {
+            // A person's rebase, started after enmetu's ended: never touched here;
+            // the preflight then refuses to start while it is in progress.
+            await deps.journal.clear();
+            record('STALE_JOURNAL_CLEARED', `the rebase in progress is not enmetu's (orig-head ${origHead ?? 'none'}, onto ${onto ?? 'none'}); left alone`);
+        }
+        else if (rebaseOwner(await deps.git.rebaseStart(), journal) === 'other') {
+            // Same orig-head and onto, but HEAD's newest start entry is not the
+            // journal's token: a person's rebase from the same HEAD onto the same
+            // upstream, or enmetu's own killed before its checkout (Decision 104).
+            await deps.journal.clear();
+            record('STALE_JOURNAL_CLEARED', `the rebase in progress has the orig-head and onto of cycle ${journal.cycleId}'s journal, but HEAD's newest start entry is not that attempt's; left alone`);
+        }
+        else {
+            // Read while the rebase state exists, to name the branch should it have moved.
+            const branchRef = await deps.git.rebaseHeadName();
+            const abort = await abortEnmetuRebase({
+                cycleId,
+                origHead: journal.origHead,
+                onto: journal.onto,
+                reflogAction: rebaseReflogAction(journal),
+            }, deps);
+            if (abort.verdict === 'unverified') {
+                return { kind: 'halted', code: 'REBASE_ABORT_UNVERIFIED' };
+            }
+            // --- Step 3: the verified abort cleared the journal ---
+            record('REBASE_ABORTED', abort.branchMovedTo === null
+                ? `aborted enmetu's interrupted rebase onto ${journal.onto}; HEAD is back at ${journal.origHead}`
+                : `ended enmetu's interrupted rebase onto ${journal.onto} at ${abort.branchMovedTo}, the tip a commit moved ${branchRef ?? 'the branch'} to while the rebase waited; orig-head ${journal.origHead} is not restored`);
+        }
+    }
+    // --- Step 4: restore paths a crash left held, only now that no rebase of enmetu's is in progress ---
+    const restore = await deps.quarantine.restore();
+    if (restore.kind === 'failed') {
+        await recordHalt({
+            code: 'QUARANTINE_RESTORE_FAILED',
+            message: `restoring the quarantine memento left by a crash failed (${restore.detail}); the memento is kept`,
+            cycleId,
+        }, deps);
+        return { kind: 'halted', code: 'QUARANTINE_RESTORE_FAILED' };
+    }
+    if (restore.kind === 'restored') {
+        logRestoreWarnings(restore, cycleId, deps.logger);
+        record('QUARANTINE_RESTORED', restore.count === 1
+            ? '1 held path restored'
+            : `${restore.count} held paths restored`);
+    }
+    return actions.length === 0
+        ? { kind: 'clean' }
+        : { kind: 'recovered', actions };
+}

package/dist/state/stateFileStore.d.ts

@@ -0,0 +1,18 @@
+import type { IFileSystem } from '../contracts/IFileSystem.js';
+import type { IStateStore, StateRecord } from '../contracts/IStateStore.js';
+export declare const STATE_FILE_NAME = "state.json";
+/**
+ * Service: <stateDir>/state.json (design 12.1). read() parses through
+ * parseStateRecord; write() serialises the fields in StateRecord order into
+ * one JSON line and replaces the file with writeAtomic (temp file in the state
+ * directory, then rename), so a reader sees the old record or the new one,
+ * never a mix, and the file never grows by appending.
+ */
+export declare class StateFileStore implements IStateStore {
+    private readonly fs;
+    private readonly stateDir;
+    constructor(fs: IFileSystem, stateDir: string);
+    read(): Promise<StateRecord | null>;
+    write(record: StateRecord): Promise<void>;
+    private path;
+}

package/dist/state/stateFileStore.js

@@ -0,0 +1,73 @@
+import { join } from 'node:path';
+import { parseStateRecord } from '../core/state/stateGuards.js';
+export const STATE_FILE_NAME = 'state.json';
+/**
+ * Service: <stateDir>/state.json (design 12.1). read() parses through
+ * parseStateRecord; write() serialises the fields in StateRecord order into
+ * one JSON line and replaces the file with writeAtomic (temp file in the state
+ * directory, then rename), so a reader sees the old record or the new one,
+ * never a mix, and the file never grows by appending.
+ */
+export class StateFileStore {
+    fs;
+    stateDir;
+    constructor(fs, stateDir) {
+        this.fs = fs;
+        this.stateDir = stateDir;
+    }
+    async read() {
+        const text = await this.fs.readText(this.path());
+        return text === null ? null : parseStateRecord(text);
+    }
+    async write(record) {
+        await this.fs.writeAtomic(this.path(), `${serialise(record)}\n`, {
+            executable: false,
+            tempDir: this.stateDir,
+        });
+    }
+    path() {
+        return join(this.stateDir, STATE_FILE_NAME);
+    }
+}
+/**
+ * JSON.stringify keeps insertion order, so the record is rebuilt field by
+ * field: the bytes then depend on the values only, whichever object built them.
+ */
+function serialise(record) {
+    const ordered = {
+        version: record.version,
+        instance: {
+            pid: record.instance.pid,
+            hostname: record.instance.hostname,
+            startedAt: record.instance.startedAt,
+        },
+        state: record.state,
+        reason: record.reason,
+        message: record.message,
+        since: record.since,
+        pushed: record.pushed,
+        unpushed: record.unpushed,
+        lastCycle: record.lastCycle === null
+            ? null
+            : {
+                cycleId: record.lastCycle.cycleId,
+                outcome: record.lastCycle.outcome,
+                at: record.lastCycle.at,
+            },
+        conflict: record.conflict === null
+            ? null
+            : { head: record.conflict.head, upstream: record.conflict.upstream },
+        history: record.history.map((transition) => ({
+            state: transition.state,
+            reason: transition.reason,
+            at: transition.at,
+        })),
+        orphaned: record.orphaned.map((orphan) => ({
+            commit: orphan.commit,
+            base: orphan.base,
+            subject: orphan.subject,
+            at: orphan.at,
+        })),
+    };
+    return JSON.stringify(ordered);
+}

package/dist/state/stateRecorder.d.ts

@@ -0,0 +1,26 @@
+import type { IClock } from '../contracts/IClock.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { IOrphanedCommitRecorder, IStateRecorder, OrphanedCommitFacts, StateEvent } from '../contracts/IStateRecorder.js';
+import type { IStateStore } from '../contracts/IStateStore.js';
+/**
+ * Service, the imperative shell around stateRecordStep (design 12.1): holds
+ * the current record (read from the store once, at the first event, so the
+ * history survives a restart), applies each event with the clock's time and
+ * the history cap, and writes the result. A failed read means no record;
+ * a failed write logs STATE_WRITE_FAILED once until a write succeeds again
+ * and is never thrown, so state recording cannot stop syncing.
+ */
+export declare class StateRecorder implements IStateRecorder, IOrphanedCommitRecorder {
+    private readonly store;
+    private readonly clock;
+    private readonly logger;
+    private readonly historyCap;
+    private current;
+    private loaded;
+    private writeFailing;
+    constructor(store: IStateStore, clock: IClock, logger: ILogger, historyCap: number);
+    record(event: StateEvent): Promise<void>;
+    /** The rebase abort's view of this recorder (design 14.15); never throws, like record. */
+    orphaned(facts: OrphanedCommitFacts): Promise<void>;
+    private previous;
+}