@fluado/enmetu 0.2.0 → 0.4.0

package/dist/contracts/config.d.ts

@@ -17,10 +17,43 @@ export interface EnmetuConfig {
     readonly commitHooks: boolean;
     /** How long one repository hook may run before it is a rejection (design 12.7, Decision 83). */
     readonly hookTimeoutMs: number;
+    /**
+     * A shell command that writes the commit message; null: commitSubject alone.
+     * Read from git config only, never from enmetu.config.json (design 14.18).
+     */
+    readonly commitMessageCommand: string | null;
+}
+/**
+ * One entry of `git config --show-scope --get-regexp ^enmetu\.`, in git's
+ * reading order (design 14.18). key is as git prints it: section and variable
+ * name lower case. value null: the key is written without a value.
+ */
+export interface GitConfigEntry {
+    readonly scope: string;
+    readonly key: string;
+    readonly value: string | null;
 }
-/** What parseConfig read: the config, and the keys it does not know, in file order (design 14.17). */
+/** A setting git config set: the start line names it with its scope (design 14.18). */
+export interface ConfigFromGit {
+    /** The setting's name as enmetu.config.json spells it, such as quietMs. */
+    readonly key: string;
+    readonly scope: string;
+    /** The value as the start line shows it; commitMessageCommand shows "set", never the command. */
+    readonly shown: string;
+}
+/** What parseConfig read: the config, and what it ignored, in reading order (design 14.17, 14.18). */
 export interface ParsedConfig {
     readonly config: EnmetuConfig;
     /** Ignored; the run command names each once at start. */
     readonly unknownKeys: readonly string[];
+    /** Keys of enmetu.config.json only git config may set (commitMessageCommand); ignored, named at start. */
+    readonly gitOnlyKeysInFile: readonly string[];
+    /** enmetu.* entries of git config enmetu does not know, once per key and scope; ignored, named at start. */
+    readonly unknownGitKeys: readonly GitConfigEntryName[];
+    /** Every setting git config set, in the order of the configuration table. */
+    readonly fromGit: readonly ConfigFromGit[];
+}
+export interface GitConfigEntryName {
+    readonly scope: string;
+    readonly key: string;
 }

package/dist/contracts/errors.d.ts

@@ -21,7 +21,11 @@ export declare class GitOutputError extends EnmetuError {
 }
 export declare class ConfigError extends EnmetuError {
     readonly key: string | null;
-    constructor(message: string, code: ConfigErrorCode, key: string | null);
+    /** The git config scope the invalid value came from; null: enmetu.config.json (design 14.18). */
+    readonly gitScope: string | null;
+    constructor(message: string, code: ConfigErrorCode, key: string | null, 
+    /** The git config scope the invalid value came from; null: enmetu.config.json (design 14.18). */
+    gitScope?: string | null);
 }
 export declare class PreflightError extends EnmetuError {
     constructor(message: string, code: PreflightErrorCode, cycleId?: string | undefined);

package/dist/contracts/errors.js

@@ -29,9 +29,13 @@ export class GitOutputError extends EnmetuError {
 }
 export class ConfigError extends EnmetuError {
     key;
-    constructor(message, code, key) {
+    gitScope;
+    constructor(message, code, key, 
+    /** The git config scope the invalid value came from; null: enmetu.config.json (design 14.18). */
+    gitScope = null) {
         super(message, code);
         this.key = key;
+        this.gitScope = gitScope;
         this.name = 'ConfigError';
     }
 }

package/dist/contracts/library.d.ts

@@ -9,6 +9,36 @@ export interface EnmetuStartOptions {
     readonly log?: ITextSink | undefined;
     /** The environment git children start from; default the process environment. */
     readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    /**
+     * Writes the message of each commit enmetu makes (design 14.19); without
+     * it, the person's commitMessageCommand does, else commitSubject.
+     */
+    readonly commitMessage?: CommitMessageWriter | undefined;
+}
+/**
+ * A host program's commit message writer (design 14.19). It returns the
+ * message, its first line the subject (at most 100 characters, not starting
+ * with #) and the lines after it the body, or null for commitSubject. It has
+ * 10 s; a throw, a timeout, or text without a subject also falls back to
+ * commitSubject, with one MESSAGE_WRITER_FAILED line.
+ */
+export type CommitMessageWriter = (change: CommitChange) => Promise<string | null>;
+/** One commit enmetu is about to make, as a host's writer sees it (design 14.19). */
+export interface CommitChange {
+    /** The repository root. */
+    readonly root: string;
+    /** The commit's only parent. */
+    readonly parent: string;
+    /** The commit's tree; `git diff-tree -r <parent> <tree>` lists the change. */
+    readonly tree: string;
+    /**
+     * The person's commitMessageCommand on this change: its message, or null
+     * when none is set or it failed (enmetu logs the failure). With a writer,
+     * the command runs only through this call, at most once per commit.
+     */
+    runCommand(): Promise<string | null>;
+    /** Aborted when the writer's time is up or enmetu stops. */
+    readonly signal: AbortSignal;
 }
 export interface EnmetuInstance {
     /**

package/dist/contracts/logCodes.d.ts

@@ -1 +1 @@
-export type LogCode = 'STARTED' | 'STOPPING' | 'STOPPED' | 'LOCK_STALE_TAKEN' | 'RECOVERED' | 'HOOK_INSTALLED' | 'HOOK_UPDATED' | 'HOOK_SKIPPED' | 'HOOK_FAILED' | 'WATCHER_FAILED' | 'COMMITTED' | 'STAGE_PARTIAL' | 'EXCLUDED' | 'PULLED' | 'PUSHED' | 'PUSH_REJECTED' | 'PUSH_FAILED' | 'OFFLINE' | 'CONFLICT' | 'UNPUSHED' | 'PAUSED' | 'BUSY' | 'RESUMED' | 'QUARANTINE_KEPT' | 'HALTED' | 'CYCLE_FAILED' | 'NOT_ELIGIBLE' | 'LOCKED' | 'CONFIG_INVALID' | 'CONFIG_KEY_IGNORED' | 'STATE_WRITE_FAILED' | 'WAITING' | 'SELECTION_WAIT_ENDED' | 'HOOK_REJECTED' | 'COMMIT_DISCARDED' | 'INDEX_REPAIRED' | 'QUARANTINE_UPSTREAM_CHANGED' | 'REBASE_NOT_STARTED' | 'STAGED_RESET' | 'STAGED_REVERT' | 'REBASE_BRANCH_MOVED' | 'COMMIT_ORPHANED';
+export type LogCode = 'STARTED' | 'STOPPING' | 'STOPPED' | 'LOCK_STALE_TAKEN' | 'RECOVERED' | 'HOOK_INSTALLED' | 'HOOK_UPDATED' | 'HOOK_SKIPPED' | 'HOOK_FAILED' | 'WATCHER_FAILED' | 'COMMITTED' | 'STAGE_PARTIAL' | 'EXCLUDED' | 'PULLED' | 'PUSHED' | 'PUSH_REJECTED' | 'PUSH_FAILED' | 'OFFLINE' | 'CONFLICT' | 'UNPUSHED' | 'PAUSED' | 'BUSY' | 'RESUMED' | 'QUARANTINE_KEPT' | 'HALTED' | 'CYCLE_FAILED' | 'NOT_ELIGIBLE' | 'LOCKED' | 'CONFIG_INVALID' | 'CONFIG_KEY_IGNORED' | 'CONFIG_FROM_GIT' | 'MESSAGE_COMMAND_FAILED' | 'MESSAGE_WRITER_FAILED' | 'STATE_WRITE_FAILED' | 'WAITING' | 'SELECTION_WAIT_ENDED' | 'HOOK_REJECTED' | 'COMMIT_DISCARDED' | 'INDEX_REPAIRED' | 'QUARANTINE_UPSTREAM_CHANGED' | 'REBASE_NOT_STARTED' | 'STAGED_RESET' | 'STAGED_REVERT' | 'REBASE_BRANCH_MOVED' | 'COMMIT_ORPHANED' | 'HELD' | 'RESTORED';

package/dist/contracts/runtime.d.ts

@@ -11,6 +11,10 @@ export interface Runtime {
     /** Absolute path of the CLI script (Node resolves argv[1]), recorded in the hook. */
     readonly cliPath: string;
     readonly version: string;
+    /** process.platform: 'linux', 'darwin', 'win32', ... */
+    readonly platform: string;
+    /** The JavaScript runtime enmetu runs on: 'bun' when process.versions.bun is set. */
+    readonly engine: 'node' | 'bun';
     readonly stdout: ITextSink;
     readonly stderr: ITextSink;
 }

package/dist/contracts/syncTypes.d.ts

@@ -11,11 +11,30 @@ export type PauseReason = 'FOREIGN_OPERATION' | 'DETACHED_HEAD' | 'NO_UPSTREAM'
  */
  | 'REBASE_REFUSED';
 /**
- * Why a cycle committed nothing although the tree has changes (design 12.7):
- * a person has a selection staged and partialStagingWaitMs has not passed
- * (design 14.17), or a repository commit hook rejected enmetu's commit.
+ * Why a cycle did less than everything although the tree has changes (design
+ * 12.7): a person has a selection staged and partialStagingWaitMs has not
+ * passed (design 14.17), a repository commit hook rejected enmetu's commit, or
+ * a file was saved while the cycle ran and the pull waits for a cycle that
+ * finds nothing new to commit (design 14.21, Decision 147).
  */
-export type WaitReason = 'PARTIAL_SELECTION_STAGED' | 'COMMIT_HOOK_REJECTED';
+export type WaitReason = 'PARTIAL_SELECTION_STAGED' | 'COMMIT_HOOK_REJECTED' | 'TREE_CHANGING';
+/**
+ * Which dirty tracked paths integrate may set aside for a pull (design 14.21,
+ * Decision 147): the ones the commit step could not commit this cycle. Any
+ * other dirty path is a save that landed during the cycle, and the pull waits.
+ */
+export type HoldPolicy = 
+/** Exactly these paths (the content guard's EXCLUDED paths); empty when the cycle committed everything or found nothing. */
+{
+    readonly kind: 'only';
+    readonly paths: readonly string[];
+}
+/** Every dirty tracked path: a commit hook rejected the commit, or the hooks' residue is all that changed. */
+ | {
+    readonly kind: 'all';
+};
+/** The policy after a clean status: any dirty path at the pull is a save made during the cycle. */
+export declare const HOLD_NOTHING: HoldPolicy;
 export type CycleOutcome = {
     readonly kind: 'synced';
 } | {

package/dist/contracts/syncTypes.js

@@ -1,3 +1,5 @@
+/** The policy after a clean status: any dirty path at the pull is a save made during the cycle. */
+export const HOLD_NOTHING = { kind: 'only', paths: [] };
 export const EMPTY_COMMIT_MEMORY = {
     partialStagingSince: null,
     rejection: null,

package/dist/core/commit/commitMessage.d.ts

@@ -1,6 +1,33 @@
+/** The longest subject enmetu commits with, from commitSubject or commitMessageCommand. */
+export declare const MAX_SUBJECT_CHARACTERS = 100;
 /**
  * git's boolean config reading for commit.gpgSign: true, yes, on, 1 (any
  * case) and '' (a key written without a value) are true; null (unset) and
  * everything else are false.
  */
 export declare function gitBoolean(value: string | null): boolean;
+/**
+ * One line of 1 to MAX_SUBJECT_CHARACTERS characters, not blank and not
+ * starting with #. git aborts a commit whose message is empty after cleanup,
+ * and a person's commit.cleanup=strip removes a line starting with #.
+ */
+export declare function isCommitSubject(value: string): boolean;
+export type ParsedMessage = {
+    readonly kind: 'message';
+    readonly message: string;
+}
+/** What the text holds instead, read after "printed" or "returned", such as "no subject". */
+ | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+/**
+ * A message writer's text as a commit message: commitMessageCommand's stdout
+ * (design 14.18) or a host program's return value (design 14.19). Line
+ * endings become \n, every line loses its trailing whitespace, the subject
+ * its leading whitespace too; the first non-blank line is the subject, the
+ * lines after it, without the blank lines around them, the body. Refused: no
+ * subject, a NUL byte (git refuses one in a message), or a subject
+ * isCommitSubject refuses.
+ */
+export declare function messageFromText(text: string): ParsedMessage;

package/dist/core/commit/commitMessage.js

@@ -1,4 +1,6 @@
 const GIT_TRUE = ['true', 'yes', 'on', '1', ''];
+/** The longest subject enmetu commits with, from commitSubject or commitMessageCommand. */
+export const MAX_SUBJECT_CHARACTERS = 100;
 /**
  * git's boolean config reading for commit.gpgSign: true, yes, on, 1 (any
  * case) and '' (a key written without a value) are true; null (unset) and
@@ -10,3 +12,62 @@ export function gitBoolean(value) {
     }
     return GIT_TRUE.includes(value.toLowerCase());
 }
+/**
+ * One line of 1 to MAX_SUBJECT_CHARACTERS characters, not blank and not
+ * starting with #. git aborts a commit whose message is empty after cleanup,
+ * and a person's commit.cleanup=strip removes a line starting with #.
+ */
+export function isCommitSubject(value) {
+    const characters = Array.from(value).length;
+    return (characters >= 1 &&
+        characters <= MAX_SUBJECT_CHARACTERS &&
+        !/[\r\n]/.test(value) &&
+        !value.startsWith('#') &&
+        value.trim() !== '');
+}
+/**
+ * A message writer's text as a commit message: commitMessageCommand's stdout
+ * (design 14.18) or a host program's return value (design 14.19). Line
+ * endings become \n, every line loses its trailing whitespace, the subject
+ * its leading whitespace too; the first non-blank line is the subject, the
+ * lines after it, without the blank lines around them, the body. Refused: no
+ * subject, a NUL byte (git refuses one in a message), or a subject
+ * isCommitSubject refuses.
+ */
+export function messageFromText(text) {
+    if (text.includes('\0')) {
+        return { kind: 'refused', reason: 'a NUL byte' };
+    }
+    const lines = withoutOuterBlankLines(text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.trimEnd()));
+    const subject = (lines[0] ?? '').trim();
+    if (subject === '') {
+        return { kind: 'refused', reason: 'no subject' };
+    }
+    if (!isCommitSubject(subject)) {
+        return {
+            kind: 'refused',
+            reason: subject.startsWith('#')
+                ? 'a subject starting with #'
+                : `a subject of ${Array.from(subject).length} characters, more than ${MAX_SUBJECT_CHARACTERS}`,
+        };
+    }
+    const body = withoutOuterBlankLines(lines.slice(1)).join('\n');
+    return {
+        kind: 'message',
+        message: body === '' ? `${subject}\n` : `${subject}\n\n${body}\n`,
+    };
+}
+function withoutOuterBlankLines(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start] === '') {
+        start += 1;
+    }
+    while (end > start && lines[end - 1] === '') {
+        end -= 1;
+    }
+    return lines.slice(start, end);
+}

package/dist/core/config/parseConfig.d.ts

@@ -1,8 +1,11 @@
-import type { EnmetuConfig, ParsedConfig } from '../../contracts/config.js';
+import type { EnmetuConfig, GitConfigEntry, ParsedConfig } from '../../contracts/config.js';
 export declare const CONFIG_FILE_NAME = "enmetu.config.json";
 export declare const DEFAULT_CONFIG: EnmetuConfig;
 /**
- * text null: the file is absent, every default applies. Throws ConfigError
- * for text that does not parse and for an invalid value of a known key.
+ * text null: the file is absent. gitEntries: every enmetu.* entry of git
+ * config, in git's reading order; a setting there replaces the file's and is
+ * checked the same way (design 14.18). Throws ConfigError for text that does
+ * not parse and for an invalid value of a known key, with gitScope set when
+ * git config gave the value.
  */
-export declare function parseConfig(text: string | null): ParsedConfig;
+export declare function parseConfig(text: string | null, gitEntries?: readonly GitConfigEntry[]): ParsedConfig;

package/dist/core/config/parseConfig.js

@@ -1,4 +1,5 @@
 import { ConfigError } from '../../contracts/errors.js';
+import { isCommitSubject, MAX_SUBJECT_CHARACTERS, } from '../commit/commitMessage.js';
 import { errorMessage } from '../errors/errorMessage.js';
 import { MAX_STATE_HISTORY } from '../state/stateRecordStep.js';
 export const CONFIG_FILE_NAME = 'enmetu.config.json';
@@ -14,6 +15,7 @@ export const DEFAULT_CONFIG = {
     partialStagingWaitMs: 300000,
     commitHooks: true,
     hookTimeoutMs: 600000,
+    commitMessageCommand: null,
 };
 const KNOWN_KEYS = [
     'quietMs',
@@ -27,29 +29,93 @@ const KNOWN_KEYS = [
     'partialStagingWaitMs',
     'commitHooks',
     'hookTimeoutMs',
+    'commitMessageCommand',
 ];
-const MAX_SUBJECT_CHARACTERS = 100;
+/**
+ * Set by git config alone: a repository's file must never make a person's
+ * machine run a program (design 14.18).
+ */
+const GIT_ONLY_KEYS = ['commitMessageCommand'];
+/** How a git config value is read; every other key is an integer (design 14.18). */
+const BOOLEAN_KEYS = ['installHook', 'commitHooks'];
+const TEXT_KEYS = [
+    'commitSubject',
+    'commitMessageCommand',
+];
+const LIST_KEYS = ['skipJsonCheck'];
+/** git's spellings of true and false; a key written without a value is true. */
+const GIT_TRUE_WORDS = ['true', 'yes', 'on', '1'];
+const GIT_FALSE_WORDS = ['false', 'no', 'off', '0', ''];
+const GIT_SECTION = 'enmetu.';
 /** The range of hookTimeoutMs: one second to one day (design 12.7). */
 const MIN_HOOK_TIMEOUT_MS = 1000;
 const MAX_HOOK_TIMEOUT_MS = 86400000;
 /**
- * text null: the file is absent, every default applies. Throws ConfigError
- * for text that does not parse and for an invalid value of a known key.
+ * text null: the file is absent. gitEntries: every enmetu.* entry of git
+ * config, in git's reading order; a setting there replaces the file's and is
+ * checked the same way (design 14.18). Throws ConfigError for text that does
+ * not parse and for an invalid value of a known key, with gitScope set when
+ * git config gave the value.
  */
-export function parseConfig(text) {
-    if (text === null) {
-        return { config: DEFAULT_CONFIG, unknownKeys: [] };
+export function parseConfig(text, gitEntries = []) {
+    const file = text === null ? {} : fileSettings(text);
+    const fileKeys = Object.keys(file);
+    // Ignored rather than refused, so a key only a newer enmetu knows never
+    // stops an older one; the caller names each, so a typo is not silent
+    // (design 14.17).
+    const unknownKeys = fileKeys.filter((key) => configKey(key) === null);
+    const gitOnlyKeysInFile = fileKeys.filter((key) => isGitOnly(key));
+    const git = gitSettings(gitEntries);
+    const settings = {};
+    for (const key of fileKeys) {
+        if (configKey(key) !== null && !isGitOnly(key)) {
+            settings[key] = file[key];
+        }
+    }
+    for (const setting of git.settings) {
+        settings[setting.key] = setting.value;
     }
+    const config = configWithScope(settings, git.settings);
+    return {
+        config,
+        unknownKeys,
+        gitOnlyKeysInFile,
+        unknownGitKeys: git.unknown,
+        fromGit: git.settings.map((setting) => ({
+            key: setting.key,
+            scope: setting.scope,
+            shown: shownValue(setting.key, config),
+        })),
+    };
+}
+function fileSettings(text) {
     const parsed = parseJson(text);
     if (!isRecord(parsed)) {
         throw new ConfigError('the top level must be a JSON object', 'CONFIG_INVALID_VALUE', null);
     }
-    // Ignored rather than refused, so a key only a newer enmetu knows never
-    // stops an older one; the caller names each, so a typo is not silent
-    // (design 14.17).
-    const unknownKeys = Object.keys(parsed).filter((key) => !KNOWN_KEYS.includes(key));
+    return parsed;
+}
+/** The checks of every key, with the scope of a git config value named in the error. */
+function configWithScope(settings, git) {
+    try {
+        return configOf(settings);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError)) {
+            throw error;
+        }
+        const { key } = error;
+        const scope = git.find((setting) => setting.key === key)?.scope;
+        if (scope === undefined) {
+            throw error;
+        }
+        // Only invalid() names a key, and it always throws CONFIG_INVALID_VALUE.
+        throw new ConfigError(error.message, 'CONFIG_INVALID_VALUE', key, scope);
+    }
+}
+function configOf(parsed) {
     const quietMs = readInteger(parsed, 'quietMs', 100, 600000);
-    const config = {
+    return {
         quietMs,
         maxDelayMs: readInteger(parsed, 'maxDelayMs', quietMs, 3600000),
         pollMs: readInteger(parsed, 'pollMs', 100, 3600000),
@@ -61,8 +127,89 @@ export function parseConfig(text) {
         partialStagingWaitMs: readPartialStagingWaitMs(parsed),
         commitHooks: readBoolean(parsed, 'commitHooks'),
         hookTimeoutMs: readHookTimeoutMs(parsed),
+        commitMessageCommand: readCommitMessageCommand(parsed),
     };
-    return { config, unknownKeys };
+}
+/**
+ * The enmetu.* entries of git config as settings, in KNOWN_KEYS order, and
+ * the entries enmetu does not know (a subsection is unknown too). git's rule
+ * decides between scopes: the last value read wins, so a local value beats a
+ * global one; a list is every value of that last scope, so a local list
+ * replaces a global one as a whole.
+ */
+function gitSettings(entries) {
+    const unknown = [];
+    const byKey = new Map();
+    for (const entry of entries) {
+        const key = gitConfigKey(entry.key);
+        if (key === null) {
+            if (!unknown.some((name) => name.key === entry.key && name.scope === entry.scope)) {
+                unknown.push({ scope: entry.scope, key: entry.key });
+            }
+            continue;
+        }
+        byKey.set(key, [...(byKey.get(key) ?? []), entry]);
+    }
+    const settings = [];
+    for (const key of KNOWN_KEYS) {
+        const set = byKey.get(key) ?? [];
+        const last = set[set.length - 1];
+        if (last === undefined) {
+            continue;
+        }
+        const value = LIST_KEYS.includes(key)
+            ? set
+                .filter((entry) => entry.scope === last.scope)
+                .map((entry) => entry.value)
+            : gitValue(key, last.value);
+        settings.push({ key, scope: last.scope, value });
+    }
+    return { settings, unknown };
+}
+/** enmetu.quietms (git prints the variable name lower case) to quietMs; null for anything else. */
+function gitConfigKey(gitKey) {
+    if (!gitKey.toLowerCase().startsWith(GIT_SECTION)) {
+        return null;
+    }
+    const name = gitKey.slice(GIT_SECTION.length).toLowerCase();
+    return KNOWN_KEYS.find((key) => key.toLowerCase() === name) ?? null;
+}
+/**
+ * A git config value as the JSON value it stands for, so the file's checks
+ * apply unchanged: digits become an integer, git's boolean words a boolean;
+ * anything else stays text, which the check of a number or boolean refuses.
+ */
+function gitValue(key, value) {
+    if (TEXT_KEYS.includes(key)) {
+        return value;
+    }
+    if (BOOLEAN_KEYS.includes(key)) {
+        if (value === null) {
+            return true;
+        }
+        const word = value.toLowerCase();
+        if (GIT_TRUE_WORDS.includes(word)) {
+            return true;
+        }
+        return GIT_FALSE_WORDS.includes(word) ? false : value;
+    }
+    return value !== null && /^-?[0-9]+$/.test(value) ? Number(value) : value;
+}
+/** The start line shows a setting's value; a command may carry a token, so it shows only that it is set. */
+function shownValue(key, config) {
+    if (key === 'commitMessageCommand') {
+        return 'set';
+    }
+    const value = config[key];
+    return typeof value === 'number' || typeof value === 'boolean'
+        ? String(value)
+        : JSON.stringify(value);
+}
+function configKey(key) {
+    return KNOWN_KEYS.find((known) => known === key) ?? null;
+}
+function isGitOnly(key) {
+    return GIT_ONLY_KEYS.some((gitOnly) => gitOnly === key);
 }
 function parseJson(text) {
     try {
@@ -103,20 +250,8 @@ function readCommitSubject(parsed) {
     if (value === undefined) {
         return DEFAULT_CONFIG.commitSubject;
     }
-    const rule = `must be one line of 1 to ${MAX_SUBJECT_CHARACTERS} characters, not blank and not starting with #`;
-    if (typeof value !== 'string') {
-        throw invalid('commitSubject', rule);
-    }
-    const characters = Array.from(value).length;
-    // git aborts a commit whose message is empty after cleanup, and a person's
-    // commit.cleanup=strip removes a line starting with #; either would make
-    // every daemon commit fail.
-    if (characters < 1 ||
-        characters > MAX_SUBJECT_CHARACTERS ||
-        /[\r\n]/.test(value) ||
-        value.startsWith('#') ||
-        value.trim() === '') {
-        throw invalid('commitSubject', rule);
+    if (typeof value !== 'string' || !isCommitSubject(value)) {
+        throw invalid('commitSubject', `must be one line of 1 to ${MAX_SUBJECT_CHARACTERS} characters, not blank and not starting with #`);
     }
     return value;
 }
@@ -174,3 +309,14 @@ function readPartialStagingWaitMs(parsed) {
 function readHookTimeoutMs(parsed) {
     return readInteger(parsed, 'hookTimeoutMs', MIN_HOOK_TIMEOUT_MS, MAX_HOOK_TIMEOUT_MS);
 }
+/** commitMessageCommand: text that is not blank; only git config reaches here (design 14.18). */
+function readCommitMessageCommand(parsed) {
+    const value = parsed.commitMessageCommand;
+    if (value === undefined) {
+        return DEFAULT_CONFIG.commitMessageCommand;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw invalid('commitMessageCommand', 'must be a command, not blank');
+    }
+    return value;
+}

package/dist/core/git/porcelain.d.ts

@@ -1,3 +1,4 @@
+import type { GitConfigEntry } from '../../contracts/config.js';
 import type { Divergence, StatusEntry, Upstream } from '../../contracts/gitTypes.js';
 import type { GitVersion } from '../../contracts/IRepositoryLocator.js';
 /**
@@ -48,5 +49,11 @@ export declare function parseBatch(stdout: Buffer): readonly BatchBlob[];
 export declare function parseUpstream(stdout: string, branchRef: string): Upstream | null;
 /** The three absolute paths of rev-parse; null unless exactly three absolute lines (a path with a newline). */
 export declare function parseRevParsePaths(stdout: string): RevParsePaths | null;
+/**
+ * `git config -z --show-scope --get-regexp` entries: scope NUL, then the key,
+ * a newline and the value, NUL; a key written without a value has no newline
+ * (measured with git 2.52.0, design 14.18).
+ */
+export declare function parseConfigEntries(stdout: Buffer): readonly GitConfigEntry[];
 /** true when `git push --porcelain` output carries a ref line starting with `!`. */
 export declare function hasRejectedRef(stdout: string): boolean;

package/dist/core/git/porcelain.js

@@ -179,6 +179,30 @@ export function parseRevParsePaths(stdout) {
     }
     return { root, gitDir, commonDir };
 }
+/**
+ * `git config -z --show-scope --get-regexp` entries: scope NUL, then the key,
+ * a newline and the value, NUL; a key written without a value has no newline
+ * (measured with git 2.52.0, design 14.18).
+ */
+export function parseConfigEntries(stdout) {
+    const fields = nulTerminatedFields(stdout, 'git config');
+    if (fields.length % 2 !== 0) {
+        throw unparseable('git config', fields.join('\0'));
+    }
+    const entries = [];
+    for (let i = 0; i < fields.length; i += 2) {
+        const scope = fields[i] ?? '';
+        const field = fields[i + 1] ?? '';
+        const newline = field.indexOf('\n');
+        const key = newline === -1 ? field : field.slice(0, newline);
+        if (scope === '' || key === '') {
+            throw unparseable('git config', `${scope}\0${field}`);
+        }
+        const value = newline === -1 ? null : field.slice(newline + 1);
+        entries.push({ scope, key, value });
+    }
+    return entries;
+}
 /** true when `git push --porcelain` output carries a ref line starting with `!`. */
 export function hasRejectedRef(stdout) {
     return stdout.split('\n').some((line) => line.startsWith('!'));

package/dist/core/quarantine/restoreWarnings.d.ts

@@ -2,6 +2,8 @@ import type { ILogger } from '../../contracts/ILogger.js';
 import type { KeptBlob } from '../../contracts/IPathQuarantine.js';
 /** What a restore reports that a person should see; the fields of RestoreResult's restored. */
 export interface RestoreWarnings {
+    /** Paths put back; 0 logs no RESTORED line (design 14.21). */
+    readonly count: number;
     readonly kept: readonly KeptBlob[];
     readonly changedUnderHold: readonly string[];
     readonly overwritten: readonly KeptBlob[];
@@ -9,8 +11,9 @@ export interface RestoreWarnings {
 /** The QUARANTINE_UPSTREAM_CHANGED message (Decision 99). */
 export declare function changedUnderHoldMessage(path: string): string;
 /**
- * One WARN per kept blob and per path restored over a change, the same at
- * every restore: recovery, a pending memento, and integrate (written three
- * times before it was extracted).
+ * One INFO RESTORED with the count of paths put back (Decision 148), then one
+ * WARN per kept blob and per path restored over a change, the same at every
+ * restore: recovery, a pending memento, and integrate (written three times
+ * before it was extracted).
  */
 export declare function logRestoreWarnings(warnings: RestoreWarnings, cycleId: string, logger: ILogger): void;

package/dist/core/quarantine/restoreWarnings.js

@@ -4,11 +4,20 @@ export function changedUnderHoldMessage(path) {
     return `${path} changed in HEAD while it was held (a pulled change) and the held edits do not merge cleanly onto it; the held version is back in the working tree, so committing it undoes that change (compare with git diff HEAD -- ${path})`;
 }
 /**
- * One WARN per kept blob and per path restored over a change, the same at
- * every restore: recovery, a pending memento, and integrate (written three
- * times before it was extracted).
+ * One INFO RESTORED with the count of paths put back (Decision 148), then one
+ * WARN per kept blob and per path restored over a change, the same at every
+ * restore: recovery, a pending memento, and integrate (written three times
+ * before it was extracted).
  */
 export function logRestoreWarnings(warnings, cycleId, logger) {
+    if (warnings.count > 0) {
+        logger.log({
+            level: 'INFO',
+            code: 'RESTORED',
+            message: `${warnings.count === 1 ? '1 held path' : `${warnings.count} held paths`} put back`,
+            cycleId,
+        });
+    }
     for (const kept of warnings.kept) {
         logger.log({
             level: 'WARN',

package/dist/core/state/stateGuards.js

@@ -169,6 +169,7 @@ const STATE_REASONS = [
     'REBASE_REFUSED',
     'PARTIAL_SELECTION_STAGED',
     'COMMIT_HOOK_REJECTED',
+    'TREE_CHANGING',
     ...HALT_CODES,
 ];
 const OUTCOME_KINDS = [