@fluado/enmetu 0.3.0 → 0.5.0

package/README.md

@@ -6,6 +6,8 @@
 
 <p align="center"><sub>/enˈme.tu/, Esperanto for "commit!"</sub></p>
 
+<p align="center"><a href="https://www.npmjs.com/package/@fluado/enmetu"><img src="https://img.shields.io/npm/v/@fluado/enmetu?label=release&color=blue" alt="latest release"></a></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
@@ -14,45 +16,45 @@ 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.
+- **Plain git.** You and your agents keep using git. enmetu commits through its own index, waits up to 5 minutes on a partial staging, pauses during your merge or rebase, and never pulls over a file you saved since its last commit: it commits the save first, then pulls.
 - **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.
+- **Commit messages.** Can be generated by a script that gets the diff, e.g. with an LLM. Falls back to a default message.
+- **Dependencies.** None besides git. Runs as an executable, under Node or Bun, or as a library.
+
+All of it is tested with real git against [35 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.4.4+
-- git 2.38+
+- The standalone executable, or Node 24+ or Bun 1.4.4+
+- git 2.39+
 - A checked-out branch with an upstream, at least one commit, and a committer identity
 
 ## Install
 
-### Node
-
-Inside a repository:
+Executable, macOS or Linux:
 
 ```sh
-npx @fluado/enmetu run
+curl -fsSL https://codefloe.com/fluado/enmetu/raw/branch/main/install.sh | sh
 ```
 
-As a project dependency: `npm install -D @fluado/enmetu`, then `npx enmetu run`.
+Node:
 
-### Bun
+```sh
+npx @fluado/enmetu run
+```
 
-Inside a repository:
+Bun:
 
 ```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
+As a dependency: `npm install -D @fluado/enmetu` or `bun add -d @fluado/enmetu`, then `npx enmetu run` or `bunx --bun enmetu run`.
 
-Add the version for repeatable runs: `@fluado/enmetu@0.3.0`.
+Pin a version with `@fluado/enmetu@0.5.0`, or `ENMETU_VERSION=v0.5.0` for the installer. The binaries are also on the [releases page](https://codefloe.com/fluado/enmetu/releases).
 
 ## Commands
 
@@ -94,7 +96,7 @@ startEnmetu({
 })
 ```
 
-- `git diff-tree -r <parent> <tree>` in `root` lists the change.
+- `git diff-tree -r -M <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`.
@@ -190,6 +192,7 @@ stderr, one line per event:
 | `EXCLUDED` | file not committed: conflict markers or invalid JSON |
 | `CONFLICT`, `UNPUSHED` | local commits not pushed |
 | `WAITING`, `PAUSED`, `OFFLINE` | sync on hold |
+| `HELD`, `RESTORED` | a file enmetu could not commit was set aside for a pull and put back; see Known limitations |
 | `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 |
@@ -231,23 +234,26 @@ if command -v enmetu >/dev/null 2>&1; then enmetu hook pre-commit || exit 1; els
 - `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.
+- A file written faster than a cycle runs keeps the pull waiting (`WAITING` with `TREE_CHANGING`) until it stops.
+- A file enmetu cannot commit (invalid JSON, conflict markers, a rejected `pre-commit`) is set aside during a pull and shows the committed version from `HELD` until `RESTORED`, about 0.1 to 0.5 seconds. A save made meanwhile is merged back, or kept as a blob named in `QUARANTINE_KEPT` when it does not merge.
+- A save landing in the milliseconds before git rewrites a file, inside a pull or its abort, is lost without a record.
 
 Overlapping git commands:
 
 | Symptom | Cause | Fix |
 |---|---|---|
+| a file briefly showed old content | `HELD`: enmetu set it aside for a pull | wait for `RESTORED`; a `QUARANTINE_KEPT` line names a blob: `git cat-file -p <id>` |
 | `cannot lock ref 'HEAD'` | raced enmetu's commit | after `INDEX_REPAIRED` in the log: `git reset --merge`, retry. If `not uptodate`: `git merge --quit`, `git reset` |
 | `STAGED_RESET` | staged during enmetu's rebase | command in the log line |
 | `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, 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 |
+| `git rebase` fails, no rebase in progress | started together with enmetu's | `git rebase --quit` if needed, `git reset --merge` if files are unmerged, `git checkout -m <branch>` (keeps your edits), 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.
+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. It is the sync engine of [faru](https://github.com/fluado/faru), our git-native kanban board.
 
 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.
 

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

@@ -9,11 +9,6 @@ import type { IGitWriter } from '../../contracts/IGitWriter.js';
 export declare const GIT_BATCH_CHUNK_BYTES = 67108864;
 /** A hook's stdout and stderr beyond this are dropped, never a failure (design 12.7, Decision 83). */
 export declare const HOOK_OUTPUT_CAP_BYTES = 65536;
-/**
- * Facade: typed questions and commands over the git CLI, with exactly the
- * argv and interpretations of design section 1.3. gitDir locates the state
- * files repositoryState and the rebase readers check.
- */
 export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter {
     private readonly runner;
     private readonly fs;
@@ -135,7 +130,9 @@ export declare class GitFacade implements IGitReader, IGitWriter, IGitCommitter
      * Runs a command that talks to the remote. A timeout there is the network or
      * a credential prompt (ssh connect, passphrase, pinentry), so it comes back as
      * a value the cycle reports (OFFLINE, or PUSH_FAILED with UNPUSHED, D2),
-     * never an error that ends the cycle in CYCLE_FAILED.
+     * never an error that ends the cycle in CYCLE_FAILED. The command leads its
+     * own process group, so the timeout ends the ssh it started too (Decision
+     * 158); killed alone, git would leave ssh waiting on the dead connection.
      */
     private remoteGit;
     /** Runs git and expects exit code 0. */

package/dist/adapters/git/gitFacade.js

@@ -54,6 +54,8 @@ const OPERATION_MARKERS = [
  * argv and interpretations of design section 1.3. gitDir locates the state
  * files repositoryState and the rebase readers check.
  */
+/** How the three remote commands run (Decision 158). */
+const REMOTE_RUN = { killGroup: true };
 export class GitFacade {
     runner;
     fs;
@@ -653,11 +655,13 @@ export class GitFacade {
      * Runs a command that talks to the remote. A timeout there is the network or
      * a credential prompt (ssh connect, passphrase, pinentry), so it comes back as
      * a value the cycle reports (OFFLINE, or PUSH_FAILED with UNPUSHED, D2),
-     * never an error that ends the cycle in CYCLE_FAILED.
+     * never an error that ends the cycle in CYCLE_FAILED. The command leads its
+     * own process group, so the timeout ends the ssh it started too (Decision
+     * 158); killed alone, git would leave ssh waiting on the dead connection.
      */
     async remoteGit(args) {
         try {
-            return { kind: 'ran', result: await this.git(args) };
+            return { kind: 'ran', result: await this.git(args, REMOTE_RUN) };
         }
         catch (error) {
             if (error instanceof GitCommandError && error.code === 'GIT_TIMEOUT') {

package/dist/adapters/git/gitProcessAdapter.js

@@ -40,7 +40,8 @@ export class GitProcessAdapter {
         const env = callEnvironment(this.env, options?.reflogAction);
         if (options?.timeoutMs !== undefined ||
             options?.outputCapBytes !== undefined ||
-            options?.abort !== undefined) {
+            options?.abort !== undefined ||
+            options?.killGroup === true) {
             return this.runInGroup(argv, env, options);
         }
         return new Promise((resolve, reject) => {

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

@@ -3,13 +3,20 @@ import { type ExitCode } from '../../contracts/exitCode.js';
 import type { IDaemon } from '../../contracts/IDaemon.js';
 import type { IFileSystem } from '../../contracts/IFileSystem.js';
 import type { ILogger } from '../../contracts/ILogger.js';
-import type { IRepositoryLocator, RepositoryPaths } from '../../contracts/IRepositoryLocator.js';
+import type { GitVersion, IRepositoryLocator, RepositoryPaths } from '../../contracts/IRepositoryLocator.js';
 export interface RunCommandInput {
     /** --repo, else the working directory. */
     readonly startDir: string;
 }
+/** The JavaScript runtime enmetu runs on and its version (design 14.25). */
+export interface Engine {
+    readonly kind: 'node' | 'bun';
+    readonly version: string;
+}
 export interface RunCommandDeps {
     readonly locator: IRepositoryLocator;
+    /** Checked first: an engine below the floor exits 5 before any git call (Decision 160). */
+    readonly engine: Engine;
     readonly fs: IFileSystem;
     /** Every enmetu.* entry of git config for the resolved repository (design 14.18). */
     readonly readGitConfig: (paths: RepositoryPaths) => Promise<readonly GitConfigEntry[]>;
@@ -20,15 +27,30 @@ export interface RunCommandDeps {
 export interface RunCommandResult {
     readonly exitCode: ExitCode;
 }
-/** Minimum git version (Decision 16): --no-update-refs appeared in 2.38. */
+/**
+ * Minimum git version: 2.39, the oldest git the suites run on (Debian bookworm,
+ * Decision 156). The feature floor is 2.38, where --no-update-refs appeared
+ * (Decision 16); no older git has run the suites, so none is promised.
+ */
 export declare const MIN_GIT_VERSION: {
     major: number;
     minor: number;
 };
+/**
+ * Minimum engine versions (design 14.25, Decision 160): Node 24 is the
+ * package's engines field; Bun 1.4.4 is measured, 1.3.6 drops the watch event
+ * for a file git merge rewrites (Decision 128). Shown as the README states them.
+ */
+export declare const MIN_ENGINE_VERSION: Readonly<Record<Engine['kind'], {
+    readonly floor: GitVersion;
+    readonly shown: string;
+}>>;
 /**
  * Controller:
+ * 0. The engine below its floor: NOT_ELIGIBLE (ENGINE_TOO_OLD), exit 5, before
+ *    any git call (design 14.25); a version that does not parse passes.
  * 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.
+ * 2. Git older than 2.39: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
  * 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;

package/dist/cli/commands/runCommand.js

@@ -2,12 +2,27 @@ import { join } from 'node:path';
 import { ConfigError, PreflightError, } from '../../contracts/errors.js';
 import { EXIT } from '../../contracts/exitCode.js';
 import { CONFIG_FILE_NAME, parseConfig } from '../../core/config/parseConfig.js';
-/** Minimum git version (Decision 16): --no-update-refs appeared in 2.38. */
-export const MIN_GIT_VERSION = { major: 2, minor: 38 };
+/**
+ * Minimum git version: 2.39, the oldest git the suites run on (Debian bookworm,
+ * Decision 156). The feature floor is 2.38, where --no-update-refs appeared
+ * (Decision 16); no older git has run the suites, so none is promised.
+ */
+export const MIN_GIT_VERSION = { major: 2, minor: 39 };
+/**
+ * Minimum engine versions (design 14.25, Decision 160): Node 24 is the
+ * package's engines field; Bun 1.4.4 is measured, 1.3.6 drops the watch event
+ * for a file git merge rewrites (Decision 128). Shown as the README states them.
+ */
+export const MIN_ENGINE_VERSION = {
+    node: { floor: { major: 24, minor: 0, patch: 0 }, shown: '24' },
+    bun: { floor: { major: 1, minor: 4, patch: 4 }, shown: '1.4.4' },
+};
 /**
  * Controller:
+ * 0. The engine below its floor: NOT_ELIGIBLE (ENGINE_TOO_OLD), exit 5, before
+ *    any git call (design 14.25); a version that does not parse passes.
  * 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.
+ * 2. Git older than 2.39: NOT_ELIGIBLE (GIT_TOO_OLD), exit 5.
  * 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;
@@ -18,6 +33,12 @@ export const MIN_GIT_VERSION = { major: 2, minor: 38 };
  * 4. createDaemon(paths, config).run(), its exit code returned.
  */
 export async function runCommand(input, deps) {
+    // --- Step 0: the engine floor (design 14.25) ---
+    const engineVersion = parseVersion(deps.engine.version);
+    const minimum = MIN_ENGINE_VERSION[deps.engine.kind];
+    if (engineVersion !== null && olderThan(engineVersion, minimum.floor)) {
+        return notEligible(deps, 'ENGINE_TOO_OLD', `${deps.engine.kind} ${deps.engine.version} is older than ${minimum.shown}`);
+    }
     // --- Step 1: the repository root through git, not the start directory (D9) ---
     let location;
     try {
@@ -101,9 +122,25 @@ function logConfigSources(parsed, logger) {
     }
 }
 function olderThanMinimum(version) {
-    return (version.major < MIN_GIT_VERSION.major ||
-        (version.major === MIN_GIT_VERSION.major &&
-            version.minor < MIN_GIT_VERSION.minor));
+    return olderThan(version, { ...MIN_GIT_VERSION, patch: 0 });
+}
+function olderThan(version, floor) {
+    if (version.major !== floor.major)
+        return version.major < floor.major;
+    if (version.minor !== floor.minor)
+        return version.minor < floor.minor;
+    return version.patch < floor.patch;
+}
+/** `major.minor.patch` at the start of the text (a label may follow); null when absent. */
+function parseVersion(text) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(text);
+    if (match === null)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
 }
 function notEligible(deps, code, message) {
     deps.logger.log({

package/dist/cli/exitCodes.js

@@ -10,6 +10,7 @@ const EXIT_CODE_BY_ERROR = {
     LOCK_UNREADABLE: EXIT.LOCKED,
     GIT_NOT_FOUND: EXIT.NOT_ELIGIBLE,
     GIT_TOO_OLD: EXIT.NOT_ELIGIBLE,
+    ENGINE_TOO_OLD: EXIT.NOT_ELIGIBLE,
     NOT_A_REPOSITORY: EXIT.NOT_ELIGIBLE,
     BARE_REPOSITORY: EXIT.NOT_ELIGIBLE,
     PATH_UNSUPPORTED: EXIT.NOT_ELIGIBLE,

package/dist/cli.js

@@ -2,8 +2,9 @@
 import { createRequire } from 'node:module';
 import { main } from './cli/main.js';
 /**
- * Entry: the only file that reads process.argv, process.env, process.cwd(),
- * process.execPath, process.stdout and process.stderr and sets
+ * Entry of the package's CLI: with src/index.ts and src/standalone.ts one of
+ * the three files that read process.argv, process.env, process.cwd(),
+ * process.execPath, process.stdout and process.stderr and set
  * process.exitCode. It gathers them into a Runtime and calls main.
  */
 /** package.json sits next to dist/ and src/, one level up from this file in both. */
@@ -21,13 +22,18 @@ const runtime = {
     argv: process.argv.slice(2),
     env: process.env,
     cwd: process.cwd(),
-    execPath: process.execPath,
-    // Node makes argv[1] absolute. Should it ever be missing, the hook records
-    // an empty path, finds no CLI there and lets commits through (fail open).
-    cliPath: process.argv[1] ?? '',
+    launch: {
+        kind: 'script',
+        interpreter: process.execPath,
+        // Node makes argv[1] absolute. Should it ever be missing, the hook
+        // records an empty path, finds no CLI there and lets commits through
+        // (fail open).
+        script: process.argv[1] ?? '',
+    },
     version: packageVersion(),
     platform: process.platform,
     engine: process.versions.bun === undefined ? 'node' : 'bun',
+    engineVersion: process.versions.bun ?? process.versions.node,
     stdout: process.stdout,
     stderr: process.stderr,
 };

package/dist/commit/commitLocalChangesController.d.ts

@@ -7,7 +7,7 @@ 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';
+import type { CommitMemory, HoldPolicy, 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). */
@@ -66,11 +66,19 @@ export interface CommitLocalChangesDeps {
     readonly clock: IClock;
     readonly settings: CommitSettings;
 }
+/**
+ * hold on nothing and committed (design 14.21, Decision 147): the dirty paths
+ * a pull may set aside, which are the ones this step could not commit. `only`
+ * names the paths the content guard excluded from the build whose tree was
+ * committed or found empty; `all` says every dirty path is the hooks' residue.
+ */
 export type CommitLocalChangesResult = {
     readonly kind: 'nothing';
+    readonly hold: HoldPolicy;
     readonly memory: CommitMemory;
 } | {
     readonly kind: 'committed';
+    readonly hold: HoldPolicy;
     readonly memory: CommitMemory;
 } | {
     readonly kind: 'waiting';
@@ -108,15 +116,17 @@ export type CommitLocalChanges = (input: CommitLocalChangesInput) => Promise<Com
  *    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.
- * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing;
- *    equal to memory.rejection.tree within HOOK_RETRY_MS returns waiting
+ *    Nothing staged returns nothing, hold only the excluded paths (14.21).
+ * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing
+ *    with hold all (the residue is every dirty path); equal to
+ *    memory.rejection.tree within HOOK_RETRY_MS returns waiting
  *    COMMIT_HOOK_REJECTED without running a hook.
  * 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 hooks do not run (Decision 80). The re-stage logs through
- *    residueLogger: its EXCLUDED lines repeat the first build's.
+ *    residueLogger: its EXCLUDED lines repeat the first build's; its excluded
+ *    paths are the ones committed's hold names (14.21).
  * 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

package/dist/commit/commitLocalChangesController.js

@@ -2,7 +2,7 @@ import { EnmetuError, GitCommandError } from '../contracts/errors.js';
 import { withLastMove } from '../core/commit/commitMemory.js';
 import { gitBoolean, messageFromText } from '../core/commit/commitMessage.js';
 import { repairStaleIndexController } from './repairStaleIndexController.js';
-import { stageGuardedChanges } from './stageGuardedChanges.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). */
@@ -23,15 +23,17 @@ export const MESSAGE_PATCH_CAP_BYTES = 65536;
  *    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.
- * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing;
- *    equal to memory.rejection.tree within HOOK_RETRY_MS returns waiting
+ *    Nothing staged returns nothing, hold only the excluded paths (14.21).
+ * 3. tree = committer.writeTree(); equal to memory.residueTree returns nothing
+ *    with hold all (the residue is every dirty path); equal to
+ *    memory.rejection.tree within HOOK_RETRY_MS returns waiting
  *    COMMIT_HOOK_REJECTED without running a hook.
  * 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 hooks do not run (Decision 80). The re-stage logs through
- *    residueLogger: its EXCLUDED lines repeat the first build's.
+ *    residueLogger: its EXCLUDED lines repeat the first build's; its excluded
+ *    paths are the ones committed's hold names (14.21).
  * 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
@@ -111,13 +113,16 @@ export async function commitLocalChangesController(input, deps) {
         // The preflight refuses an unborn HEAD; this guards the type.
         throw new EnmetuError('HEAD is unborn; there is nothing to commit onto', 'HEAD_UNBORN', cycleId);
     }
-    if (!(await build(parent, cycleId, deps.logger, deps))) {
-        return { kind: 'nothing', memory: unchanged };
+    const built = await build(parent, cycleId, deps.logger, deps);
+    let hold = { kind: 'only', paths: built.excluded };
+    if (!built.staged) {
+        return { kind: 'nothing', hold, memory: unchanged };
     }
     // --- Step 3: trees enmetu already knows ---
     let tree = await deps.commitIndex.committer.writeTree();
     if (tree === memory.residueTree) {
-        return { kind: 'nothing', memory: unchanged };
+        // Every dirty path is what the hooks wrote after the last commit (Decision 90).
+        return { kind: 'nothing', hold: { kind: 'all' }, memory: unchanged };
     }
     const rejection = memory.rejection;
     if (rejection !== null &&
@@ -156,8 +161,9 @@ export async function commitLocalChangesController(input, deps) {
             logger: deps.residueLogger,
             skipJsonCheck: settings.skipJsonCheck,
         });
+        hold = { kind: 'only', paths: restaged.excluded };
         if (!restaged.staged) {
-            return { kind: 'nothing', memory: unchanged };
+            return { kind: 'nothing', hold, memory: unchanged };
         }
         tree = await deps.commitIndex.committer.writeTree();
     }
@@ -192,6 +198,7 @@ export async function commitLocalChangesController(input, deps) {
     }
     return {
         kind: 'committed',
+        hold,
         memory: {
             partialStagingSince: null,
             rejection: null,
@@ -213,7 +220,7 @@ export async function commitLocalChangesController(input, deps) {
 async function runPostCommitHooks(commit, tree, cycleId, deps) {
     const mayWrite = (await deps.realHooks.hookExists('post-index-change')) ||
         (await deps.realHooks.hookExists('post-commit'));
-    const pendingBefore = mayWrite && (await build(commit, cycleId, deps.residueLogger, deps));
+    const pendingBefore = mayWrite && (await build(commit, cycleId, deps.residueLogger, deps)).staged;
     // Both run through `git hook run --ignore-missing` whatever hookExists
     // said, so what runs is git's decision alone; git ignores both exit codes,
     // and so does enmetu.
@@ -222,7 +229,7 @@ async function runPostCommitHooks(commit, tree, cycleId, deps) {
     if (!mayWrite || pendingBefore) {
         return null;
     }
-    if (!(await build(commit, cycleId, deps.residueLogger, deps))) {
+    if (!(await build(commit, cycleId, deps.residueLogger, deps)).staged) {
         return null;
     }
     const residue = await deps.commitIndex.committer.writeTree();
@@ -324,7 +331,8 @@ async function commandMessage(parent, tree, cycleId, deps) {
 /**
  * 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
- * tree, stage the guarded working tree. true when anything is staged.
+ * tree, stage the guarded working tree; staged when anything is, with the
+ * paths the content rules kept out (design 14.21).
  */
 async function build(seed, cycleId, logger, deps) {
     const { commitIndex } = deps;
@@ -334,13 +342,12 @@ async function build(seed, cycleId, logger, deps) {
         await deps.fs.remove(commitIndex.path);
     }
     await commitIndex.committer.seedFrom(seed);
-    const { staged } = await stageGuardedChanges({ cycleId }, {
+    return stageGuardedChanges({ cycleId }, {
         git: commitIndex.reader,
         writer: commitIndex.writer,
         logger,
         skipJsonCheck: deps.settings.skipJsonCheck,
     });
-    return staged;
 }
 /**
  * Step 6: under index.lock, in this order (Decisions 72, 81, 121):

package/dist/commit/stageGuardedChanges.d.ts

@@ -12,6 +12,8 @@ export interface StageGuardedDeps {
 }
 export interface StageGuardedResult {
     readonly staged: boolean;
+    /** The paths unstaged by the content rules, in git's order: the EXCLUDED lines (design 14.21). */
+    readonly excluded: readonly string[];
 }
 /**
  * Controller: stage everything, inspect the staged blobs with the shared
@@ -20,7 +22,7 @@ export interface StageGuardedResult {
  * 1. writer.stageAll(); partial logs STAGE_PARTIAL.
  * 2. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation.
  * 3. Violations: one writer.unstage(paths) call, EXCLUDED logged per path.
- * 4. staged = git.hasStagedChanges().
+ * 4. staged = git.hasStagedChanges(); excluded = the violations' paths.
  *
  * Inspecting the staged blobs rather than the working tree means what is
  * inspected is exactly what the next commit records (Decision 5). The

package/dist/commit/stageGuardedChanges.js

@@ -6,7 +6,7 @@ import { findContentViolation, MAX_SCAN_BYTES, } from '../core/content/contentRu
  * 1. writer.stageAll(); partial logs STAGE_PARTIAL.
  * 2. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation.
  * 3. Violations: one writer.unstage(paths) call, EXCLUDED logged per path.
- * 4. staged = git.hasStagedChanges().
+ * 4. staged = git.hasStagedChanges(); excluded = the violations' paths.
  *
  * Inspecting the staged blobs rather than the working tree means what is
  * inspected is exactly what the next commit records (Decision 5). The
@@ -34,10 +34,11 @@ export async function stageGuardedChanges(input, deps) {
         }
     }
     // --- Step 3: unstage the violations in one call, in git's order ---
+    const excluded = violations.map((violation) => violation.path);
     if (violations.length > 0) {
         // reset also clears unmerged entries, which git add has already turned
         // into stage-0 marker text; the bytes stay on disk for the person.
-        await deps.writer.unstage(violations.map((violation) => violation.path));
+        await deps.writer.unstage(excluded);
         for (const violation of violations) {
             deps.logger.log({
                 level: 'WARN',
@@ -47,6 +48,6 @@ export async function stageGuardedChanges(input, deps) {
             });
         }
     }
-    // --- Step 4: report whether anything is left to commit ---
-    return { staged: await deps.git.hasStagedChanges() };
+    // --- Step 4: report whether anything is left to commit, and what was kept out ---
+    return { staged: await deps.git.hasStagedChanges(), excluded };
 }

package/dist/contracts/IGitRunner.d.ts

@@ -20,6 +20,13 @@ export interface GitRunOptions {
      * repository hook this way (design 12.7, Decision 92).
      */
     readonly abort?: AbortSignal | undefined;
+    /**
+     * Runs git leading its own process group with the adapter's per-command
+     * timeout, so the timeout ends git and everything git started: the ssh of a
+     * remote command, which a signal to git alone would orphan on a dead
+     * connection (design 14.24, Decision 158). The three remote commands set it.
+     */
+    readonly killGroup?: boolean | undefined;
     /**
      * Sets GIT_REFLOG_ACTION for this call only, so the entries git writes to
      * HEAD's reflog carry this action instead of the command's name: enmetu's

package/dist/contracts/ISyncCycle.d.ts

@@ -7,6 +7,12 @@ export interface SyncCycleInput {
     readonly commitMemory?: CommitMemory | undefined;
     /** Consecutive cycles whose rebase git refused to start (Decision 82); absent is 0. */
     readonly notStartedRebases?: number | undefined;
+    /**
+     * The previous cycle deferred the pull for a save made during a cycle
+     * (TREE_CHANGING); the pull waits until a cycle commits nothing (Decision
+     * 162). Absent is false.
+     */
+    readonly pullDeferred?: boolean | undefined;
 }
 export interface SyncCycleResult {
     readonly outcome: CycleOutcome;
@@ -16,6 +22,8 @@ export interface SyncCycleResult {
     readonly commitMemory?: CommitMemory | undefined;
     /** The count for the next cycle (Decision 82); absent is 0. */
     readonly notStartedRebases?: number | undefined;
+    /** Whether the pull is still deferred for the next cycle (Decision 162); absent is false. */
+    readonly pullDeferred?: boolean | undefined;
 }
 /** One cycle with its deps bound: a closure over syncCycleController, built by the composition root. */
 export interface ISyncCycle {

package/dist/contracts/errors.d.ts

@@ -1,5 +1,5 @@
 import type { HaltCode } from './IHaltStore.js';
-export type EnmetuErrorCode = 'GIT_NOT_FOUND' | 'GIT_TIMEOUT' | 'GIT_ABORTED' | 'GIT_FAILED' | 'GIT_INDEX_LOCKED' | 'GIT_OUTPUT_UNPARSEABLE' | 'CONFIG_INVALID_JSON' | 'CONFIG_INVALID_VALUE' | 'NOT_A_REPOSITORY' | 'BARE_REPOSITORY' | 'GIT_TOO_OLD' | 'PATH_UNSUPPORTED' | 'OPERATION_IN_PROGRESS' | 'DETACHED_HEAD' | 'HEAD_UNBORN' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'IDENTITY_MISSING' | 'LOCK_HELD' | 'LOCK_UNREADABLE' | 'HALTED' | 'USAGE';
+export type EnmetuErrorCode = 'GIT_NOT_FOUND' | 'GIT_TIMEOUT' | 'GIT_ABORTED' | 'GIT_FAILED' | 'GIT_INDEX_LOCKED' | 'GIT_OUTPUT_UNPARSEABLE' | 'CONFIG_INVALID_JSON' | 'CONFIG_INVALID_VALUE' | 'NOT_A_REPOSITORY' | 'BARE_REPOSITORY' | 'GIT_TOO_OLD' | 'ENGINE_TOO_OLD' | 'PATH_UNSUPPORTED' | 'OPERATION_IN_PROGRESS' | 'DETACHED_HEAD' | 'HEAD_UNBORN' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'IDENTITY_MISSING' | 'LOCK_HELD' | 'LOCK_UNREADABLE' | 'HALTED' | 'USAGE';
 export type GitCommandErrorCode = 'GIT_NOT_FOUND' | 'GIT_TIMEOUT' | 'GIT_ABORTED' | 'GIT_FAILED' | 'GIT_INDEX_LOCKED';
 export type ConfigErrorCode = 'CONFIG_INVALID_JSON' | 'CONFIG_INVALID_VALUE';
 export type PreflightErrorCode = 'NOT_A_REPOSITORY' | 'BARE_REPOSITORY' | 'GIT_TOO_OLD' | 'PATH_UNSUPPORTED' | 'OPERATION_IN_PROGRESS' | 'DETACHED_HEAD' | 'HEAD_UNBORN' | 'NO_UPSTREAM' | 'UPSTREAM_NOT_REMOTE' | 'IDENTITY_MISSING';

package/dist/contracts/library.d.ts

@@ -29,7 +29,7 @@ export interface CommitChange {
     readonly root: string;
     /** The commit's only parent. */
     readonly parent: string;
-    /** The commit's tree; `git diff-tree -r <parent> <tree>` lists the change. */
+    /** The commit's tree; `git diff-tree -r -M <parent> <tree>` lists the change. */
     readonly tree: string;
     /**
      * The person's commitMessageCommand on this change: its message, or null

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' | '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';
+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';