@fluado/enmetu 0.1.0 → 0.3.0

package/dist/adapters/watch/watcherFor.js

@@ -0,0 +1,29 @@
+import { FsWatchAdapter, nodeWatch } from './fsWatchAdapter.js';
+/** Why no file watch starts under Node on Linux (design 14.20, Decision 137). */
+export const NODE_LINUX_WATCH_OFF = 'file watching is off under Node on Linux, where its recursive watch can end the process (nodejs/node#66791)';
+/**
+ * Null Object: a watcher that never starts and says so at once, so the
+ * daemon takes its existing path for a lost watch, one WATCHER_FAILED line,
+ * then the poll (Decision 21).
+ */
+export class PollOnlyWatcher {
+    reason;
+    constructor(reason) {
+        this.reason = reason;
+    }
+    start(listener) {
+        listener.onFailure(this.reason);
+    }
+    close() { }
+}
+/**
+ * The watcher for a runtime, chosen at the composition root (design 14.20):
+ * Node's recursive fs.watch on Linux throws ENOTDIR, EACCES or ELOOP inside
+ * its own event handler from 24.22.0 on, where no error listener sees it, so
+ * Node on Linux polls; Bun, and Node on every other platform, watch.
+ */
+export function watcherFor(root, runtime) {
+    return runtime.platform === 'linux' && runtime.engine === 'node'
+        ? new PollOnlyWatcher(NODE_LINUX_WATCH_OFF)
+        : new FsWatchAdapter(root, nodeWatch);
+}

package/dist/cli/commands/hookCommand.d.ts

@@ -20,8 +20,10 @@ export interface HookCommandResult {
 /**
  * Controller:
  * 1. locator.locate(startDir); anything but found: notice, exit 0 (the hook fails open).
- * 2. parseConfig of <root>/enmetu.config.json; a ConfigError prints a notice and
+ * 2. parseConfig of <root>/enmetu.config.json with git config over it, as the
+ *    daemon reads it (design 14.18); a ConfigError prints a notice and
  *    applies the defaults, so a broken config never blocks the commit that fixes it.
+ *    Unknown keys are ignored without a word: the daemon names them at start (design 14.17).
  * 3. preCommitCheckController with the config's skipJsonCheck.
  * 4. Violations: print the refusal of design 1.18 to stderr, exit 1. None: print nothing, exit 0.
  */

package/dist/cli/commands/hookCommand.js

@@ -7,8 +7,10 @@ const HOOK_CYCLE_ID = 'hook';
 /**
  * Controller:
  * 1. locator.locate(startDir); anything but found: notice, exit 0 (the hook fails open).
- * 2. parseConfig of <root>/enmetu.config.json; a ConfigError prints a notice and
+ * 2. parseConfig of <root>/enmetu.config.json with git config over it, as the
+ *    daemon reads it (design 14.18); a ConfigError prints a notice and
  *    applies the defaults, so a broken config never blocks the commit that fixes it.
+ *    Unknown keys are ignored without a word: the daemon names them at start (design 14.17).
  * 3. preCommitCheckController with the config's skipJsonCheck.
  * 4. Violations: print the refusal of design 1.18 to stderr, exit 1. None: print nothing, exit 0.
  */
@@ -20,10 +22,11 @@ export async function hookCommand(input, deps) {
         return { exitCode: EXIT.OK };
     }
     const { paths } = location;
-    // --- Step 2: the config at the root; defaults when it is broken ---
-    const config = await configForCheck(paths.root, deps);
+    const git = deps.openGit(paths);
+    // --- Step 2: the config at the root and git config; defaults when it is broken ---
+    const config = await configForCheck(paths.root, git, deps);
     // --- Step 3: the shared content rules over the staged blobs (D11) ---
-    const { violations } = await preCommitCheckController({ cycleId: HOOK_CYCLE_ID }, { git: deps.openGit(paths), skipJsonCheck: config.skipJsonCheck });
+    const { violations } = await preCommitCheckController({ cycleId: HOOK_CYCLE_ID }, { git, skipJsonCheck: config.skipJsonCheck });
     // --- Step 4: the refusal, or silence ---
     if (violations.length === 0) {
         return { exitCode: EXIT.OK };
@@ -55,15 +58,20 @@ async function locateOrReason(startDir, deps) {
             };
     }
 }
-async function configForCheck(root, deps) {
+async function configForCheck(root, git, deps) {
+    const text = await deps.fs.readText(join(root, CONFIG_FILE_NAME));
+    const gitEntries = await git.enmetuEntries();
     try {
-        return parseConfig(await deps.fs.readText(join(root, CONFIG_FILE_NAME)));
+        return parseConfig(text, gitEntries).config;
     }
     catch (error) {
         if (!(error instanceof ConfigError)) {
             throw error;
         }
-        deps.stderr.write(`enmetu: ignoring ${CONFIG_FILE_NAME} (${error.code}: ${error.message}); using the defaults for this check\n`);
+        const source = error.gitScope === null
+            ? CONFIG_FILE_NAME
+            : `git config enmetu.${error.key ?? ''} (${error.gitScope})`;
+        deps.stderr.write(`enmetu: ignoring ${source} (${error.code}: ${error.message}); using the defaults for this check\n`);
         return DEFAULT_CONFIG;
     }
 }

package/dist/cli/commands/runCommand.d.ts

@@ -1,4 +1,4 @@
-import type { EnmetuConfig } from '../../contracts/config.js';
+import type { EnmetuConfig, GitConfigEntry } from '../../contracts/config.js';
 import { type ExitCode } from '../../contracts/exitCode.js';
 import type { IDaemon } from '../../contracts/IDaemon.js';
 import type { IFileSystem } from '../../contracts/IFileSystem.js';
@@ -11,6 +11,8 @@ export interface RunCommandInput {
 export interface RunCommandDeps {
     readonly locator: IRepositoryLocator;
     readonly fs: IFileSystem;
+    /** Every enmetu.* entry of git config for the resolved repository (design 14.18). */
+    readonly readGitConfig: (paths: RepositoryPaths) => Promise<readonly GitConfigEntry[]>;
     readonly logger: ILogger;
     /** Composition-root closure; builds the daemon for the resolved repository. */
     readonly createDaemon: (paths: RepositoryPaths, config: EnmetuConfig) => IDaemon;
@@ -27,7 +29,13 @@ export declare const MIN_GIT_VERSION: {
  * Controller:
  * 1. locator.locate(startDir): not a repository, bare, or PATH_UNSUPPORTED log NOT_ELIGIBLE, exit 5.
  * 2. Git older than 2.38: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
- * 3. parseConfig of <root>/enmetu.config.json: ConfigError logs CONFIG_INVALID, exit 2.
+ * 3. parseConfig of <root>/enmetu.config.json and readGitConfig(paths), git
+ *    config overriding the file (design 14.18): ConfigError logs
+ *    CONFIG_INVALID naming the file or the git config key and scope, exit 2;
+ *    each unknown key of the file, each key of the file only git config may
+ *    set and each unknown enmetu.* key of git config logs CONFIG_KEY_IGNORED
+ *    once and is ignored (design 14.17); each setting git config set logs
+ *    CONFIG_FROM_GIT with its scope.
  * 4. createDaemon(paths, config).run(), its exit code returned.
  */
 export declare function runCommand(input: RunCommandInput, deps: RunCommandDeps): Promise<RunCommandResult>;

package/dist/cli/commands/runCommand.js

@@ -8,7 +8,13 @@ export const MIN_GIT_VERSION = { major: 2, minor: 38 };
  * Controller:
  * 1. locator.locate(startDir): not a repository, bare, or PATH_UNSUPPORTED log NOT_ELIGIBLE, exit 5.
  * 2. Git older than 2.38: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
- * 3. parseConfig of <root>/enmetu.config.json: ConfigError logs CONFIG_INVALID, exit 2.
+ * 3. parseConfig of <root>/enmetu.config.json and readGitConfig(paths), git
+ *    config overriding the file (design 14.18): ConfigError logs
+ *    CONFIG_INVALID naming the file or the git config key and scope, exit 2;
+ *    each unknown key of the file, each key of the file only git config may
+ *    set and each unknown enmetu.* key of git config logs CONFIG_KEY_IGNORED
+ *    once and is ignored (design 14.17); each setting git config set logs
+ *    CONFIG_FROM_GIT with its scope.
  * 4. createDaemon(paths, config).run(), its exit code returned.
  */
 export async function runCommand(input, deps) {
@@ -34,26 +40,66 @@ export async function runCommand(input, deps) {
     if (olderThanMinimum(version)) {
         return notEligible(deps, 'GIT_TOO_OLD', `git ${version.major}.${version.minor}.${version.patch} is older than ${MIN_GIT_VERSION.major}.${MIN_GIT_VERSION.minor}`);
     }
-    // --- Step 3: the config at the resolved root, defaults when absent ---
+    // --- Step 3: the config at the resolved root, then git config over it ---
     const configPath = join(paths.root, CONFIG_FILE_NAME);
-    let config;
+    let parsed;
     try {
-        config = parseConfig(await deps.fs.readText(configPath));
+        parsed = parseConfig(await deps.fs.readText(configPath), await deps.readGitConfig(paths));
     }
     catch (error) {
         if (!(error instanceof ConfigError)) {
             throw error;
         }
+        const source = error.gitScope === null
+            ? configPath
+            : `git config enmetu.${error.key ?? ''} (${error.gitScope})`;
         deps.logger.log({
             level: 'ERROR',
             code: 'CONFIG_INVALID',
-            message: `${configPath}: ${error.code}: ${error.message}`,
+            message: `${source}: ${error.code}: ${error.message}`,
         });
         return { exitCode: EXIT.USAGE };
     }
+    logConfigSources(parsed, deps.logger);
+    const { config } = parsed;
     // --- Step 4: the daemon for this repository ---
     return { exitCode: await deps.createDaemon(paths, config).run() };
 }
+/**
+ * Step 3's lines, before the daemon starts: what was ignored, then every
+ * setting git config set, so nobody wonders why one clone behaves differently.
+ */
+function logConfigSources(parsed, logger) {
+    // A key only a newer enmetu knows must not stop this one (design 14.17).
+    for (const key of parsed.unknownKeys) {
+        logger.log({
+            level: 'WARN',
+            code: 'CONFIG_KEY_IGNORED',
+            message: `${CONFIG_FILE_NAME}: unknown setting "${key}", ignored`,
+        });
+    }
+    for (const key of parsed.gitOnlyKeysInFile) {
+        logger.log({
+            level: 'WARN',
+            code: 'CONFIG_KEY_IGNORED',
+            message: `${CONFIG_FILE_NAME}: ${key} is read from git config only, ignored`,
+        });
+    }
+    for (const { key, scope } of parsed.unknownGitKeys) {
+        logger.log({
+            level: 'WARN',
+            code: 'CONFIG_KEY_IGNORED',
+            message: `git config (${scope}): unknown setting "${key}", ignored`,
+        });
+    }
+    for (const { key, scope, shown } of parsed.fromGit) {
+        logger.log({
+            level: 'INFO',
+            code: 'CONFIG_FROM_GIT',
+            message: `${key} ${shown} (git config, ${scope})`,
+        });
+    }
+}
 function olderThanMinimum(version) {
     return (version.major < MIN_GIT_VERSION.major ||
         (version.major === MIN_GIT_VERSION.major &&

package/dist/cli/exitCodes.js

@@ -4,7 +4,6 @@ import { EXIT } from '../contracts/exitCode.js';
 const EXIT_CODE_BY_ERROR = {
     USAGE: EXIT.USAGE,
     CONFIG_INVALID_JSON: EXIT.USAGE,
-    CONFIG_UNKNOWN_KEY: EXIT.USAGE,
     CONFIG_INVALID_VALUE: EXIT.USAGE,
     HALTED: EXIT.HALTED,
     LOCK_HELD: EXIT.LOCKED,

package/dist/cli.js

@@ -26,6 +26,8 @@ const runtime = {
     // an empty path, finds no CLI there and lets commits through (fail open).
     cliPath: process.argv[1] ?? '',
     version: packageVersion(),
+    platform: process.platform,
+    engine: process.versions.bun === undefined ? 'node' : 'bun',
     stdout: process.stdout,
     stderr: process.stderr,
 };

package/dist/commit/commitLocalChangesController.d.ts

@@ -1,14 +1,17 @@
-import type { StagedSelectionMode } from '../contracts/config.js';
 import type { IClock } from '../contracts/IClock.js';
+import type { ICommitMessageCommand } from '../contracts/ICommitMessageCommand.js';
 import type { IFileSystem } from '../contracts/IFileSystem.js';
 import type { IGitCommitter, IGitHookRunner } from '../contracts/IGitCommitter.js';
 import type { IGitIndexLock } from '../contracts/IGitIndexLock.js';
 import type { IGitReader } from '../contracts/IGitReader.js';
 import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { IHostMessageWriter } from '../contracts/IHostMessageWriter.js';
 import type { ILogger } from '../contracts/ILogger.js';
 import type { CommitMemory, WaitReason } from '../contracts/syncTypes.js';
 /** An unchanged tree a hook rejected is offered to the hooks again after this long (design 12.7). */
 export declare const HOOK_RETRY_MS = 600000;
+/** commitMessageCommand reads at most this much of the patch on stdin (design 14.18). */
+export declare const MESSAGE_PATCH_CAP_BYTES = 65536;
 export interface CommitLocalChangesInput {
     readonly cycleId: string;
     readonly memory: CommitMemory;
@@ -32,9 +35,11 @@ export interface CommitIndexGit {
 }
 export interface CommitSettings {
     readonly commitSubject: string;
+    /** null: the message is commitSubject alone (design 14.18). */
+    readonly commitMessageCommand: string | null;
     readonly skipJsonCheck: readonly string[];
-    readonly stagedSelection: StagedSelectionMode;
-    readonly stagedSelectionMaxWaitMs: number | null;
+    /** How long a partial staging holds the commit back; 0 commits at once (design 14.17). */
+    readonly partialStagingWaitMs: number;
     readonly commitHooks: boolean;
     /** <gitDir>/index, copied to seed the commit index with its stat data. */
     readonly realIndex: string;
@@ -50,6 +55,10 @@ export interface CommitLocalChangesDeps {
     /** Hooks on the real index: post-commit and post-index-change run after the branch moved. */
     readonly realHooks: IGitHookRunner;
     readonly indexLock: IGitIndexLock;
+    /** Runs commitMessageCommand; called only when it is set (design 14.18). */
+    readonly messageCommand: ICommitMessageCommand;
+    /** The host program's writer (library option commitMessage); null for the CLI (design 14.19). */
+    readonly hostMessage: IHostMessageWriter | null;
     readonly fs: IFileSystem;
     readonly logger: ILogger;
     /** NullLogger from the root: the residue build must not log EXCLUDED a second time. */
@@ -93,9 +102,10 @@ export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<Com
  *    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.
+ *    person's selection. While less than partialStagingWaitMs has passed
+ *    since memory.partialStagingSince (the first cycle that saw the staging)
+ *    it returns waiting PARTIAL_SELECTION_STAGED; once it has passed it logs
+ *    SELECTION_WAIT_ENDED and goes on; 0 goes on at once (design 14.17).
  * 2. Build: parent = git.headCommit(); fs.copy(realIndex, commit index);
  *    committer.seedFrom(parent); stageGuardedChanges on the commit index.
  *    Nothing staged returns nothing.
@@ -105,9 +115,20 @@ export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<Com
  * 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.
+ * 4b. The message (design 14.18, 14.19), before index.lock, so no writer
+ *    ever holds up a person's git. The command's message: when
+ *    commitMessageCommand is set, messageCommand runs with
+ *    git.patch(parent, tree, MESSAGE_PATCH_CAP_BYTES) on stdin and
+ *    messageFromText turns its stdout into the message; a failed patch, a
+ *    failed command or output messageFromText refuses log one
+ *    MESSAGE_COMMAND_FAILED line and give none. Without hostMessage: the
+ *    command's message, else commitSubject plus a newline. With hostMessage:
+ *    its write decides, given a runCommand that yields the command's message,
+ *    run at most once however often it is called; declined is commitSubject;
+ *    failed, or text messageFromText refuses, logs MESSAGE_WRITER_FAILED and
+ *    is commitSubject.
  * 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

package/dist/commit/commitLocalChangesController.js

@@ -1,10 +1,12 @@
 import { EnmetuError, GitCommandError } from '../contracts/errors.js';
 import { withLastMove } from '../core/commit/commitMemory.js';
-import { gitBoolean } from '../core/commit/commitMessage.js';
+import { gitBoolean, messageFromText } 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;
+/** commitMessageCommand reads at most this much of the patch on stdin (design 14.18). */
+export const MESSAGE_PATCH_CAP_BYTES = 65536;
 /**
  * Controller: enmetu's commit without touching the person's index (design
  * 12.7, Decisions 72 to 74, 80, 81).
@@ -15,9 +17,10 @@ export const HOOK_RETRY_MS = 600000;
  *    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.
+ *    person's selection. While less than partialStagingWaitMs has passed
+ *    since memory.partialStagingSince (the first cycle that saw the staging)
+ *    it returns waiting PARTIAL_SELECTION_STAGED; once it has passed it logs
+ *    SELECTION_WAIT_ENDED and goes on; 0 goes on at once (design 14.17).
  * 2. Build: parent = git.headCommit(); fs.copy(realIndex, commit index);
  *    committer.seedFrom(parent); stageGuardedChanges on the commit index.
  *    Nothing staged returns nothing.
@@ -27,9 +30,20 @@ export const HOOK_RETRY_MS = 600000;
  * 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.
+ * 4b. The message (design 14.18, 14.19), before index.lock, so no writer
+ *    ever holds up a person's git. The command's message: when
+ *    commitMessageCommand is set, messageCommand runs with
+ *    git.patch(parent, tree, MESSAGE_PATCH_CAP_BYTES) on stdin and
+ *    messageFromText turns its stdout into the message; a failed patch, a
+ *    failed command or output messageFromText refuses log one
+ *    MESSAGE_COMMAND_FAILED line and give none. Without hostMessage: the
+ *    command's message, else commitSubject plus a newline. With hostMessage:
+ *    its write decides, given a runCommand that yields the command's message,
+ *    run at most once however often it is called; declined is commitSubject;
+ *    failed, or text messageFromText refuses, logs MESSAGE_WRITER_FAILED and
+ *    is commitSubject.
  * 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
@@ -73,24 +87,22 @@ export async function commitLocalChangesController(input, deps) {
         }
     }
     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 wait = settings.partialStagingWaitMs;
+    if (staged && wait > 0) {
+        since = memory.partialStagingSince ?? now;
+        if (now - since < wait) {
+            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 ${wait} 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 ---
@@ -131,7 +143,7 @@ export async function commitLocalChangesController(input, deps) {
                 kind: 'waiting',
                 reason: 'COMMIT_HOOK_REJECTED',
                 memory: {
-                    stagedSelectionSince: since,
+                    partialStagingSince: since,
                     rejection: { tree, at: now },
                     residueTree: memory.residueTree,
                     lastMove: memory.lastMove,
@@ -149,12 +161,15 @@ export async function commitLocalChangesController(input, deps) {
         }
         tree = await deps.commitIndex.committer.writeTree();
     }
+    // --- Step 4b: the message, outside the lock ---
+    const message = await commitMessage(parent, tree, cycleId, deps);
     // --- 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).
+    // enmetu itself puts no path into the message (D1); a person's
+    // commitMessageCommand may (design 14.18).
     const commit = await deps.commitIndex.committer.commitTree({
         tree,
         parent,
-        message: `${settings.commitSubject}\n`,
+        message,
         sign: gitBoolean(await deps.git.configValue('commit.gpgSign')),
     });
     // --- Step 6: critical section under git's own index.lock ---
@@ -178,7 +193,7 @@ export async function commitLocalChangesController(input, deps) {
     return {
         kind: 'committed',
         memory: {
-            stagedSelectionSince: null,
+            partialStagingSince: null,
             rejection: null,
             residueTree,
             lastMove: { from: parent, to: commit },
@@ -213,6 +228,99 @@ async function runPostCommitHooks(commit, tree, cycleId, deps) {
     const residue = await deps.commitIndex.committer.writeTree();
     return residue === tree ? null : residue;
 }
+/**
+ * Step 4b (design 14.18, 14.19): the message. Without a host writer, the
+ * person's commitMessageCommand's, else commitSubject. With one, the
+ * writer's: it decides, and the person's command runs only when the writer
+ * asks for it, at most once. Messages are optional and cosmetic, so nothing
+ * about them ever stops a commit: every failure falls back to commitSubject
+ * with one line.
+ */
+async function commitMessage(parent, tree, cycleId, deps) {
+    const subjectOnly = `${deps.settings.commitSubject}\n`;
+    if (deps.hostMessage === null) {
+        return (await commandMessage(parent, tree, cycleId, deps)) ?? subjectOnly;
+    }
+    let command = null;
+    const run = await deps.hostMessage.write({
+        parent,
+        tree,
+        runCommand: () => {
+            command ??= commandMessage(parent, tree, cycleId, deps);
+            return command;
+        },
+    });
+    if (run.kind === 'declined') {
+        return subjectOnly;
+    }
+    let failure;
+    if (run.kind === 'failed') {
+        failure = run.detail;
+    }
+    else {
+        const parsed = messageFromText(run.text);
+        if (parsed.kind === 'message') {
+            return parsed.message;
+        }
+        failure = `returned ${parsed.reason}`;
+    }
+    deps.logger.log({
+        level: 'WARN',
+        code: 'MESSAGE_WRITER_FAILED',
+        message: `the host program's commitMessage ${failure}; committing with commitSubject`,
+        cycleId,
+    });
+    return subjectOnly;
+}
+/**
+ * commitMessageCommand on the patch from the parent to the tree (design
+ * 14.18, Decision 131): its message, or null when the setting is unset or
+ * anything failed, a failure logged once as MESSAGE_COMMAND_FAILED naming
+ * what comes instead: commitSubject, or the host writer's own message.
+ */
+async function commandMessage(parent, tree, cycleId, deps) {
+    const { commitMessageCommand } = deps.settings;
+    if (commitMessageCommand === null) {
+        return null;
+    }
+    let failure;
+    try {
+        const stdin = await deps.git.patch(parent, tree, MESSAGE_PATCH_CAP_BYTES);
+        const run = await deps.messageCommand.run({
+            command: commitMessageCommand,
+            stdin,
+            parent,
+            tree,
+        });
+        if (run.kind === 'failed') {
+            failure = run.detail;
+        }
+        else {
+            const parsed = messageFromText(run.stdout);
+            if (parsed.kind === 'message') {
+                return parsed.message;
+            }
+            failure = `printed ${parsed.reason}`;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof GitCommandError)) {
+            throw error;
+        }
+        failure = `got no patch (${error.message})`;
+    }
+    // With a host writer the fallback is the writer's, not commitSubject.
+    const next = deps.hostMessage === null
+        ? 'committing with commitSubject'
+        : "the host program's commitMessage writes the message";
+    deps.logger.log({
+        level: 'WARN',
+        code: 'MESSAGE_COMMAND_FAILED',
+        message: `commitMessageCommand ${failure}; ${next}`,
+        cycleId,
+    });
+    return null;
+}
 /**
  * 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
@@ -347,7 +455,7 @@ async function rollBack(branchRef, commit, parent, cycleId, deps) {
 }
 function rememberSince(memory, since) {
     return {
-        stagedSelectionSince: since,
+        partialStagingSince: since,
         rejection: memory.rejection,
         residueTree: memory.residueTree,
         lastMove: memory.lastMove,

package/dist/contracts/ICommitMessageCommand.d.ts

@@ -0,0 +1,32 @@
+export interface CommitMessageCommandInput {
+    /** commitMessageCommand, run by the shell in the repository root. */
+    readonly command: string;
+    /** Written to the command's stdin, then stdin is closed. */
+    readonly stdin: Buffer;
+    /** The commit's parent, as ENMETU_PARENT. */
+    readonly parent: string;
+    /** The commit's tree, as ENMETU_TREE. */
+    readonly tree: string;
+}
+export type CommitMessageCommandRun = 
+/** Exit code 0; stdout up to the output cap. */
+{
+    readonly kind: 'printed';
+    readonly stdout: string;
+}
+/**
+ * Not started, a non-zero exit, a signal, the time limit, or a stop
+ * request; detail says which, with the first line of stderr when there is one.
+ */
+ | {
+    readonly kind: 'failed';
+    readonly detail: string;
+};
+/**
+ * Runs commitMessageCommand for one commit (design 14.18): a shell command
+ * leading its own process group, ended with the whole group at the time
+ * limit or a stop request. Never throws.
+ */
+export interface ICommitMessageCommand {
+    run(input: CommitMessageCommandInput): Promise<CommitMessageCommandRun>;
+}

package/dist/contracts/ICommitMessageCommand.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitConfigReader.d.ts

@@ -1,5 +1,8 @@
-/** The one git question the hook installer needs; it cannot write configuration through it. */
+import type { GitConfigEntry } from './config.js';
+/** The git config questions enmetu asks; it cannot write configuration through it. */
 export interface IGitConfigReader {
     /** null when unset at every scope. */
     configValue(key: string): Promise<string | null>;
+    /** Every enmetu.* entry at every scope, in git's reading order; none set: empty (design 14.18). */
+    enmetuEntries(): Promise<readonly GitConfigEntry[]>;
 }

package/dist/contracts/IGitReader.d.ts

@@ -78,4 +78,9 @@ export interface IGitReader extends IGitConfigReader {
     mergeBase(left: string, right: string): Promise<string | null>;
     /** Root-relative paths that differ between two commits, a rename being a delete plus an add, in git's order. */
     changedPaths(from: string, to: string): Promise<readonly string[]>;
+    /**
+     * `git diff-tree -p` from a commit to a tree, without colour, external
+     * diffs or textconv; the first maxBytes bytes, the rest dropped (design 14.18).
+     */
+    patch(from: string, toTree: string, maxBytes: number): Promise<Buffer>;
 }

package/dist/contracts/IHostMessageWriter.d.ts

@@ -0,0 +1,28 @@
+export interface HostMessageInput {
+    readonly parent: string;
+    readonly tree: string;
+    /** The person's command for this change, its message or null; see CommitChange.runCommand. */
+    readonly runCommand: () => Promise<string | null>;
+}
+export type HostMessageRun = 
+/** The writer returned text; enmetu still checks that it holds a subject. */
+{
+    readonly kind: 'wrote';
+    readonly text: string;
+}
+/** The writer returned null: commitSubject, nothing logged. */
+ | {
+    readonly kind: 'declined';
+}
+/** A throw, the time limit, a stop request or a value that is neither text nor null. */
+ | {
+    readonly kind: 'failed';
+    readonly detail: string;
+};
+/**
+ * The host program's commit message writer (EnmetuStartOptions.commitMessage)
+ * with its time limit, behind one call that never throws (design 14.19).
+ */
+export interface IHostMessageWriter {
+    write(input: HostMessageInput): Promise<HostMessageRun>;
+}

package/dist/contracts/IHostMessageWriter.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IRepositoryLocator.d.ts

@@ -3,7 +3,11 @@ export interface RepositoryPaths {
     readonly root: string;
     /** Per worktree; state files live under it. */
     readonly gitDir: string;
-    /** Effective hooks directory (honours core.hooksPath). */
+    /**
+     * The repository's own hooks directory, <git common dir>/hooks, whatever
+     * core.hooksPath says; git runs hooks from it only while core.hooksPath is
+     * unset, which is also the only case the installer writes there (design 14.17).
+     */
     readonly hooksDir: string;
     /** <gitDir>/enmetu */
     readonly stateDir: string;