@fluado/enmetu 0.3.0 → 0.5.0

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

@@ -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';
 } | {
@@ -23,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/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/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/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,12 @@ 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), 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