@fluado/enmetu 0.4.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
@@ -17,42 +19,42 @@ Most auto-commit tools commit and push. enmetu also handles what goes wrong:
 - **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.4.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`.
@@ -247,7 +249,7 @@ Overlapping git commands:
 | `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
 

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/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/runtime.d.ts

@@ -1,20 +1,41 @@
 import type { ITextSink } from './ITextSink.js';
-/** Everything the process gives enmetu, gathered once by src/cli.ts. */
+/**
+ * How this enmetu is started again, recorded in the pre-commit hook (designs
+ * 1.7, 13.1, 14.22).
+ */
+export type Launch = 
+/**
+ * An interpreter and the CLI script: node or bun with dist/cli.js. The
+ * interpreter is process.execPath, absolute under Node, a bare name under a
+ * Bun started by name (13.1); the script is process.argv[1], which Node
+ * makes absolute.
+ */
+{
+    readonly kind: 'script';
+    readonly interpreter: string;
+    readonly script: string;
+}
+/** The standalone executable of design 14.22 (process.execPath): it runs its own hook check. */
+ | {
+    readonly kind: 'executable';
+    readonly path: string;
+};
+/** Everything the process gives enmetu, gathered once by an entry (src/cli.ts, src/index.ts, src/standalone.ts). */
 export interface Runtime {
     /** Arguments after the node binary and the script. */
     readonly argv: readonly string[];
     /** Base environment for every git child. */
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly cwd: string;
-    /** Absolute node binary, recorded in the hook. */
-    readonly execPath: string;
-    /** Absolute path of the CLI script (Node resolves argv[1]), recorded in the hook. */
-    readonly cliPath: string;
+    /** Recorded in the hook. */
+    readonly launch: Launch;
     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';
+    /** Its version: process.versions.bun under Bun, process.versions.node under Node (design 14.25). */
+    readonly engineVersion: string;
     readonly stdout: ITextSink;
     readonly stderr: ITextSink;
 }

package/dist/contracts/syncTypes.d.ts

@@ -42,8 +42,11 @@ export type CycleOutcome = {
     readonly reason: PauseReason;
 } | {
     readonly kind: 'busy';
-} | {
+}
+/** The remote could not be reached; detail is git's first line of reason (design 14.24, Decision 159). */
+ | {
     readonly kind: 'offline';
+    readonly detail: string;
 } | {
     readonly kind: 'conflict';
 } | {

package/dist/enmetuInstances.d.ts

@@ -31,9 +31,9 @@ export declare function createRecoveryDeps(paths: RepositoryPaths, config: Enmet
  */
 export declare function createDaemon(paths: RepositoryPaths, config: EnmetuConfig, runtime: Runtime, processHost?: IProcessHost | undefined, commitMessage?: CommitMessageWriter | undefined): IDaemon;
 /**
- * The daemon's hook installer for one repository (design 13.1): it records
- * Runtime.execPath, resolved through the PATH enmetu was started with when it
- * is a bare name, and Runtime.cliPath.
+ * The daemon's hook installer for one repository (designs 13.1, 14.22): it
+ * records Runtime.launch, its interpreter or executable resolved through the
+ * PATH enmetu was started with when it is a bare name.
  */
 export declare function createHookInstaller(paths: RepositoryPaths, config: EnmetuConfig, runtime: Runtime): IHookInstaller;
 export declare function createRunDeps(runtime: Runtime): RunCommandDeps;

package/dist/enmetuInstances.js

@@ -107,9 +107,9 @@ export function createDaemon(paths, config, runtime, processHost, commitMessage)
     return new Daemon({ root: paths.root, quietMs: config.quietMs, pollMs: config.pollMs }, lockFor(paths, parts.fs, host, parts.clock), parts.halt, recovery, preflight, hookInstaller, watcherFor(paths.root, runtime), scheduler, host, parts.logger, state, parts.clock);
 }
 /**
- * The daemon's hook installer for one repository (design 13.1): it records
- * Runtime.execPath, resolved through the PATH enmetu was started with when it
- * is a bare name, and Runtime.cliPath.
+ * The daemon's hook installer for one repository (designs 13.1, 14.22): it
+ * records Runtime.launch, its interpreter or executable resolved through the
+ * PATH enmetu was started with when it is a bare name.
  */
 export function createHookInstaller(paths, config, runtime) {
     return hookInstallerOf(guardedRepositoryParts(paths, config.gitTimeoutMs, runtime), paths, config, runtime);
@@ -117,7 +117,7 @@ export function createHookInstaller(paths, config, runtime) {
 // Null Object: the daemon has no branch for installHook (section 2).
 function hookInstallerOf(parts, paths, config, runtime) {
     return config.installHook
-        ? new PreCommitHookInstaller(parts.git, parts.fs, paths.hooksDir, { nodePath: runtime.execPath, cliPath: runtime.cliPath }, runtime.env.PATH)
+        ? new PreCommitHookInstaller(parts.git, parts.fs, paths.hooksDir, runtime.launch, runtime.env.PATH)
         : new NullHookInstaller();
 }
 export function createRunDeps(runtime) {
@@ -127,6 +127,7 @@ export function createRunDeps(runtime) {
         fs,
         readGitConfig: gitConfigReaderFor(runtime, fs),
         logger: new StderrLoggerAdapter(runtime.stderr, new SystemClockAdapter()),
+        engine: { kind: runtime.engine, version: runtime.engineVersion },
         createDaemon: (paths, config) => createDaemon(paths, config, runtime),
     };
 }
@@ -351,6 +352,7 @@ export function createEmbeddedRunDeps(runtime, commitMessage) {
             fs,
             readGitConfig: gitConfigReaderFor(runtime, fs),
             logger: new StderrLoggerAdapter(runtime.stderr, new SystemClockAdapter()),
+            engine: { kind: runtime.engine, version: runtime.engineVersion },
             createDaemon: (paths, config) => createDaemon(paths, config, runtime, processHost, commitMessage),
         },
         requestStop: () => processHost.requestStop(),

package/dist/hooks/hookScript.d.ts

@@ -1,15 +1,10 @@
+import type { Launch } from '../contracts/runtime.js';
 export declare const HOOK_MARKER = "# enmetu-managed-hook v1";
-export interface HookScriptPaths {
-    /**
-     * The interpreter recorded at install time: an absolute path, or the bare
-     * name no search path entry held (design 13.1).
-     */
-    readonly nodePath: string;
-    /** Absolute enmetu CLI script recorded at install time. */
-    readonly cliPath: string;
-}
-/** The POSIX sh pre-commit hook of design 1.7; a single quote becomes '\''. */
-export declare function renderHookScript(paths: HookScriptPaths): string;
+/**
+ * The POSIX sh pre-commit hook of design 1.7 in the shape the launch needs
+ * (design 14.22); a single quote becomes '\''.
+ */
+export declare function renderHookScript(launch: Launch): string;
 /** true when the content carries the enmetu marker line. */
 export declare function isEnmetuHook(content: string): boolean;
 /**

package/dist/hooks/hookScript.js

@@ -1,14 +1,24 @@
 export const HOOK_MARKER = '# enmetu-managed-hook v1';
-/** The POSIX sh pre-commit hook of design 1.7; a single quote becomes '\''. */
-export function renderHookScript(paths) {
+const HEADER = [
+    '#!/bin/sh',
+    HOOK_MARKER,
+    '# Written by enmetu at startup; set "installHook": false in enmetu.config.json to stop that.',
+    '# Refuses a commit that records conflict markers or a .json file that does not parse.',
+    '# To commit anyway: git commit --no-verify',
+];
+/**
+ * The POSIX sh pre-commit hook of design 1.7 in the shape the launch needs
+ * (design 14.22); a single quote becomes '\''.
+ */
+export function renderHookScript(launch) {
+    const body = launch.kind === 'script' ? scriptForm(launch) : executableForm(launch);
+    return [...HEADER, ...body, ''].join('\n');
+}
+/** The interpreter and the CLI script, as src/cli.ts and src/index.ts record them. */
+function scriptForm(launch) {
     return [
-        '#!/bin/sh',
-        HOOK_MARKER,
-        '# Written by enmetu at startup; set "installHook": false in enmetu.config.json to stop that.',
-        '# Refuses a commit that records conflict markers or a .json file that does not parse.',
-        '# To commit anyway: git commit --no-verify',
-        `ENMETU_NODE=${shellQuote(paths.nodePath)}`,
-        `ENMETU_CLI=${shellQuote(paths.cliPath)}`,
+        `ENMETU_NODE=${shellQuote(launch.interpreter)}`,
+        `ENMETU_CLI=${shellQuote(launch.script)}`,
         // The recorded interpreter may vanish with an upgrade (nvm, a moved Bun)
         // or be a bare name no PATH entry held at install time: the same name on
         // the commit's PATH keeps a Bun-only machine checking, node on PATH is
@@ -26,8 +36,22 @@ export function renderHookScript(paths) {
         'fi',
         'echo "enmetu: pre-commit check skipped (node or enmetu not found)" >&2',
         'exit 0',
-        '',
-    ].join('\n');
+    ];
+}
+/** The standalone executable, which runs its own check (design 14.22, Decision 151). */
+function executableForm(launch) {
+    return [
+        `ENMETU_BIN=${shellQuote(launch.path)}`,
+        // The recorded file may be gone (reinstalled elsewhere, another clone of
+        // the hook's machine): the same name on the commit's PATH, then enmetu on
+        // PATH, then fail open, the shape of Decision 102's line.
+        '[ -x "$ENMETU_BIN" ] || ENMETU_BIN="$(command -v "${ENMETU_BIN##*/}" 2>/dev/null || command -v enmetu 2>/dev/null)"',
+        'if [ -n "$ENMETU_BIN" ]; then',
+        '  exec "$ENMETU_BIN" hook pre-commit',
+        'fi',
+        'echo "enmetu: pre-commit check skipped (enmetu not found)" >&2',
+        'exit 0',
+    ];
 }
 /** true when the content carries the enmetu marker line. */
 export function isEnmetuHook(content) {

package/dist/hooks/preCommitHookInstaller.d.ts

@@ -1,32 +1,34 @@
 import type { IFileSystem } from '../contracts/IFileSystem.js';
 import type { IGitConfigReader } from '../contracts/IGitConfigReader.js';
 import type { HookInstallResult, IHookInstaller } from '../contracts/IHookInstaller.js';
-import { type HookScriptPaths } from './hookScript.js';
+import type { Launch } from '../contracts/runtime.js';
 /**
  * Service: installs <hooksDir>/pre-commit following rules 1 to 5 of design
  * 1.7 (D10). Reads git configuration only through IGitConfigReader, so it
  * cannot write any; never overwrites a hook without the enmetu marker.
  * A bare-name interpreter (Bun started by name reports the bare name "bun"
- * for its own executable path) is resolved through searchPath before the
- * hook is rendered (design 13.1, Decision 102).
+ * for its own executable path) or executable is resolved through searchPath
+ * before the hook is rendered (designs 13.1 and 14.22, Decision 102).
  */
 export declare class PreCommitHookInstaller implements IHookInstaller {
     private readonly config;
     private readonly fs;
     private readonly hooksDir;
-    private readonly script;
+    private readonly launch;
     /** The PATH the daemon was started with (Runtime.env.PATH); absent: no resolution. */
     private readonly searchPath?;
-    constructor(config: IGitConfigReader, fs: IFileSystem, hooksDir: string, script: HookScriptPaths, 
+    constructor(config: IGitConfigReader, fs: IFileSystem, hooksDir: string, launch: Launch, 
     /** The PATH the daemon was started with (Runtime.env.PATH); absent: no resolution. */
     searchPath?: string | undefined);
     ensure(): Promise<HookInstallResult>;
     private install;
+    /** The launch with its interpreter or executable resolved for the record. */
+    private resolvedLaunch;
     /**
-     * The interpreter to record: an absolute nodePath unchanged; for a bare
-     * name, <dir>/<name> for the first absolute search path entry where that
-     * is an executable file or a link; else the bare name, which the hook
-     * looks up on the commit's PATH.
+     * The file to record: an absolute name unchanged; for a bare name,
+     * <dir>/<name> for the first absolute search path entry where that is an
+     * executable file or a link; else the bare name, which the hook looks up
+     * on the commit's PATH.
      */
-    private interpreterPath;
+    private resolve;
 }

package/dist/hooks/preCommitHookInstaller.js

@@ -9,22 +9,22 @@ const OTHER_LANGUAGE_NOTE = 'A hook in another language runs "enmetu hook pre-co
  * 1.7 (D10). Reads git configuration only through IGitConfigReader, so it
  * cannot write any; never overwrites a hook without the enmetu marker.
  * A bare-name interpreter (Bun started by name reports the bare name "bun"
- * for its own executable path) is resolved through searchPath before the
- * hook is rendered (design 13.1, Decision 102).
+ * for its own executable path) or executable is resolved through searchPath
+ * before the hook is rendered (designs 13.1 and 14.22, Decision 102).
  */
 export class PreCommitHookInstaller {
     config;
     fs;
     hooksDir;
-    script;
+    launch;
     searchPath;
-    constructor(config, fs, hooksDir, script, 
+    constructor(config, fs, hooksDir, launch, 
     /** The PATH the daemon was started with (Runtime.env.PATH); absent: no resolution. */
     searchPath) {
         this.config = config;
         this.fs = fs;
         this.hooksDir = hooksDir;
-        this.script = script;
+        this.launch = launch;
         this.searchPath = searchPath;
     }
     async ensure() {
@@ -73,11 +73,8 @@ export class PreCommitHookInstaller {
                 instruction: `${target} exists and is not enmetu's. To add enmetu's check, add this line to it: ${pathInvocationLine()}. ${OTHER_LANGUAGE_NOTE}`,
             };
         }
-        // 4. An enmetu hook is rewritten only when the recorded paths changed.
-        const rendered = renderHookScript({
-            nodePath: await this.interpreterPath(),
-            cliPath: this.script.cliPath,
-        });
+        // 4. An enmetu hook is rewritten only when the recorded launch changed.
+        const rendered = renderHookScript(await this.resolvedLaunch());
         if (existing === rendered) {
             return { kind: 'unchanged' };
         }
@@ -89,14 +86,24 @@ export class PreCommitHookInstaller {
         });
         return { kind: existing === null ? 'installed' : 'updated' };
     }
+    /** The launch with its interpreter or executable resolved for the record. */
+    async resolvedLaunch() {
+        if (this.launch.kind === 'script') {
+            return {
+                kind: 'script',
+                interpreter: await this.resolve(this.launch.interpreter),
+                script: this.launch.script,
+            };
+        }
+        return { kind: 'executable', path: await this.resolve(this.launch.path) };
+    }
     /**
-     * The interpreter to record: an absolute nodePath unchanged; for a bare
-     * name, <dir>/<name> for the first absolute search path entry where that
-     * is an executable file or a link; else the bare name, which the hook
-     * looks up on the commit's PATH.
+     * The file to record: an absolute name unchanged; for a bare name,
+     * <dir>/<name> for the first absolute search path entry where that is an
+     * executable file or a link; else the bare name, which the hook looks up
+     * on the commit's PATH.
      */
-    async interpreterPath() {
-        const name = this.script.nodePath;
+    async resolve(name) {
         if (name.includes('/') || this.searchPath === undefined) {
             return name;
         }

package/dist/index.js

@@ -16,13 +16,17 @@ function processRuntime() {
         argv: [],
         env: process.env,
         cwd: process.cwd(),
-        execPath: process.execPath,
-        // The CLI ships next to this file; the hook records it like `enmetu run`
-        // records its own argv[1].
-        cliPath: fileURLToPath(new URL('./cli.js', import.meta.url)),
+        launch: {
+            kind: 'script',
+            interpreter: process.execPath,
+            // The CLI ships next to this file; the hook records it like
+            // `enmetu run` records its own argv[1].
+            script: fileURLToPath(new URL('./cli.js', import.meta.url)),
+        },
         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/library/enmetuLibrary.js

@@ -39,11 +39,11 @@ function embeddedRuntime(options, runtime) {
         argv: [],
         env: options.env ?? runtime.env,
         cwd: runtime.cwd,
-        execPath: runtime.execPath,
-        cliPath: runtime.cliPath,
+        launch: runtime.launch,
         version: runtime.version,
         platform: runtime.platform,
         engine: runtime.engine,
+        engineVersion: runtime.engineVersion,
         stdout: runtime.stdout,
         stderr: options.log ?? runtime.stderr,
     };

package/dist/sync/syncCycleController.d.ts

@@ -57,7 +57,10 @@ export interface SyncCycleDeps {
  *    returned (Decision 84).
  *    deferred (a save made during the cycle is dirty): UNPUSHED reported,
  *    waiting TREE_CHANGING returned, the refusal count left as it is
- *    (Decision 147).
+ *    (Decision 147), and pullDeferred carried to the next cycle: while it is
+ *    carried, a cycle that committed reports UNPUSHED and returns waiting
+ *    TREE_CHANGING before integrate; the first cycle that commits nothing
+ *    pulls and clears it (Decision 162).
  *    not-started: the count of consecutive refusals (input.notStartedRebases)
  *    goes up by one; the first logs REBASE_NOT_STARTED with git's first stderr
  *    line; UNPUSHED is reported; the outcome is busy, or paused REBASE_REFUSED

package/dist/sync/syncCycleController.js

@@ -43,7 +43,10 @@ export const REBASE_REFUSED_AFTER = 3;
  *    returned (Decision 84).
  *    deferred (a save made during the cycle is dirty): UNPUSHED reported,
  *    waiting TREE_CHANGING returned, the refusal count left as it is
- *    (Decision 147).
+ *    (Decision 147), and pullDeferred carried to the next cycle: while it is
+ *    carried, a cycle that committed reports UNPUSHED and returns waiting
+ *    TREE_CHANGING before integrate; the first cycle that commits nothing
+ *    pulls and clears it (Decision 162).
  *    not-started: the count of consecutive refusals (input.notStartedRebases)
  *    goes up by one; the first logs REBASE_NOT_STARTED with git's first stderr
  *    line; UNPUSHED is reported; the outcome is busy, or paused REBASE_REFUSED
@@ -63,6 +66,7 @@ export async function syncCycleController(input, deps) {
     const carried = {
         commitMemory: input.commitMemory,
         notStartedRebases: input.notStartedRebases,
+        pullDeferred: input.pullDeferred,
     };
     const outcome = (cycleOutcome) => resultOf(cycleOutcome, null, carried);
     try {
@@ -123,6 +127,9 @@ async function runCycle(input, deps, carried, outcome) {
     // Which dirty paths the pull may set aside (design 14.21): after a clean
     // status none, so a path dirty at step 9 is a save made during the cycle.
     let hold = HOLD_NOTHING;
+    // Whether this cycle's commit step committed: with a deferred pull carried
+    // in, that defers the pull once more (Decision 162).
+    let committedThisCycle = false;
     if ((await deps.git.status()).length > 0) {
         // A person's merge, cherry-pick or revert that stopped after step 2 is in
         // that status; the commit step would only find it under index.lock (Decision 52).
@@ -154,6 +161,7 @@ async function runCycle(input, deps, carried, outcome) {
         }
         if (committed.kind === 'committed') {
             committedFrom = committed.memory.lastMove?.from ?? null;
+            committedThisCycle = true;
         }
     }
     else if (carried.commitMemory !== undefined) {
@@ -172,7 +180,10 @@ async function runCycle(input, deps, carried, outcome) {
     let verifiedSha = await deps.git.resolveCommit(verifiedRef);
     if (remoteHead.kind === 'unreachable') {
         await reportUnpushedAgainstLastKnown(trackingSha ?? verifiedSha, upstream, cycleId, deps);
-        return outcome({ kind: 'offline' });
+        return outcome({
+            kind: 'offline',
+            detail: offlineDetail(remoteHead.detail),
+        });
     }
     if (remoteHead.kind === 'absent') {
         // A deleted remote branch is never recreated by enmetu, so commits pile
@@ -191,7 +202,7 @@ async function runCycle(input, deps, carried, outcome) {
         const fetched = await deps.writer.fetch(upstream.remote, upstream.remoteRef, incomingRefFor(branchRef));
         if (fetched.kind === 'failed') {
             await reportUnpushedAgainstLastKnown(trackingSha ?? verifiedSha, upstream, cycleId, deps);
-            return outcome({ kind: 'offline' });
+            return outcome({ kind: 'offline', detail: offlineDetail(fetched.detail) });
         }
     }
     // Checked even when the fetch was skipped: a person's own fetch may already
@@ -214,6 +225,11 @@ async function runCycle(input, deps, carried, outcome) {
     // --- Step 9: integrate when behind ---
     if (behind === 0) {
         carried.notStartedRebases = resetCount(carried.notStartedRebases);
+        // A cycle that commits nothing ends a deferral; a committing one keeps
+        // it, the writer may still be at work, and pushes as before (Decision 162).
+        if (!committedThisCycle) {
+            carried.pullDeferred = resetFlag(carried.pullDeferred);
+        }
     }
     else {
         // git rebase refuses an index that differs from HEAD (Decision 84). A
@@ -226,6 +242,16 @@ async function runCycle(input, deps, carried, outcome) {
             reportUnpushed(ahead, upstream, cycleId, deps);
             return outcome({ kind: 'waiting', reason: waiting });
         }
+        // After a deferral for a save made during a cycle, a cycle that commits
+        // defers again; the pull runs in the first cycle whose commit step finds
+        // nothing new, as the WAITING line says (Decision 162). A check at one
+        // instant is not enough: a file saved every 40 ms is clean right after
+        // each commit, and a rebase started then walks it through every replayed
+        // version (CodeFloe run 1, 2026-11-08).
+        if (carried.pullDeferred === true && committedThisCycle) {
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome({ kind: 'waiting', reason: 'TREE_CHANGING' });
+        }
         const pulledFrom = committedFrom ?? (await deps.git.headCommit());
         const integrated = await deps.integrate({
             cycleId,
@@ -236,10 +262,13 @@ async function runCycle(input, deps, carried, outcome) {
             hold,
         });
         if (integrated.kind === 'deferred') {
-            // The next cycle commits the save first; the runner logs WAITING once.
+            // The next cycle commits the save first and pulls only once a cycle
+            // commits nothing (Decision 162); the runner logs WAITING once.
+            carried.pullDeferred = true;
             reportUnpushed(ahead, upstream, cycleId, deps);
             return outcome({ kind: 'waiting', reason: 'TREE_CHANGING' });
         }
+        carried.pullDeferred = resetFlag(carried.pullDeferred);
         if (integrated.kind === 'not-started') {
             const refusals = (carried.notStartedRebases ?? 0) + 1;
             carried.notStartedRebases = refusals;
@@ -318,8 +347,13 @@ function resultOf(cycleOutcome, conflict, carried) {
         conflict,
         commitMemory: carried.commitMemory,
         notStartedRebases: carried.notStartedRebases,
+        pullDeferred: carried.pullDeferred,
     };
 }
+/** A flag the input carried goes back to false; an absent one stays absent, which means false. */
+function resetFlag(flag) {
+    return flag === undefined ? undefined : false;
+}
 /** A count the input carried goes back to 0; an absent one stays absent, which means 0. */
 function resetCount(count) {
     return count === undefined ? undefined : 0;
@@ -352,6 +386,15 @@ function reportUnpushed(ahead, upstream, cycleId, deps) {
  * observation of the remote; the verified ref covers a tracking ref that
  * `git fetch --prune` removed after the remote branch was deleted.
  */
+/**
+ * What git said, for the OFFLINE line (Decision 159): its first line is ssh's
+ * "Permission denied (publickey)." or "Connection refused", or the adapter's
+ * timeout message; the rest is git's generic advice.
+ */
+function offlineDetail(detail) {
+    const line = firstLine(detail);
+    return line === '' ? 'no detail from git' : line;
+}
 async function reportUnpushedAgainstLastKnown(lastKnownSha, upstream, cycleId, deps) {
     if (lastKnownSha === null) {
         deps.logger.log({

package/dist/sync/syncCycleRunner.js

@@ -34,10 +34,12 @@ export class SyncCycleRunner {
             this.knownConflict = result.conflict;
             if (this.carried !== null ||
                 result.commitMemory !== undefined ||
-                result.notStartedRebases !== undefined) {
+                result.notStartedRebases !== undefined ||
+                result.pullDeferred !== undefined) {
                 this.carried = {
                     commitMemory: result.commitMemory ?? EMPTY_COMMIT_MEMORY,
                     notStartedRebases: result.notStartedRebases ?? 0,
+                    pullDeferred: result.pullDeferred ?? false,
                 };
             }
             this.reportQuietTransition(result.outcome, cycleId);
@@ -65,6 +67,7 @@ export class SyncCycleRunner {
             knownConflict: this.knownConflict,
             commitMemory: this.carried.commitMemory,
             notStartedRebases: this.carried.notStartedRebases,
+            pullDeferred: this.carried.pullDeferred,
         };
     }
     reportQuietTransition(outcome, cycleId) {
@@ -133,7 +136,7 @@ function quietEntry(outcome, cycleId) {
             return {
                 level: 'WARN',
                 code: 'OFFLINE',
-                message: 'remote unreachable; retrying on every poll',
+                message: `remote unreachable (${outcome.detail}); retrying on every poll`,
                 cycleId,
             };
         case 'waiting':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluado/enmetu",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Keeps one git working tree committed and in sync with its upstream.",
   "license": "MIT",
   "author": "fluado UG (haftungsbeschränkt)",
@@ -20,7 +20,8 @@
     "dist"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=24",
+    "bun": ">=1.4.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.8",