@fluado/enmetu 0.2.0 → 0.4.0

package/dist/core/status/statusHeadline.js

@@ -69,6 +69,9 @@ function runningHeadline(record, uncommitted, unpushed) {
             if (record.reason === 'COMMIT_HOOK_REJECTED') {
                 return `waiting: a commit hook rejected the last commit since ${since}, ${work}`;
             }
+            if (record.reason === 'TREE_CHANGING') {
+                return `waiting: a save landed during the last cycle since ${since}; the pull waits for a quiet cycle, ${work}`;
+            }
             return `waiting:${reasonText(record)} since ${since}, ${work}`;
         case 'paused':
             return `paused:${reasonText(record)} since ${since}, ${work}`;

package/dist/enmetuInstances.d.ts

@@ -7,6 +7,7 @@ import type { IDaemon } from './contracts/IDaemon.js';
 import type { IHookInstaller } from './contracts/IHookInstaller.js';
 import type { IProcessHost } from './contracts/IProcessHost.js';
 import type { IRepositoryLocator, RepositoryPaths } from './contracts/IRepositoryLocator.js';
+import type { CommitMessageWriter } from './contracts/library.js';
 import type { Runtime } from './contracts/runtime.js';
 import type { ReadStateDeps } from './library/readStateController.js';
 import { type RecoveryDeps } from './recovery/recoveryController.js';
@@ -25,9 +26,10 @@ export declare function createRecoveryDeps(paths: RepositoryPaths, config: Enmet
  * their controllers. Recovery, preflight, hook installer and cycle share one
  * set of repository parts, so one halt store guards every writer. processHost
  * defaults to the operating system's signals; the library passes
- * RequestedStopProcessHost so a host program's process is left alone.
+ * RequestedStopProcessHost so a host program's process is left alone, and the
+ * host's commitMessage writer when it has one (design 14.19).
  */
-export declare function createDaemon(paths: RepositoryPaths, config: EnmetuConfig, runtime: Runtime, processHost?: IProcessHost | undefined): IDaemon;
+export declare function createDaemon(paths: RepositoryPaths, config: EnmetuConfig, runtime: Runtime, processHost?: IProcessHost | undefined, commitMessage?: CommitMessageWriter | undefined): IDaemon;
 /**
  * The daemon's hook installer for one repository (design 13.1): it records
  * Runtime.execPath, resolved through the PATH enmetu was started with when it
@@ -58,8 +60,9 @@ export interface EmbeddedRun {
 /**
  * runCommand's deps with one process host shared by the daemon and its lock:
  * the lock still records this process's pid and hostname, while stops come
- * from requestStop() instead of the host program's signals.
+ * from requestStop() instead of the host program's signals. commitMessage is
+ * the host's writer, when it passed one (design 14.19).
  */
-export declare function createEmbeddedRunDeps(runtime: Runtime): EmbeddedRun;
+export declare function createEmbeddedRunDeps(runtime: Runtime, commitMessage?: CommitMessageWriter | undefined): EmbeddedRun;
 /** The library's state read: the state file and the instance lock, nothing else (design 12.5). */
 export declare function createReadStateDeps(runtime: Runtime): ReadStateDeps;

package/dist/enmetuInstances.js

@@ -5,10 +5,12 @@ import { NodeFileSystemAdapter } from './adapters/fs/nodeFileSystemAdapter.js';
 import { GitFacade } from './adapters/git/gitFacade.js';
 import { GitLocatorFacade } from './adapters/git/gitLocatorFacade.js';
 import { GitProcessAdapter } from './adapters/git/gitProcessAdapter.js';
+import { HostMessageWriterAdapter } from './adapters/host/hostMessageWriterAdapter.js';
 import { NullLogger } from './adapters/log/nullLogger.js';
 import { StderrLoggerAdapter } from './adapters/log/stderrLoggerAdapter.js';
 import { NodeProcessAdapter } from './adapters/process/nodeProcessAdapter.js';
-import { FsWatchAdapter, nodeWatch } from './adapters/watch/fsWatchAdapter.js';
+import { ShellMessageCommandAdapter } from './adapters/process/shellMessageCommandAdapter.js';
+import { watcherFor } from './adapters/watch/watcherFor.js';
 import { commitLocalChangesController, } from './commit/commitLocalChangesController.js';
 import { GitIndexLock } from './commit/gitIndexLock.js';
 import { DEFAULT_CONFIG } from './core/config/parseConfig.js';
@@ -73,9 +75,10 @@ export function createRecoveryDeps(paths, config, runtime) {
  * their controllers. Recovery, preflight, hook installer and cycle share one
  * set of repository parts, so one halt store guards every writer. processHost
  * defaults to the operating system's signals; the library passes
- * RequestedStopProcessHost so a host program's process is left alone.
+ * RequestedStopProcessHost so a host program's process is left alone, and the
+ * host's commitMessage writer when it has one (design 14.19).
  */
-export function createDaemon(paths, config, runtime, processHost) {
+export function createDaemon(paths, config, runtime, processHost, commitMessage) {
     const parts = guardedRepositoryParts(paths, config.gitTimeoutMs, runtime);
     const host = processHost ?? new NodeProcessAdapter();
     // One recorder for the daemon's lifecycle events, the Decorator's cycle
@@ -93,7 +96,7 @@ export function createDaemon(paths, config, runtime, processHost) {
     // Aborted by the first stop request, so a running repository hook ends at
     // once instead of holding the stop for up to hookTimeoutMs (Decision 92).
     const hookStop = new AbortController();
-    const cycleDeps = syncCycleDepsOf(parts, commitOf(parts, paths, config, runtime, hookStop.signal), recorder);
+    const cycleDeps = syncCycleDepsOf(parts, commitOf(parts, paths, config, runtime, hookStop.signal, commitMessage), recorder);
     const cycle = new StateRecordingSyncCycle({ run: (input) => syncCycleController(input, cycleDeps) }, state, parts.git);
     const hookInstaller = hookInstallerOf(parts, paths, config, runtime);
     const scheduler = new HookAbortingSyncScheduler(new SyncScheduler(new SyncCycleRunner(cycle, parts.logger), parts.clock, {
@@ -101,7 +104,7 @@ export function createDaemon(paths, config, runtime, processHost) {
         maxDelayMs: config.maxDelayMs,
         pollMs: config.pollMs,
     }), hookStop);
-    return new Daemon({ root: paths.root, quietMs: config.quietMs, pollMs: config.pollMs }, lockFor(paths, parts.fs, host, parts.clock), parts.halt, recovery, preflight, hookInstaller, new FsWatchAdapter(paths.root, nodeWatch), scheduler, host, parts.logger, state, parts.clock);
+    return new Daemon({ root: paths.root, quietMs: config.quietMs, pollMs: config.pollMs }, lockFor(paths, parts.fs, host, parts.clock), parts.halt, recovery, preflight, hookInstaller, watcherFor(paths.root, runtime), scheduler, host, parts.logger, state, parts.clock);
 }
 /**
  * The daemon's hook installer for one repository (design 13.1): it records
@@ -118,13 +121,19 @@ function hookInstallerOf(parts, paths, config, runtime) {
         : new NullHookInstaller();
 }
 export function createRunDeps(runtime) {
+    const fs = new NodeFileSystemAdapter();
     return {
         locator: createLocator(runtime),
-        fs: new NodeFileSystemAdapter(),
+        fs,
+        readGitConfig: gitConfigReaderFor(runtime, fs),
         logger: new StderrLoggerAdapter(runtime.stderr, new SystemClockAdapter()),
         createDaemon: (paths, config) => createDaemon(paths, config, runtime),
     };
 }
+/** The run command's git config read, before the config and its git timeout are known (design 14.18). */
+function gitConfigReaderFor(runtime, fs) {
+    return (paths) => facadeFor(paths, UNCONFIGURED_GIT_TIMEOUT_MS, runtime, fs).enmetuEntries();
+}
 /**
  * Status reads only; its quarantine still sits on the guarded writer, so even
  * a mistaken write from status would honour the halt.
@@ -251,15 +260,27 @@ function lockFor(paths, fs, processHost, clock) {
 }
 /** The commit index of design 12.7, under the state directory, never committed. */
 const COMMIT_INDEX_FILE = 'commit-index';
+/** commitMessageCommand's fixed time limit, then commitSubject (design 14.18, Decision 131). */
+const MESSAGE_COMMAND_TIMEOUT_MS = 5000;
+/** The most of a message command's stdout enmetu reads; a message is far shorter. */
+const MESSAGE_COMMAND_OUTPUT_CAP_BYTES = 65536;
+/**
+ * A host writer's time limit: the command's own limit, which the writer may
+ * wait for through runCommand, plus room for its own git reads (design 14.19,
+ * Decision 135).
+ */
+const HOST_MESSAGE_TIMEOUT_MS = 10000;
 /**
  * The commit step bound into a closure (design 12.7): a second facade whose
  * runner sets GIT_INDEX_FILE to the commit index, its writer behind the same
  * halt Decorator, a real-index facade for post-commit and post-index-change,
  * both facades with the hook timeout and the daemon's hook stop signal
- * (undefined outside the daemon), the index lock and the NullLogger for the
- * residue build.
+ * (undefined outside the daemon), the index lock, the NullLogger for the
+ * residue build, the message command with its fixed time limit and the same
+ * stop signal (design 14.18), and the host's writer with its own limit and
+ * that signal when the library got one (design 14.19).
  */
-function commitOf(parts, paths, config, runtime, hookStop) {
+function commitOf(parts, paths, config, runtime, hookStop, commitMessage) {
     const commitIndexPath = join(paths.stateDir, COMMIT_INDEX_FILE);
     const commitFacade = new GitFacade(new GitProcessAdapter({
         cwd: paths.root,
@@ -285,12 +306,27 @@ function commitOf(parts, paths, config, runtime, hookStop) {
         },
         realHooks,
         indexLock: parts.indexLock,
+        messageCommand: new ShellMessageCommandAdapter({
+            cwd: paths.root,
+            baseEnv: runtime.env,
+            timeoutMs: MESSAGE_COMMAND_TIMEOUT_MS,
+            outputCapBytes: MESSAGE_COMMAND_OUTPUT_CAP_BYTES,
+            abort: hookStop,
+        }),
+        hostMessage: commitMessage === undefined
+            ? null
+            : new HostMessageWriterAdapter(commitMessage, {
+                root: paths.root,
+                timeoutMs: HOST_MESSAGE_TIMEOUT_MS,
+                abort: hookStop,
+            }),
         fs: parts.fs,
         logger: parts.logger,
         residueLogger: new NullLogger(),
         clock: parts.clock,
         settings: {
             commitSubject: config.commitSubject,
+            commitMessageCommand: config.commitMessageCommand,
             skipJsonCheck: config.skipJsonCheck,
             partialStagingWaitMs: config.partialStagingWaitMs,
             commitHooks: config.commitHooks,
@@ -303,16 +339,19 @@ function commitOf(parts, paths, config, runtime, hookStop) {
 /**
  * runCommand's deps with one process host shared by the daemon and its lock:
  * the lock still records this process's pid and hostname, while stops come
- * from requestStop() instead of the host program's signals.
+ * from requestStop() instead of the host program's signals. commitMessage is
+ * the host's writer, when it passed one (design 14.19).
  */
-export function createEmbeddedRunDeps(runtime) {
+export function createEmbeddedRunDeps(runtime, commitMessage) {
     const processHost = new RequestedStopProcessHost(new NodeProcessAdapter());
+    const fs = new NodeFileSystemAdapter();
     return {
         deps: {
             locator: createLocator(runtime),
-            fs: new NodeFileSystemAdapter(),
+            fs,
+            readGitConfig: gitConfigReaderFor(runtime, fs),
             logger: new StderrLoggerAdapter(runtime.stderr, new SystemClockAdapter()),
-            createDaemon: (paths, config) => createDaemon(paths, config, runtime, processHost),
+            createDaemon: (paths, config) => createDaemon(paths, config, runtime, processHost, commitMessage),
         },
         requestStop: () => processHost.requestStop(),
     };

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export type { ExitCode } from './contracts/exitCode.js';
 export { EXIT } from './contracts/exitCode.js';
 export type { DaemonState, LastCycle, StateInstance, StateReason, StateRecord, StateTransition, } from './contracts/IStateStore.js';
 export type { ITextSink } from './contracts/ITextSink.js';
-export type { EnmetuInstance, EnmetuStartOptions, EnmetuStateView, StateLiveness, } from './contracts/library.js';
+export type { CommitChange, CommitMessageWriter, EnmetuInstance, EnmetuStartOptions, EnmetuStateView, StateLiveness, } from './contracts/library.js';
 export type { ConflictKey, CycleOutcomeKind, PauseReason, WaitReason, } from './contracts/syncTypes.js';
 /** Starts enmetu for the repository containing options.repo, in this process. */
 export declare function startEnmetu(options: EnmetuStartOptions): EnmetuInstance;

package/dist/index.js

@@ -21,6 +21,8 @@ function processRuntime() {
         // records its own argv[1].
         cliPath: fileURLToPath(new URL('./cli.js', import.meta.url)),
         version: packageVersion(),
+        platform: process.platform,
+        engine: process.versions.bun === undefined ? 'node' : 'bun',
         stdout: process.stdout,
         stderr: process.stderr,
     };

package/dist/library/enmetuLibrary.d.ts

@@ -5,7 +5,8 @@ import type { Runtime } from '../contracts/runtime.js';
  * without src/index.ts (which reads the process and its own module URL). startEmbedded
  * runs runCommand with createEmbeddedRunDeps: the same locate, git version
  * gate, config and daemon `enmetu run` uses, but with RequestedStopProcessHost,
- * so stop() takes the place of the first SIGTERM. options.repo is resolved
+ * so stop() takes the place of the first SIGTERM, and with the host's
+ * commitMessage writer when it passed one (design 14.19). options.repo is resolved
  * against runtime.cwd. It returns at once; done resolves when the run ends and
  * never rejects: an error runCommand throws is written to the log sink in the
  * form `enmetu: <message>` and mapped by exitCodeFor, like the CLI's main, so a

package/dist/library/enmetuLibrary.js

@@ -9,7 +9,8 @@ import { readStateController } from './readStateController.js';
  * without src/index.ts (which reads the process and its own module URL). startEmbedded
  * runs runCommand with createEmbeddedRunDeps: the same locate, git version
  * gate, config and daemon `enmetu run` uses, but with RequestedStopProcessHost,
- * so stop() takes the place of the first SIGTERM. options.repo is resolved
+ * so stop() takes the place of the first SIGTERM, and with the host's
+ * commitMessage writer when it passed one (design 14.19). options.repo is resolved
  * against runtime.cwd. It returns at once; done resolves when the run ends and
  * never rejects: an error runCommand throws is written to the log sink in the
  * form `enmetu: <message>` and mapped by exitCodeFor, like the CLI's main, so a
@@ -17,7 +18,7 @@ import { readStateController } from './readStateController.js';
  */
 export function startEmbedded(options, runtime) {
     const embedded = embeddedRuntime(options, runtime);
-    const run = createEmbeddedRunDeps(embedded);
+    const run = createEmbeddedRunDeps(embedded, options.commitMessage);
     const done = settledRun({ startDir: resolve(runtime.cwd, options.repo) }, run.deps, embedded.stderr);
     return {
         done,
@@ -41,6 +42,8 @@ function embeddedRuntime(options, runtime) {
         execPath: runtime.execPath,
         cliPath: runtime.cliPath,
         version: runtime.version,
+        platform: runtime.platform,
+        engine: runtime.engine,
         stdout: runtime.stdout,
         stderr: options.log ?? runtime.stderr,
     };

package/dist/quarantine/pathQuarantine.d.ts

@@ -27,6 +27,16 @@ export declare class PathQuarantine implements IPathQuarantine {
     constructor(git: IGitReader, writer: IGitWriter, fs: IFileSystem, paths: QuarantinePaths);
     hold(paths: readonly string[]): Promise<HoldResult>;
     extend(paths: readonly string[]): Promise<HoldResult>;
+    /**
+     * git refused the checkout (a person's merge left a held path unmerged,
+     * design 14.20): an entry whose file still holds the bytes stored for it was
+     * never set aside, and restoring it later would write those bytes over the
+     * person's newer work, conflict markers included. Such entries leave the
+     * memento (the memento goes when none is left); an entry whose file changed
+     * stays, so no write goes unrecorded. Entries before `from` (an earlier
+     * hold that extend added to) stay as they are.
+     */
+    private forgetUnheld;
     /**
      * git's checkout writes the index's version over a file whatever the file
      * holds, so a write that landed after storeEntries read it would be gone

package/dist/quarantine/pathQuarantine.js

@@ -70,7 +70,13 @@ export class PathQuarantine {
         // --- Step 5: a file written since step 3 is stored again (Decision 114) ---
         await this.storeAgainIfWritten(entries, []);
         // --- Step 6: the held paths now match the index, so the rebase may run ---
-        await this.writer.restoreFromIndex(paths);
+        try {
+            await this.writer.restoreFromIndex(paths);
+        }
+        catch (error) {
+            await this.forgetUnheld(0);
+            throw error;
+        }
         return { kind: 'held', count: entries.length };
     }
     async extend(paths) {
@@ -102,9 +108,45 @@ export class PathQuarantine {
         // --- Step 6: a file written since step 4 is stored again (Decision 114) ---
         await this.storeAgainIfWritten(entries, earlier);
         // --- Step 7: the captured paths now match the index ---
-        await this.writer.restoreFromIndex(paths);
+        try {
+            await this.writer.restoreFromIndex(paths);
+        }
+        catch (error) {
+            await this.forgetUnheld(earlier.length);
+            throw error;
+        }
         return { kind: 'held', count: entries.length };
     }
+    /**
+     * git refused the checkout (a person's merge left a held path unmerged,
+     * design 14.20): an entry whose file still holds the bytes stored for it was
+     * never set aside, and restoring it later would write those bytes over the
+     * person's newer work, conflict markers included. Such entries leave the
+     * memento (the memento goes when none is left); an entry whose file changed
+     * stays, so no write goes unrecorded. Entries before `from` (an earlier
+     * hold that extend added to) stay as they are.
+     */
+    async forgetUnheld(from) {
+        const text = await this.fs.readText(this.mementoPath());
+        const memento = text === null ? null : parseQuarantineMemento(text);
+        if (memento === null) {
+            return;
+        }
+        const kept = memento.entries.slice(0, from);
+        for (const entry of memento.entries.slice(from)) {
+            const target = join(this.paths.root, entry.path);
+            const seen = await this.observe(entry.path, target);
+            if (seen !== (entry.blobId ?? OBSERVED_ABSENT)) {
+                kept.push(entry);
+            }
+        }
+        if (kept.length === 0) {
+            await this.fs.remove(this.mementoPath());
+        }
+        else {
+            await this.writeMemento({ version: 1, entries: kept });
+        }
+    }
     /**
      * git's checkout writes the index's version over a file whatever the file
      * holds, so a write that landed after storeEntries read it would be gone

package/dist/sync/integrateUpstreamController.d.ts

@@ -6,7 +6,7 @@ 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';
-import type { ConflictKey, PauseReason } from '../contracts/syncTypes.js';
+import type { ConflictKey, HoldPolicy, PauseReason } from '../contracts/syncTypes.js';
 export interface IntegrateUpstreamInput {
     readonly cycleId: string;
     /** The branch the cycle resolved its upstream for. */
@@ -16,6 +16,8 @@ export interface IntegrateUpstreamInput {
     /** Commits the upstream has that HEAD lacks, for the PULLED line. */
     readonly behind: number;
     readonly knownConflict: ConflictKey | null;
+    /** Which dirty tracked paths step 2 may hold (design 14.21, Decision 147). */
+    readonly hold: HoldPolicy;
 }
 export interface IntegrateUpstreamDeps {
     readonly git: IGitReader;
@@ -51,6 +53,14 @@ export type IntegrateUpstreamResult = {
 } | {
     readonly kind: 'halted';
     readonly code: HaltCode;
+}
+/**
+ * Dirty tracked paths the hold policy does not name were found: saves made
+ * during the cycle. Nothing was held or rebased (design 14.21, Decision 147).
+ */
+ | {
+    readonly kind: 'deferred';
+    readonly paths: readonly string[];
 };
 /**
  * The integrate step with its deps bound, the shape the sync cycle consumes. The
@@ -63,7 +73,11 @@ export type IntegrateUpstream = (input: IntegrateUpstreamInput) => Promise<Integ
  * paths held aside (design 1.11).
  *
  * 1. head = git.headCommit(); an identical knownConflict logs CONFLICT and returns it (Decision 11).
- * 2. Dirty tracked paths: quarantine.hold; pending returns busy, unsupported pauses QUARANTINE_UNSUPPORTED.
+ * 2. Dirty tracked paths: any the hold policy does not name is a save made
+ *    during the cycle, and the step returns deferred with those paths, nothing
+ *    held or rebased (design 14.21, Decision 147). Otherwise HELD names the
+ *    paths (Decision 148) and quarantine.hold runs; pending returns busy,
+ *    unsupported pauses QUARANTINE_UNSUPPORTED.
  * 3. From here on in try/finally:
  *    a. git.repositoryState() again: operation pauses FOREIGN_OPERATION, indexLocked returns busy,
  *       another branch pauses BRANCH_CHANGED.

package/dist/sync/integrateUpstreamController.js

@@ -9,7 +9,11 @@ const SHORT_SHA_LENGTH = 7;
  * paths held aside (design 1.11).
  *
  * 1. head = git.headCommit(); an identical knownConflict logs CONFLICT and returns it (Decision 11).
- * 2. Dirty tracked paths: quarantine.hold; pending returns busy, unsupported pauses QUARANTINE_UNSUPPORTED.
+ * 2. Dirty tracked paths: any the hold policy does not name is a save made
+ *    during the cycle, and the step returns deferred with those paths, nothing
+ *    held or rebased (design 14.21, Decision 147). Otherwise HELD names the
+ *    paths (Decision 148) and quarantine.hold runs; pending returns busy,
+ *    unsupported pauses QUARANTINE_UNSUPPORTED.
  * 3. From here on in try/finally:
  *    a. git.repositoryState() again: operation pauses FOREIGN_OPERATION, indexLocked returns busy,
  *       another branch pauses BRANCH_CHANGED.
@@ -65,8 +69,24 @@ export async function integrateUpstreamController(input, deps) {
             entry.worktree === 'D' ||
             entry.worktree === 'T'))
         .map((entry) => entry.path);
+    // A dirty path the commit step could have committed is a save that landed
+    // since its add -A: holding it would rewrite a file the person is editing
+    // (design 14.21). The pull waits for a cycle that commits it first.
+    const policy = input.hold;
+    const fresh = policy.kind === 'all'
+        ? []
+        : dirty.filter((path) => !policy.paths.includes(path));
+    if (fresh.length > 0) {
+        return { kind: 'deferred', paths: fresh };
+    }
     let held = false;
     if (dirty.length > 0) {
+        deps.logger.log({
+            level: 'WARN',
+            code: 'HELD',
+            message: `set aside for the pull, showing the committed version until RESTORED: ${dirty.join(', ')}`,
+            cycleId,
+        });
         const hold = await deps.quarantine.hold(dirty);
         if (hold.kind === 'pending') {
             return { kind: 'busy' };

package/dist/sync/syncCycleController.d.ts

@@ -42,7 +42,9 @@ export interface SyncCycleDeps {
  *    memory (design 12.7); busy and paused return, committed and nothing go
  *    on, waiting goes on and is the outcome unless a later step returns
  *    something else. The check right before the commit is the commit step's,
- *    under index.lock.
+ *    under index.lock. The hold policy for step 9 (design 14.21): the commit
+ *    step's after committed or nothing, all after a hook rejection, nothing
+ *    after a clean status.
  * 6. Remote check: ls-remote, tracking ref, verified ref (seeded from tracking when missing).
  * 7. Verify and fetch: fetch into the incoming ref when the remote moved; the remote sha
  *    must descend from the verified sha, else halt UPSTREAM_REWRITTEN; then move the
@@ -53,6 +55,9 @@ export interface SyncCycleDeps {
  *    git.hasStagedChanges() says the real index differs from HEAD (git would
  *    refuse the rebase), integrate is skipped, UNPUSHED reported and waiting
  *    returned (Decision 84).
+ *    deferred (a save made during the cycle is dirty): UNPUSHED reported,
+ *    waiting TREE_CHANGING returned, the refusal count left as it is
+ *    (Decision 147).
  *    not-started: the count of consecutive refusals (input.notStartedRebases)
  *    goes up by one; the first logs REBASE_NOT_STARTED with git's first stderr
  *    line; UNPUSHED is reported; the outcome is busy, or paused REBASE_REFUSED

package/dist/sync/syncCycleController.js

@@ -1,5 +1,5 @@
 import { EnmetuError } from '../contracts/errors.js';
-import { EMPTY_COMMIT_MEMORY, } from '../contracts/syncTypes.js';
+import { EMPTY_COMMIT_MEMORY, HOLD_NOTHING, } from '../contracts/syncTypes.js';
 import { withLastMove } from '../core/commit/commitMemory.js';
 import { withCycleId } from '../core/errors/withCycleId.js';
 import { incomingRefFor, verifiedRefFor } from '../core/git/enmetuRefs.js';
@@ -28,7 +28,9 @@ export const REBASE_REFUSED_AFTER = 3;
  *    memory (design 12.7); busy and paused return, committed and nothing go
  *    on, waiting goes on and is the outcome unless a later step returns
  *    something else. The check right before the commit is the commit step's,
- *    under index.lock.
+ *    under index.lock. The hold policy for step 9 (design 14.21): the commit
+ *    step's after committed or nothing, all after a hook rejection, nothing
+ *    after a clean status.
  * 6. Remote check: ls-remote, tracking ref, verified ref (seeded from tracking when missing).
  * 7. Verify and fetch: fetch into the incoming ref when the remote moved; the remote sha
  *    must descend from the verified sha, else halt UPSTREAM_REWRITTEN; then move the
@@ -39,6 +41,9 @@ export const REBASE_REFUSED_AFTER = 3;
  *    git.hasStagedChanges() says the real index differs from HEAD (git would
  *    refuse the rebase), integrate is skipped, UNPUSHED reported and waiting
  *    returned (Decision 84).
+ *    deferred (a save made during the cycle is dirty): UNPUSHED reported,
+ *    waiting TREE_CHANGING returned, the refusal count left as it is
+ *    (Decision 147).
  *    not-started: the count of consecutive refusals (input.notStartedRebases)
  *    goes up by one; the first logs REBASE_NOT_STARTED with git's first stderr
  *    line; UNPUSHED is reported; the outcome is busy, or paused REBASE_REFUSED
@@ -115,6 +120,9 @@ async function runCycle(input, deps, carried, outcome) {
     // The commit's parent when this cycle committed: step 9 records the pull
     // from there, so the repair covers the commit and the pull in one move.
     let committedFrom = null;
+    // Which dirty paths the pull may set aside (design 14.21): after a clean
+    // status none, so a path dirty at step 9 is a save made during the cycle.
+    let hold = HOLD_NOTHING;
     if ((await deps.git.status()).length > 0) {
         // A person's merge, cherry-pick or revert that stopped after step 2 is in
         // that status; the commit step would only find it under index.lock (Decision 52).
@@ -135,6 +143,14 @@ async function runCycle(input, deps, carried, outcome) {
         }
         if (committed.kind === 'waiting') {
             waiting = committed.reason;
+            // A rejected commit leaves every dirty path uncommittable; a rejecting
+            // hook must not block incoming changes (D4), so the pull holds them all.
+            if (committed.reason === 'COMMIT_HOOK_REJECTED') {
+                hold = { kind: 'all' };
+            }
+        }
+        if (committed.kind === 'committed' || committed.kind === 'nothing') {
+            hold = committed.hold;
         }
         if (committed.kind === 'committed') {
             committedFrom = committed.memory.lastMove?.from ?? null;
@@ -217,7 +233,13 @@ async function runCycle(input, deps, carried, outcome) {
             ontoSha: remoteSha,
             behind,
             knownConflict: input.knownConflict,
+            hold,
         });
+        if (integrated.kind === 'deferred') {
+            // The next cycle commits the save first; the runner logs WAITING once.
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome({ kind: 'waiting', reason: 'TREE_CHANGING' });
+        }
         if (integrated.kind === 'not-started') {
             const refusals = (carried.notStartedRebases ?? 0) + 1;
             carried.notStartedRebases = refusals;

package/dist/sync/syncCycleRunner.js

@@ -3,6 +3,7 @@ import { errorMessage } from '../core/errors/errorMessage.js';
 const WAITING_MESSAGES = {
     PARTIAL_SELECTION_STAGED: 'waiting: a partial selection is staged; nothing is committed or pulled until you commit or unstage it, and after partialStagingWaitMs enmetu commits everything',
     COMMIT_HOOK_REJECTED: 'waiting: a commit hook rejected the commit; enmetu tries again when the files change',
+    TREE_CHANGING: 'waiting: a file was saved while this cycle ran; the pull waits for a cycle that finds nothing new to commit, so no file you are editing is set aside',
 };
 /**
  * Service: the memory that spans cycles. Numbers cycles c1, c2, ...; passes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluado/enmetu",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Keeps one git working tree committed and in sync with its upstream.",
   "license": "MIT",
   "author": "fluado UG (haftungsbeschränkt)",