@fluado/enmetu 0.1.0 → 0.3.0

package/README.md

@@ -1,24 +1,58 @@
-# enmetu
+<p align="center">
+  <img src="logo.svg" width="80" height="80" alt="enmetu">
+</p>
+
+<h1 align="center">enmetu</h1>
+
+<p align="center"><sub>/enˈme.tu/, Esperanto for "commit!"</sub></p>
 
 Commits and syncs a git working tree automatically. Run it inside a repository: it commits after you stop editing, rebases onto the upstream, pushes, and pulls new commits.
 
+## Why enmetu
+
+Most auto-commit tools commit and push. enmetu also handles what goes wrong:
+
+- **Conflicts.** A pull that conflicts is undone and held. Your commits stay local, and enmetu retries when either side changes. It never commits conflict markers and never force-pushes.
+- **No stash.** A file it won't commit (conflict markers, invalid JSON) stays on disk and doesn't block the rest of the sync. Its pre-commit hook applies the same check to your own commits.
+- **Plain git.** You and your agents keep using git. enmetu commits through its own index, waits up to 5 minutes on a partial staging, and pauses during your merge or rebase.
+- **Halts.** A rewritten upstream, or a state it cannot verify, halts it. The halt survives restarts until you run `enmetu resume`.
+- **Status.** `enmetu status` says whether your work is committed and pushed, and during a conflict prints the commands to end it.
+- **Dependencies.** None besides git. Runs under Node or Bun, as a command or as a library.
+- **Tests.** Real git against [28 conflict shapes](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/conflictMatrix.scenario.integration.test.ts) (renames against deletions, binary files, case-only renames, line endings, a merge in progress), [several clones converging on one history](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/convergence.scenario.integration.test.ts), and [a stress test](https://codefloe.com/fluado/enmetu/src/branch/main/src/__tests__/concurrencyStress.scenario.integration.test.ts) where a scripted person runs git next to enmetu as fast as it can, with every write checked against the final history.
+
 ## Prerequisites
 
-- Node 24+ or Bun 1.3.6+
+- Node 24+ or Bun 1.4.4+
 - git 2.38+
 - A checked-out branch with an upstream, at least one commit, and a committer identity
 
 ## Install
 
+### Node
+
 Inside a repository:
 
 ```sh
 npx @fluado/enmetu run
 ```
 
-Pin a version for repeatable runs: `npx @fluado/enmetu@0.1.0 run`.
+As a project dependency: `npm install -D @fluado/enmetu`, then `npx enmetu run`.
+
+### Bun
+
+Inside a repository:
+
+```sh
+bunx --bun @fluado/enmetu run
+```
+
+As a project dependency: `bun add -d @fluado/enmetu`, then `bunx --bun enmetu run`.
+
+Keep `--bun`: without it, `bunx` runs enmetu with Node when Node is installed.
+
+### Pinning
 
-In a Node project: `npm install -D @fluado/enmetu`, then `npx enmetu run`.
+Add the version for repeatable runs: `@fluado/enmetu@0.3.0`.
 
 ## Commands
 
@@ -50,6 +84,21 @@ const { liveness, record } = await readEnmetuState('.')
 const exitCode = await enmetu.stop()
 ```
 
+`commitMessage` lets the host program write each commit message:
+
+```js
+startEnmetu({
+  repo: '.',
+  commitMessage: async ({ root, parent, tree, runCommand, signal }) =>
+    (await runCommand()) ?? 'Update notes',
+})
+```
+
+- `git diff-tree -r <parent> <tree>` in `root` lists the change.
+- Return the message, its first line the subject, or `null` for `commitSubject`.
+- `runCommand()` runs the person's `commitMessageCommand` on this change, at most once, and gives its message or `null`. With `commitMessage` set, the command runs only through this call.
+- 10 seconds, then `signal` aborts and enmetu commits with `commitSubject`. So does a throw, or text without a subject; the log says `MESSAGE_WRITER_FAILED`.
+
 ## Configuration
 
 `enmetu.config.json` at the repository root, optional:
@@ -59,16 +108,46 @@ const exitCode = await enmetu.stop()
 | `quietMs` | `5000` | wait after the last change before committing |
 | `maxDelayMs` | `60000` | maximum delay while changes keep coming |
 | `pollMs` | `5000` | remote check interval |
-| `commitSubject` | `"enmetu: local changes"` | commit message |
+| `commitSubject` | `"enmetu: local changes"` | commit message, and the fallback of `commitMessageCommand` |
 | `installHook` | `true` | install the pre-commit hook |
 | `skipJsonCheck` | `[]` | files exempt from the JSON check, such as `tsconfig.json` |
 | `gitTimeoutMs` | `120000` | timeout per git command |
 | `stateHistory` | `20` | state changes kept in the state file (0 to 100) |
-| `stagedSelection` | `"wait"` | with a partial staging: `"wait"`, or `"commit"` everything |
-| `stagedSelectionMaxWaitMs` | `null` | with `"wait"`: commit everything after this long |
+| `partialStagingWaitMs` | `300000` | with a partial staging: commit everything after this long; `0` at once |
 | `commitHooks` | `true` | run your commit hooks on enmetu's commits |
 | `hookTimeoutMs` | `600000` | timeout per hook |
 
+Unknown settings are logged and ignored.
+
+### Your own settings
+
+`git config enmetu.<key>` overrides the file for you alone, with the same names and checks: `--global` for all your repositories, `--local` for one clone. Local beats global. `enmetu run` logs each override at start, such as `CONFIG_FROM_GIT quietMs 2000 (git config, local)`.
+
+```sh
+git config --global enmetu.quietMs 2000
+git config --local --add enmetu.skipJsonCheck tsconfig.json
+```
+
+`skipJsonCheck` takes one path per entry; the list of the most specific scope replaces the file's.
+
+### Commit message command
+
+A command that writes the commit message. Set it in git config only; enmetu ignores it in `enmetu.config.json`.
+
+```sh
+git config --global enmetu.commitMessageCommand 'your-command'
+```
+
+For each commit, enmetu runs it through the shell in the repository root:
+
+- stdin: the patch, its first 64 KiB
+- environment: `ENMETU_PARENT` and `ENMETU_TREE`, for your own `git diff "$ENMETU_PARENT" "$ENMETU_TREE"`
+- stdout: the first line is the subject (at most 100 characters), the lines after it the body
+
+After 5 seconds, or when the command fails or prints no usable subject, enmetu commits with `commitSubject` and logs `MESSAGE_COMMAND_FAILED`. The start line shows that a command is set, never the command.
+
+Example: [`examples/commit-message`](https://codefloe.com/fluado/enmetu/src/branch/main/examples/commit-message), a Node or Bun script that names the changed document and adds a detail from a local model through [llm](https://llm.datasette.io), such as Apple's on-device model. Not part of the package.
+
 ## Status
 
 ```
@@ -112,6 +191,7 @@ stderr, one line per event:
 | `CONFLICT`, `UNPUSHED` | local commits not pushed |
 | `WAITING`, `PAUSED`, `OFFLINE` | sync on hold |
 | `HALTED` | see `enmetu status` |
+| `MESSAGE_COMMAND_FAILED`, `MESSAGE_WRITER_FAILED` | message from the fallback named in the line |
 | `COMMIT_ORPHANED`, `STAGED_RESET`, `STAGED_REVERT`, `QUARANTINE_KEPT` | see Known limitations |
 
 ## State file
@@ -147,9 +227,10 @@ if command -v enmetu >/dev/null 2>&1; then enmetu hook pre-commit || exit 1; els
 ## Known limitations
 
 - One repository per process. No system service, no notifications.
-- A partial staging pauses sync until you commit or unstage it (`stagedSelection: "wait"`).
-- `commit-msg` and `prepare-commit-msg` hooks don't run on enmetu's commits.
+- A partial staging pauses sync for up to `partialStagingWaitMs` (5 minutes by default), then enmetu commits everything. A case-only rename staged with `git mv` pauses it until you commit it.
+- `commit-msg` and `prepare-commit-msg` hooks don't run on enmetu's commits; `commitMessageCommand` writes the message instead.
 - Under Bun without file-watching permission, enmetu commits on its poll interval.
+- Under Node on Linux, enmetu does not watch files: from Node 24.22, Node's recursive watch there can end the process ([nodejs/node#66791](https://github.com/nodejs/node/issues/66791)). enmetu commits on its poll interval (`pollMs`, 5 seconds by default) and says so once at start (`WATCHER_FAILED`). Bun watches.
 - A save during enmetu's pull can be overwritten by git without notice.
 
 Overlapping git commands:
@@ -161,9 +242,17 @@ Overlapping git commands:
 | `QUARANTINE_KEPT` | your edit collided with a version enmetu held aside | command in the log line |
 | `COMMIT_ORPHANED` | committed during enmetu's pull | `git cherry-pick -x` command in `enmetu status` |
 | `STAGED_REVERT` | a refused `git merge` restored old content | `git restore` command in the log line |
-| `could not write index` on a refused merge | git stashed your edits | `git fsck --no-reflogs --unreachable`, then `git stash apply <id>` |
+| `could not write index` on a refused merge, or with older git (2.39) your edits gone after `would be overwritten by merge` | git stashed your edits | `git fsck --no-reflogs --unreachable`, then `git stash apply <id>` |
 | `git rebase` fails, no rebase in progress | started together with enmetu's | `git rebase --quit` if needed, `git reset --merge`, `git checkout <branch>`, retry |
 
+## Contributing
+
+We built enmetu for ourselves. We use it every day at [fluado](https://fluado.com) and we're sharing it because it might be useful to others.
+
+This is not a community project. We don't have the bandwidth to review PRs, triage issues, or maintain a roadmap for external contributors. If you open an issue with a good idea, we might pick it up when it aligns with what we need. No promises.
+
+Fork it, break it, make it yours. Have fun.
+
 ## Licence
 
 MIT, Copyright (c) 2026 Yves Van Goethem, fluado UG (haftungsbeschränkt). See `LICENSE`.

package/dist/adapters/git/gitFacade.d.ts

@@ -1,3 +1,4 @@
+import type { GitConfigEntry } from '../../contracts/config.js';
 import type { Divergence, FetchResult, HeadMove, PushResult, RebaseResult, RebaseStart, RemoteHead, RepositoryState, StagedFile, StageResult, StatusEntry, Upstream } from '../../contracts/gitTypes.js';
 import type { IFileSystem } from '../../contracts/IFileSystem.js';
 import type { CommitHookName, CommitTreeInput, HookRun, IGitCommitter } from '../../contracts/IGitCommitter.js';
@@ -79,6 +80,11 @@ export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter
     mergeBase(left: string, right: string): Promise<string | null>;
     /** git diff --name-only -z --no-renames <from> <to> (design 12.3). */
     changedPaths(from: string, to: string): Promise<readonly string[]>;
+    /**
+     * git diff-tree -r -p --no-color --no-ext-diff --no-textconv <from> <toTree>,
+     * stdout capped at maxBytes, the rest read and dropped (design 14.18).
+     */
+    patch(from: string, toTree: string, maxBytes: number): Promise<Buffer>;
     /**
      * git -c core.hooksPath=/dev/null read-tree --reset <commit> (design 12.7):
      * -m's one-tree merge, which keeps the stat data of matching entries, except
@@ -102,6 +108,8 @@ export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter
      */
     runHook(name: CommitHookName, args: readonly string[]): Promise<HookRun>;
     configValue(key: string): Promise<string | null>;
+    /** git config -z --show-scope --get-regexp ^enmetu\. ; exit 1 means none is set (design 14.18). */
+    enmetuEntries(): Promise<readonly GitConfigEntry[]>;
     stageAll(): Promise<StageResult>;
     unstage(paths: readonly string[]): Promise<void>;
     fetch(remote: string, remoteRef: string, intoRef: string): Promise<FetchResult>;

package/dist/adapters/git/gitFacade.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { GitCommandError, GitOutputError } from '../../contracts/errors.js';
-import { hasRejectedRef, parseBatch, parseBatchCheck, parseDivergence, parseLsRemote, parseRawDiff, parseStatus, parseUpstream, } from '../../core/git/porcelain.js';
+import { hasRejectedRef, parseBatch, parseBatchCheck, parseConfigEntries, parseDivergence, parseLsRemote, parseRawDiff, parseStatus, parseUpstream, } from '../../core/git/porcelain.js';
 /** At most this much blob content is requested from one `git cat-file --batch` call. */
 export const GIT_BATCH_CHUNK_BYTES = 67108864;
 /** A hook's stdout and stderr beyond this are dropped, never a failure (design 12.7, Decision 83). */
@@ -347,6 +347,27 @@ export class GitFacade {
         const args = ['diff', '--name-only', '-z', '--no-renames', from, to];
         return parseNulPaths((await this.gitOk(args)).stdout, 'git diff --name-only');
     }
+    /**
+     * git diff-tree -r -p --no-color --no-ext-diff --no-textconv <from> <toTree>,
+     * stdout capped at maxBytes, the rest read and dropped (design 14.18).
+     */
+    async patch(from, toTree, maxBytes) {
+        const args = [
+            'diff-tree',
+            '-r',
+            '-p',
+            '--no-color',
+            '--no-ext-diff',
+            '--no-textconv',
+            from,
+            toTree,
+        ];
+        const result = await this.git(args, { outputCapBytes: maxBytes });
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return result.stdout;
+    }
     /**
      * git -c core.hooksPath=/dev/null read-tree --reset <commit> (design 12.7):
      * -m's one-tree merge, which keeps the stat data of matching entries, except
@@ -448,6 +469,18 @@ export class GitFacade {
         }
         return stripOneTrailingNewline(result.stdout.toString('utf8'));
     }
+    /** git config -z --show-scope --get-regexp ^enmetu\. ; exit 1 means none is set (design 14.18). */
+    async enmetuEntries() {
+        const args = ['config', '-z', '--show-scope', '--get-regexp', '^enmetu\\.'];
+        const result = await this.git(args);
+        if (result.exitCode === 1) {
+            return [];
+        }
+        if (result.exitCode !== 0) {
+            throw gitFailed(args, result);
+        }
+        return parseConfigEntries(result.stdout);
+    }
     async stageAll() {
         const args = [...HOOKLESS, 'add', '-A', '--ignore-errors'];
         const result = await this.git(args);

package/dist/adapters/git/gitLocatorFacade.js

@@ -36,13 +36,16 @@ export class GitLocatorFacade {
         if (insideWorkTree !== 'true') {
             return { kind: 'not-a-repository' };
         }
+        // Not --git-path hooks: it honours core.hooksPath, and git refuses an
+        // empty one as a path (exit 128) although it runs hooks with it; the
+        // installer writes only to the repository's own hooks directory, and only
+        // while core.hooksPath is unset (design 14.17).
         const paths = parseRevParsePaths((await runOk(runner, [
             'rev-parse',
             '--path-format=absolute',
             '--show-toplevel',
             '--git-dir',
-            '--git-path',
-            'hooks',
+            '--git-common-dir',
         ])).stdout.toString('utf8'));
         if (paths === null) {
             throw new PreflightError('a repository path contains a newline, which enmetu does not support', 'PATH_UNSUPPORTED');
@@ -52,7 +55,7 @@ export class GitLocatorFacade {
             paths: {
                 root: paths.root,
                 gitDir: paths.gitDir,
-                hooksDir: paths.hooksDir,
+                hooksDir: join(paths.commonDir, 'hooks'),
                 stateDir: join(paths.gitDir, 'enmetu'),
             },
             version,

package/dist/adapters/git/gitProcessAdapter.js

@@ -1,6 +1,6 @@
 import { execFile, spawn } from 'node:child_process';
-import { kill } from 'node:process';
 import { GitCommandError } from '../../contracts/errors.js';
+import { CappedOutput, errorCode, killGroup } from '../process/processGroup.js';
 /** 128 MiB: a cat-file batch chunk (64 MiB of content) plus headers fits with room. */
 export const GIT_MAX_BUFFER_BYTES = 134217728;
 const KILL_SIGNAL = 'SIGTERM';
@@ -184,53 +184,6 @@ export class GitProcessAdapter {
         return new GitCommandError(`${command} ended by signal ${error.signal ?? 'unknown'}`, 'GIT_FAILED', args, null, stderr);
     }
 }
-/** Keeps the first `cap` bytes of a stream and counts that more arrived. */
-class CappedOutput {
-    cap;
-    chunks = [];
-    length = 0;
-    dropped = false;
-    constructor(cap) {
-        this.cap = cap;
-    }
-    add(chunk) {
-        const room = this.cap - this.length;
-        if (room <= 0) {
-            this.dropped = this.dropped || chunk.length > 0;
-            return;
-        }
-        const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
-        this.dropped = this.dropped || kept.length < chunk.length;
-        this.chunks.push(kept);
-        this.length += kept.length;
-    }
-    bytes() {
-        return Buffer.concat(this.chunks);
-    }
-    text() {
-        return this.bytes().toString('utf8');
-    }
-}
-/** Signals git's whole process group; a group that is already gone is fine. */
-function killGroup(pid, signal) {
-    if (pid === undefined) {
-        return;
-    }
-    try {
-        kill(-pid, signal);
-    }
-    catch (error) {
-        if (errorCode(error) !== 'ESRCH') {
-            throw error;
-        }
-    }
-}
-function errorCode(error) {
-    if (typeof error === 'object' && error !== null && 'code' in error) {
-        return typeof error.code === 'string' ? error.code : 'unknown';
-    }
-    return 'unknown';
-}
 /**
  * The adapter's environment, plus GIT_REFLOG_ACTION when the call names one.
  * The shared environment is never changed, so no other call inherits it.

package/dist/adapters/host/hostMessageWriterAdapter.d.ts

@@ -0,0 +1,23 @@
+import type { HostMessageInput, HostMessageRun, IHostMessageWriter } from '../../contracts/IHostMessageWriter.js';
+import type { CommitMessageWriter } from '../../contracts/library.js';
+export interface HostMessageWriterOptions {
+    /** The repository root, handed to the writer. */
+    readonly root: string;
+    readonly timeoutMs: number;
+    /** A stop request ends the wait at once (design 14.19). */
+    readonly abort?: AbortSignal | undefined;
+}
+/**
+ * Adapter: the host program's CommitMessageWriter with a time limit (design
+ * 14.19, Decision 135). The writer runs in enmetu's own process, so nothing
+ * can end it: at the limit or a stop request enmetu stops waiting, aborts the
+ * signal it handed over and commits with commitSubject, and a writer that
+ * ignores the signal finishes into nothing. Never throws; a writer's throw,
+ * synchronous or not, is a value.
+ */
+export declare class HostMessageWriterAdapter implements IHostMessageWriter {
+    private readonly writer;
+    private readonly options;
+    constructor(writer: CommitMessageWriter, options: HostMessageWriterOptions);
+    write(input: HostMessageInput): Promise<HostMessageRun>;
+}

package/dist/adapters/host/hostMessageWriterAdapter.js

@@ -0,0 +1,76 @@
+import { errorMessage } from '../../core/errors/errorMessage.js';
+/**
+ * Adapter: the host program's CommitMessageWriter with a time limit (design
+ * 14.19, Decision 135). The writer runs in enmetu's own process, so nothing
+ * can end it: at the limit or a stop request enmetu stops waiting, aborts the
+ * signal it handed over and commits with commitSubject, and a writer that
+ * ignores the signal finishes into nothing. Never throws; a writer's throw,
+ * synchronous or not, is a value.
+ */
+export class HostMessageWriterAdapter {
+    writer;
+    options;
+    constructor(writer, options) {
+        this.writer = writer;
+        this.options = options;
+    }
+    write(input) {
+        const { abort, timeoutMs } = this.options;
+        if (abort?.aborted === true) {
+            return Promise.resolve(stopped());
+        }
+        const handover = new AbortController();
+        const deadline = AbortSignal.timeout(timeoutMs);
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (run) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                deadline.removeEventListener('abort', onDeadline);
+                abort?.removeEventListener('abort', onAbort);
+                resolve(run);
+            };
+            const end = (run) => {
+                handover.abort();
+                settle(run);
+            };
+            const onDeadline = () => end({ kind: 'failed', detail: `took longer than ${timeoutMs} ms` });
+            const onAbort = () => end(stopped());
+            deadline.addEventListener('abort', onDeadline, { once: true });
+            abort?.addEventListener('abort', onAbort, { once: true });
+            let pending;
+            try {
+                pending = Promise.resolve(this.writer({
+                    root: this.options.root,
+                    parent: input.parent,
+                    tree: input.tree,
+                    runCommand: input.runCommand,
+                    signal: handover.signal,
+                }));
+            }
+            catch (error) {
+                settle(threw(error));
+                return;
+            }
+            pending.then((value) => settle(runOf(value)), (error) => settle(threw(error)));
+        });
+    }
+}
+/** A JavaScript host can return anything; only text and null mean something. */
+function runOf(value) {
+    if (typeof value === 'string') {
+        return { kind: 'wrote', text: value };
+    }
+    if (value === null) {
+        return { kind: 'declined' };
+    }
+    return { kind: 'failed', detail: 'returned neither text nor null' };
+}
+function threw(error) {
+    return { kind: 'failed', detail: `threw: ${errorMessage(error)}` };
+}
+function stopped() {
+    return { kind: 'failed', detail: 'was ended because enmetu is stopping' };
+}

package/dist/adapters/process/processGroup.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Plumbing shared by the two adapters that run a child in its own process
+ * group: git with a budget (a repository hook) and commitMessageCommand.
+ */
+/** Keeps the first `cap` bytes of a stream and counts that more arrived. */
+export declare class CappedOutput {
+    private readonly cap;
+    private readonly chunks;
+    private length;
+    dropped: boolean;
+    constructor(cap: number);
+    add(chunk: Buffer): void;
+    bytes(): Buffer;
+    text(): string;
+}
+/** Signals a child's whole process group; a group that is already gone is fine. */
+export declare function killGroup(pid: number | undefined, signal: NodeJS.Signals): void;
+export declare function errorCode(error: unknown): string;

package/dist/adapters/process/processGroup.js

@@ -0,0 +1,52 @@
+import { kill } from 'node:process';
+/**
+ * Plumbing shared by the two adapters that run a child in its own process
+ * group: git with a budget (a repository hook) and commitMessageCommand.
+ */
+/** Keeps the first `cap` bytes of a stream and counts that more arrived. */
+export class CappedOutput {
+    cap;
+    chunks = [];
+    length = 0;
+    dropped = false;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    add(chunk) {
+        const room = this.cap - this.length;
+        if (room <= 0) {
+            this.dropped = this.dropped || chunk.length > 0;
+            return;
+        }
+        const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+        this.dropped = this.dropped || kept.length < chunk.length;
+        this.chunks.push(kept);
+        this.length += kept.length;
+    }
+    bytes() {
+        return Buffer.concat(this.chunks);
+    }
+    text() {
+        return this.bytes().toString('utf8');
+    }
+}
+/** Signals a child's whole process group; a group that is already gone is fine. */
+export function killGroup(pid, signal) {
+    if (pid === undefined) {
+        return;
+    }
+    try {
+        kill(-pid, signal);
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ESRCH') {
+            throw error;
+        }
+    }
+}
+export function errorCode(error) {
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+        return typeof error.code === 'string' ? error.code : 'unknown';
+    }
+    return 'unknown';
+}

package/dist/adapters/process/shellMessageCommandAdapter.d.ts

@@ -0,0 +1,24 @@
+import type { CommitMessageCommandInput, CommitMessageCommandRun, ICommitMessageCommand } from '../../contracts/ICommitMessageCommand.js';
+export interface ShellMessageCommandOptions {
+    /** The repository root; the command runs there. */
+    readonly cwd: string;
+    /** The environment the command starts from (Runtime.env); the adapter reads no global environment. */
+    readonly baseEnv: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs: number;
+    /** stdout beyond this is dropped, never a failure. */
+    readonly outputCapBytes: number;
+    /** A stop request ends a running command at once (design 14.18). */
+    readonly abort?: AbortSignal | undefined;
+}
+/**
+ * Adapter: commitMessageCommand through the shell (design 14.18, Decision
+ * 131). The command leads its own process group, so the time limit and a
+ * stop request end it and everything it started, with SIGKILL at once: a
+ * message writer holds nothing that needs a graceful end, and the commit does
+ * not wait for it. Never throws; every way the command can fail is a value.
+ */
+export declare class ShellMessageCommandAdapter implements ICommitMessageCommand {
+    private readonly options;
+    constructor(options: ShellMessageCommandOptions);
+    run(input: CommitMessageCommandInput): Promise<CommitMessageCommandRun>;
+}

package/dist/adapters/process/shellMessageCommandAdapter.js

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import { CappedOutput, errorCode, killGroup } from './processGroup.js';
+/** Enough of stderr for the first line the failure names. */
+const STDERR_CAP_BYTES = 4096;
+/**
+ * Adapter: commitMessageCommand through the shell (design 14.18, Decision
+ * 131). The command leads its own process group, so the time limit and a
+ * stop request end it and everything it started, with SIGKILL at once: a
+ * message writer holds nothing that needs a graceful end, and the commit does
+ * not wait for it. Never throws; every way the command can fail is a value.
+ */
+export class ShellMessageCommandAdapter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    run(input) {
+        const { abort, timeoutMs } = this.options;
+        if (abort?.aborted === true) {
+            return Promise.resolve(stopped());
+        }
+        return new Promise((resolve) => {
+            const child = spawn(input.command, {
+                cwd: this.options.cwd,
+                env: commandEnvironment(this.options.baseEnv, input),
+                shell: true,
+                detached: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+            const stdout = new CappedOutput(this.options.outputCapBytes);
+            const stderr = new CappedOutput(STDERR_CAP_BYTES);
+            const deadline = AbortSignal.timeout(timeoutMs);
+            let settled = false;
+            const settle = (run) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                deadline.removeEventListener('abort', onDeadline);
+                abort?.removeEventListener('abort', onAbort);
+                resolve(run);
+            };
+            const end = (run) => {
+                killGroup(child.pid, 'SIGKILL');
+                // A process that left the group (setsid) may still hold the pipes
+                // open; the run ends here regardless.
+                child.stdout.destroy();
+                child.stderr.destroy();
+                settle(run);
+            };
+            const onDeadline = () => end({ kind: 'failed', detail: `timed out after ${timeoutMs} ms` });
+            const onAbort = () => end(stopped());
+            deadline.addEventListener('abort', onDeadline, { once: true });
+            abort?.addEventListener('abort', onAbort, { once: true });
+            child.stdout.on('data', (chunk) => stdout.add(chunk));
+            child.stderr.on('data', (chunk) => stderr.add(chunk));
+            child.on('error', (error) => {
+                settle({
+                    kind: 'failed',
+                    detail: `could not be started in ${this.options.cwd} (${errorCode(error)})`,
+                });
+            });
+            child.on('close', (code, signal) => {
+                if (code === 0) {
+                    settle({ kind: 'printed', stdout: stdout.text() });
+                    return;
+                }
+                const ended = code === null
+                    ? `ended by signal ${signal ?? 'unknown'}`
+                    : `exited ${code}`;
+                const reason = firstLine(stderr.text());
+                settle({
+                    kind: 'failed',
+                    detail: reason === '' ? ended : `${ended}: ${reason}`,
+                });
+            });
+            // A command that ignores its input may exit before reading it; the
+            // resulting EPIPE must not become an uncaught exception.
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(input.stdin);
+        });
+    }
+}
+function stopped() {
+    return { kind: 'failed', detail: 'was ended because enmetu is stopping' };
+}
+/** The base environment plus the commit's parent and tree, so a command can ask git itself. */
+function commandEnvironment(baseEnv, input) {
+    const env = {};
+    for (const [key, value] of Object.entries(baseEnv)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+    env.ENMETU_PARENT = input.parent;
+    env.ENMETU_TREE = input.tree;
+    return env;
+}
+function firstLine(text) {
+    return (text.trim().split('\n')[0] ?? '').trim();
+}

package/dist/adapters/watch/watcherFor.d.ts

@@ -0,0 +1,22 @@
+import type { IWatcher, WatchListener } from '../../contracts/IWatcher.js';
+import type { Runtime } from '../../contracts/runtime.js';
+/** Why no file watch starts under Node on Linux (design 14.20, Decision 137). */
+export declare 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 declare class PollOnlyWatcher implements IWatcher {
+    private readonly reason;
+    constructor(reason: string);
+    start(listener: WatchListener): void;
+    close(): void;
+}
+/**
+ * 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 declare function watcherFor(root: string, runtime: Pick<Runtime, 'platform' | 'engine'>): IWatcher;