@fluado/enmetu 0.3.0 → 0.4.0

package/README.md

@@ -14,7 +14,7 @@ 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.
@@ -52,7 +52,7 @@ Keep `--bun`: without it, `bunx` runs enmetu with Node when Node is installed.
 
 ### Pinning
 
-Add the version for repeatable runs: `@fluado/enmetu@0.3.0`.
+Add the version for repeatable runs: `@fluado/enmetu@0.4.0`.
 
 ## Commands
 
@@ -190,6 +190,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,12 +232,15 @@ 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 |
@@ -247,7 +251,7 @@ Overlapping git commands:
 
 ## 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/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/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';

package/dist/contracts/syncTypes.d.ts

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

package/dist/contracts/syncTypes.js

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

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

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

package/dist/core/quarantine/restoreWarnings.js

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

package/dist/core/state/stateGuards.js

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

package/dist/core/status/statusHeadline.js

@@ -69,6 +69,9 @@ function runningHeadline(record, uncommitted, unpushed) {
             if (record.reason === 'COMMIT_HOOK_REJECTED') {
                 return `waiting: a commit hook rejected the last commit since ${since}, ${work}`;
             }
+            if (record.reason === 'TREE_CHANGING') {
+                return `waiting: a save landed during the last cycle since ${since}; the pull waits for a quiet cycle, ${work}`;
+            }
             return `waiting:${reasonText(record)} since ${since}, ${work}`;
         case 'paused':
             return `paused:${reasonText(record)} since ${since}, ${work}`;

package/dist/sync/integrateUpstreamController.d.ts

@@ -6,7 +6,7 @@ import type { ILogger } from '../contracts/ILogger.js';
 import type { IOperationJournal } from '../contracts/IOperationJournal.js';
 import type { IPathQuarantine } from '../contracts/IPathQuarantine.js';
 import type { IOrphanedCommitRecorder } from '../contracts/IStateRecorder.js';
-import type { ConflictKey, PauseReason } from '../contracts/syncTypes.js';
+import type { ConflictKey, HoldPolicy, PauseReason } from '../contracts/syncTypes.js';
 export interface IntegrateUpstreamInput {
     readonly cycleId: string;
     /** The branch the cycle resolved its upstream for. */
@@ -16,6 +16,8 @@ export interface IntegrateUpstreamInput {
     /** Commits the upstream has that HEAD lacks, for the PULLED line. */
     readonly behind: number;
     readonly knownConflict: ConflictKey | null;
+    /** Which dirty tracked paths step 2 may hold (design 14.21, Decision 147). */
+    readonly hold: HoldPolicy;
 }
 export interface IntegrateUpstreamDeps {
     readonly git: IGitReader;
@@ -51,6 +53,14 @@ export type IntegrateUpstreamResult = {
 } | {
     readonly kind: 'halted';
     readonly code: HaltCode;
+}
+/**
+ * Dirty tracked paths the hold policy does not name were found: saves made
+ * during the cycle. Nothing was held or rebased (design 14.21, Decision 147).
+ */
+ | {
+    readonly kind: 'deferred';
+    readonly paths: readonly string[];
 };
 /**
  * The integrate step with its deps bound, the shape the sync cycle consumes. The
@@ -63,7 +73,11 @@ export type IntegrateUpstream = (input: IntegrateUpstreamInput) => Promise<Integ
  * paths held aside (design 1.11).
  *
  * 1. head = git.headCommit(); an identical knownConflict logs CONFLICT and returns it (Decision 11).
- * 2. Dirty tracked paths: quarantine.hold; pending returns busy, unsupported pauses QUARANTINE_UNSUPPORTED.
+ * 2. Dirty tracked paths: any the hold policy does not name is a save made
+ *    during the cycle, and the step returns deferred with those paths, nothing
+ *    held or rebased (design 14.21, Decision 147). Otherwise HELD names the
+ *    paths (Decision 148) and quarantine.hold runs; pending returns busy,
+ *    unsupported pauses QUARANTINE_UNSUPPORTED.
  * 3. From here on in try/finally:
  *    a. git.repositoryState() again: operation pauses FOREIGN_OPERATION, indexLocked returns busy,
  *       another branch pauses BRANCH_CHANGED.

package/dist/sync/integrateUpstreamController.js

@@ -9,7 +9,11 @@ const SHORT_SHA_LENGTH = 7;
  * paths held aside (design 1.11).
  *
  * 1. head = git.headCommit(); an identical knownConflict logs CONFLICT and returns it (Decision 11).
- * 2. Dirty tracked paths: quarantine.hold; pending returns busy, unsupported pauses QUARANTINE_UNSUPPORTED.
+ * 2. Dirty tracked paths: any the hold policy does not name is a save made
+ *    during the cycle, and the step returns deferred with those paths, nothing
+ *    held or rebased (design 14.21, Decision 147). Otherwise HELD names the
+ *    paths (Decision 148) and quarantine.hold runs; pending returns busy,
+ *    unsupported pauses QUARANTINE_UNSUPPORTED.
  * 3. From here on in try/finally:
  *    a. git.repositoryState() again: operation pauses FOREIGN_OPERATION, indexLocked returns busy,
  *       another branch pauses BRANCH_CHANGED.
@@ -65,8 +69,24 @@ export async function integrateUpstreamController(input, deps) {
             entry.worktree === 'D' ||
             entry.worktree === 'T'))
         .map((entry) => entry.path);
+    // A dirty path the commit step could have committed is a save that landed
+    // since its add -A: holding it would rewrite a file the person is editing
+    // (design 14.21). The pull waits for a cycle that commits it first.
+    const policy = input.hold;
+    const fresh = policy.kind === 'all'
+        ? []
+        : dirty.filter((path) => !policy.paths.includes(path));
+    if (fresh.length > 0) {
+        return { kind: 'deferred', paths: fresh };
+    }
     let held = false;
     if (dirty.length > 0) {
+        deps.logger.log({
+            level: 'WARN',
+            code: 'HELD',
+            message: `set aside for the pull, showing the committed version until RESTORED: ${dirty.join(', ')}`,
+            cycleId,
+        });
         const hold = await deps.quarantine.hold(dirty);
         if (hold.kind === 'pending') {
             return { kind: 'busy' };

package/dist/sync/syncCycleController.d.ts

@@ -42,7 +42,9 @@ export interface SyncCycleDeps {
  *    memory (design 12.7); busy and paused return, committed and nothing go
  *    on, waiting goes on and is the outcome unless a later step returns
  *    something else. The check right before the commit is the commit step's,
- *    under index.lock.
+ *    under index.lock. The hold policy for step 9 (design 14.21): the commit
+ *    step's after committed or nothing, all after a hook rejection, nothing
+ *    after a clean status.
  * 6. Remote check: ls-remote, tracking ref, verified ref (seeded from tracking when missing).
  * 7. Verify and fetch: fetch into the incoming ref when the remote moved; the remote sha
  *    must descend from the verified sha, else halt UPSTREAM_REWRITTEN; then move the
@@ -53,6 +55,9 @@ export interface SyncCycleDeps {
  *    git.hasStagedChanges() says the real index differs from HEAD (git would
  *    refuse the rebase), integrate is skipped, UNPUSHED reported and waiting
  *    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).
  *    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

@@ -1,5 +1,5 @@
 import { EnmetuError } from '../contracts/errors.js';
-import { EMPTY_COMMIT_MEMORY, } from '../contracts/syncTypes.js';
+import { EMPTY_COMMIT_MEMORY, HOLD_NOTHING, } from '../contracts/syncTypes.js';
 import { withLastMove } from '../core/commit/commitMemory.js';
 import { withCycleId } from '../core/errors/withCycleId.js';
 import { incomingRefFor, verifiedRefFor } from '../core/git/enmetuRefs.js';
@@ -28,7 +28,9 @@ export const REBASE_REFUSED_AFTER = 3;
  *    memory (design 12.7); busy and paused return, committed and nothing go
  *    on, waiting goes on and is the outcome unless a later step returns
  *    something else. The check right before the commit is the commit step's,
- *    under index.lock.
+ *    under index.lock. The hold policy for step 9 (design 14.21): the commit
+ *    step's after committed or nothing, all after a hook rejection, nothing
+ *    after a clean status.
  * 6. Remote check: ls-remote, tracking ref, verified ref (seeded from tracking when missing).
  * 7. Verify and fetch: fetch into the incoming ref when the remote moved; the remote sha
  *    must descend from the verified sha, else halt UPSTREAM_REWRITTEN; then move the
@@ -39,6 +41,9 @@ export const REBASE_REFUSED_AFTER = 3;
  *    git.hasStagedChanges() says the real index differs from HEAD (git would
  *    refuse the rebase), integrate is skipped, UNPUSHED reported and waiting
  *    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).
  *    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
@@ -115,6 +120,9 @@ async function runCycle(input, deps, carried, outcome) {
     // The commit's parent when this cycle committed: step 9 records the pull
     // from there, so the repair covers the commit and the pull in one move.
     let committedFrom = null;
+    // 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;
     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).
@@ -135,6 +143,14 @@ async function runCycle(input, deps, carried, outcome) {
         }
         if (committed.kind === 'waiting') {
             waiting = committed.reason;
+            // A rejected commit leaves every dirty path uncommittable; a rejecting
+            // hook must not block incoming changes (D4), so the pull holds them all.
+            if (committed.reason === 'COMMIT_HOOK_REJECTED') {
+                hold = { kind: 'all' };
+            }
+        }
+        if (committed.kind === 'committed' || committed.kind === 'nothing') {
+            hold = committed.hold;
         }
         if (committed.kind === 'committed') {
             committedFrom = committed.memory.lastMove?.from ?? null;
@@ -217,7 +233,13 @@ async function runCycle(input, deps, carried, outcome) {
             ontoSha: remoteSha,
             behind,
             knownConflict: input.knownConflict,
+            hold,
         });
+        if (integrated.kind === 'deferred') {
+            // The next cycle commits the save first; the runner logs WAITING once.
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome({ kind: 'waiting', reason: 'TREE_CHANGING' });
+        }
         if (integrated.kind === 'not-started') {
             const refusals = (carried.notStartedRebases ?? 0) + 1;
             carried.notStartedRebases = refusals;

package/dist/sync/syncCycleRunner.js

@@ -3,6 +3,7 @@ import { errorMessage } from '../core/errors/errorMessage.js';
 const WAITING_MESSAGES = {
     PARTIAL_SELECTION_STAGED: 'waiting: a partial selection is staged; nothing is committed or pulled until you commit or unstage it, and after partialStagingWaitMs enmetu commits everything',
     COMMIT_HOOK_REJECTED: 'waiting: a commit hook rejected the commit; enmetu tries again when the files change',
+    TREE_CHANGING: 'waiting: a file was saved while this cycle ran; the pull waits for a cycle that finds nothing new to commit, so no file you are editing is set aside',
 };
 /**
  * Service: the memory that spans cycles. Numbers cycles c1, c2, ...; passes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluado/enmetu",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Keeps one git working tree committed and in sync with its upstream.",
   "license": "MIT",
   "author": "fluado UG (haftungsbeschränkt)",