@ouro.bot/cli 0.1.0-alpha.990 → 0.1.0-alpha.992

package/dist/heart/sync.js

@@ -33,18 +33,42 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STALE_INDEX_LOCK_MS = exports.SYNC_GIT_TIMEOUT_MS = exports.SYNC_GIT_MAX_BUFFER_BYTES = exports.SYNC_FILE_SIZE_LIMIT_BYTES = void 0;
+exports.NOT_A_REPO_ERROR = exports.STALE_INDEX_LOCK_MS = exports.SYNC_KILL_PROBE_MS = exports.SYNC_PAUSE_MAX_MS = exports.__testHooks = exports.PRE_TURN_LOCK_WAIT_MS = exports.OWNER_WINS_MESSAGE = exports.SYNC_SSH_COMMAND = exports.SYNC_SECRET_DIR = exports.SYNC_KILL_GRACE_MS = exports.SYNC_PUSH_TIMEOUT_MS = exports.SYNC_FETCH_TIMEOUT_MS = exports.SYNC_GIT_TIMEOUT_MS = exports.SYNC_GIT_MAX_BUFFER_BYTES = exports.SYNC_FILE_SIZE_LIMIT_BYTES = exports.FIRST_PUSH_HELD_NOTICE = void 0;
+exports.syncSecretDir = syncSecretDir;
 exports.pendingSyncPath = pendingSyncPath;
 exports.skippedSyncFilesPath = skippedSyncFilesPath;
+exports.syncPausedPath = syncPausedPath;
+exports.firstPushHeldPath = firstPushHeldPath;
+exports.agentNameFromRoot = agentNameFromRoot;
+exports.syncNetworkEnv = syncNetworkEnv;
+exports.syncGroupExists = syncGroupExists;
+exports.abortInFlightSync = abortInFlightSync;
 exports.clearPendingSync = clearPendingSync;
+exports.setSyncOwnerNotifier = setSyncOwnerNotifier;
+exports.tellOwner = tellOwner;
+exports.commitLocalChanges = commitLocalChanges;
+exports.integrateFetched = integrateFetched;
+exports.fetchRemote = fetchRemote;
+exports.listRemoteRefs = listRemoteRefs;
+exports.pushAsync = pushAsync;
+exports.syncPausedUntil = syncPausedUntil;
+exports.syncTrackingRef = syncTrackingRef;
+exports.holdSyncLock = holdSyncLock;
+exports.pushHeadToBranch = pushHeadToBranch;
+exports.probeSync = probeSync;
 exports.preTurnPull = preTurnPull;
-exports.postTurnPush = postTurnPush;
 exports.preTurnPullAsync = preTurnPullAsync;
+exports.postTurnPush = postTurnPush;
+exports.syncNow = syncNow;
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../nerves/runtime");
 const sync_health_1 = require("./sync-health");
+const sync_lock_1 = require("./sync-lock");
+/** What sync tells the owner, once, when it holds off a first push to an empty remote. */
+exports.FIRST_PUSH_HELD_NOTICE = "My bundle's GitHub repo is empty. Before I push to it for the first time, please look over what would go up and tell me yes.";
 /**
  * Sync never commits a file larger than this. GitHub rejects any push that
  * contains a file over 100 MiB and warns above 50 MiB; one such file in an
@@ -59,16 +83,351 @@ exports.SYNC_FILE_SIZE_LIMIT_BYTES = 50 * 1024 * 1024;
  */
 exports.SYNC_GIT_MAX_BUFFER_BYTES = 256 * 1024 * 1024;
 /**
- * Timeout for sync's add, commit, push and pull. `git add -A` took 17 s on a
- * bundle with 30,000 changed files, past the old 10 s limit.
+ * Timeout for sync's local git steps (status, add, commit, merge). `git add -A`
+ * took 17 s on a bundle with 30,000 changed files, past the old 10 s limit.
  */
 exports.SYNC_GIT_TIMEOUT_MS = 120_000;
+/** Network steps run as detached children, killed by process group at these limits. */
+exports.SYNC_FETCH_TIMEOUT_MS = 10_000;
+exports.SYNC_PUSH_TIMEOUT_MS = 60_000;
+/**
+ * Between the SIGTERM and the SIGKILL of a timed-out network step. In the
+ * container ssh runs as ouro-sync, which the agent's uid cannot signal; sudo
+ * can, and relays the SIGTERM to it.
+ */
+exports.SYNC_KILL_GRACE_MS = 2_000;
+/**
+ * The container's read-only mount for the sync deploy key. The key is owned by
+ * ouro-sync (10002) mode 0400, so the agent's uid cannot read it.
+ */
+exports.SYNC_SECRET_DIR = "/run/ouro-sync";
+/**
+ * git's ssh in the container: the root-owned wrapper, run as ouro-sync, is the
+ * only thing that reads the key. It accepts only git's call for one GitHub repo.
+ */
+exports.SYNC_SSH_COMMAND = "sudo -n -u ouro-sync /usr/local/libexec/ouro-sync-ssh";
+/** The deploy key directory: SYNC_SECRET_DIR, unless a test points it elsewhere. */
+function syncSecretDir() {
+    return exports.__testHooks.syncSecretDir ?? exports.SYNC_SECRET_DIR;
+}
+/** Message of the merge commit in which the owner's psyche edits win. */
+exports.OWNER_WINS_MESSAGE = "sync: owner's psyche edit wins";
+/**
+ * How long `preTurnPull` waits for the bundle lock before skipping. A turn
+ * skips rather than queues: the next turn integrates anyway.
+ */
+exports.PRE_TURN_LOCK_WAIT_MS = 5_000;
+/**
+ * Test seams.
+ * @internal Not part of the public API; production code must not set these.
+ */
+exports.__testHooks = {};
+/** A pause marker longer than this is garbage: a crashed pauser must not stop sync for good. */
+exports.SYNC_PAUSE_MAX_MS = 24 * 60 * 60 * 1000;
 function pendingSyncPath(agentRoot) {
     return path.join(agentRoot, "state", "pending-sync.json");
 }
 function skippedSyncFilesPath(agentRoot) {
     return path.join(agentRoot, "state", "sync-skipped-files.json");
 }
+function syncPausedPath(agentRoot) {
+    return path.join(agentRoot, "state", "sync-paused");
+}
+/** Present once the owner has been told a first push is held, so they are told only once. */
+function firstPushHeldPath(agentRoot) {
+    return path.join(agentRoot, "state", "sync-first-push-held.json");
+}
+function syncConflictStatePath(agentRoot) {
+    return path.join(agentRoot, "state", "sync-conflict.json");
+}
+function agentNameFromRoot(agentRoot) {
+    return path.basename(agentRoot).replace(/\.ouro$/, "");
+}
+function branchOf(config) {
+    return config.branch ?? "main";
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Flags on every call. The identity: a container or an empty HOME has no
+ * gitconfig. The rest: the owner's global gitconfig on the Mac must not
+ * stash, replay recorded resolutions, run hooks or demand signatures.
+ */
+function identityArgs(agentName) {
+    return [
+        "-c", `user.name=${agentName}`,
+        "-c", `user.email=${agentName}@ouro.local`,
+        "-c", "commit.gpgsign=false",
+        "-c", "merge.autoStash=false",
+        "-c", "rerere.enabled=false",
+        "-c", "core.hooksPath=/dev/null",
+        "-c", "merge.verifySignatures=false",
+        "-c", "core.fsmonitor=false",
+        ...(exports.__testHooks.extraGitConfig ?? []),
+    ];
+}
+/** git's messages are matched in English, so the locale is pinned. */
+function gitEnv(extra = {}) {
+    return { ...process.env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C", LANG: "C", ...extra };
+}
+/**
+ * The environment of a fetch or push. When the container has the key mount,
+ * git's ssh is the sync wrapper under sudo. `GIT_SSH_VARIANT=ssh` stops git
+ * probing an unknown "sudo" with `-G`. Without the mount (the Mac, or before
+ * the cutover) ssh is left to the host's own setup.
+ */
+function syncNetworkEnv() {
+    if (!fs.existsSync(syncSecretDir()))
+        return gitEnv();
+    return gitEnv({ GIT_SSH_COMMAND: exports.SYNC_SSH_COMMAND, GIT_SSH_VARIANT: "ssh" });
+}
+function runGit(agentRoot, agentName, args, env, input) {
+    const run = (0, child_process_1.spawnSync)("git", [...identityArgs(agentName), ...args], {
+        cwd: agentRoot,
+        env: gitEnv(env),
+        input,
+        stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        timeout: exports.SYNC_GIT_TIMEOUT_MS,
+        maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
+    });
+    /* v8 ignore next -- spawn failures (ENOENT, timeout, ENOBUFS) need a broken host @preserve */
+    if (run.error)
+        return { status: null, stdout: "", stderr: run.error.message };
+    return { status: run.status, stdout: run.stdout.toString(), stderr: run.stderr.toString() };
+}
+function gitFailure(args, run) {
+    return new Error(`git ${args[0]} failed: ${(run.stderr || run.stdout).trim()}`);
+}
+/** Run git and return stdout; throw with git's message on a non-zero exit. */
+function git(agentRoot, agentName, args, env, input) {
+    const run = runGit(agentRoot, agentName, args, env, input);
+    if (run.status !== 0)
+        throw gitFailure(args, run);
+    return run.stdout;
+}
+/**
+ * Run a git command over a list of paths, passed NUL-separated on stdin and
+ * matched literally. A list in argv dies with E2BIG past about 1 MB.
+ */
+function gitOnPaths(agentRoot, agentName, args, paths) {
+    return git(agentRoot, agentName, ["--literal-pathspecs", ...args, "--pathspec-from-file=-", "--pathspec-file-nul"], undefined, paths.join("\0"));
+}
+/**
+ * A network git call. It runs detached, in its own process group, so a timeout
+ * or an abort ends git and everything it started (ssh, a credential helper):
+ * a lone `kill` of git leaves ssh holding the pipes open. The group gets
+ * SIGTERM, which sudo relays to the ssh it runs, then SIGKILL after a grace.
+ */
+function runGitAsync(agentRoot, agentName, args, timeoutMs, signal) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)("git", [...identityArgs(agentName), ...args], {
+            cwd: agentRoot,
+            env: syncNetworkEnv(),
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let aborted = false;
+        let settled = false;
+        const pid = child.pid;
+        inFlightChildren.add(pid);
+        child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+        const killGroup = () => killSyncGroup(pid);
+        const onAbort = () => {
+            aborted = true;
+            killGroup();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, timeoutMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (status, extra = "") => {
+            /* v8 ignore next -- only a spawn error followed by close settles twice @preserve */
+            if (settled)
+                return;
+            settled = true;
+            inFlightChildren.delete(pid);
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            resolve({ status, stdout, stderr: extra + stderr, timedOut, aborted });
+        };
+        /* v8 ignore next -- spawning git itself failing needs a host without git @preserve */
+        child.on("error", (err) => finish(null, `${err.message}\n`));
+        child.on("close", (code) => finish(code));
+        if (signal?.aborted)
+            onAbort();
+    });
+}
+function signalSyncGroup(pid, name) {
+    try {
+        process.kill(-pid, name);
+    }
+    catch {
+        // The group is already gone.
+    }
+}
+/** How often a killed group is probed during the grace, so its timers stop once it is gone. */
+exports.SYNC_KILL_PROBE_MS = 50;
+/**
+ * Whether anything is left in process group `pid`. EPERM means a member this
+ * uid cannot signal (the ouro-sync ssh) is still there.
+ */
+function syncGroupExists(pid, kill = process.kill.bind(process)) {
+    try {
+        kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * SIGTERM to a network git child's process group, then SIGKILL after the
+ * grace. sudo relays only the SIGTERM to the ouro-sync ssh, which the agent's
+ * uid cannot signal. The timers are not tied to git closing: whatever in the
+ * group outlived the SIGTERM still gets the SIGKILL. They stop as soon as a
+ * probe finds the group gone, and the SIGKILL goes only to a group that still
+ * exists, so a reused group id is never signalled.
+ */
+function killSyncGroup(pid) {
+    signalSyncGroup(pid, "SIGTERM");
+    const probe = setInterval(() => {
+        if (syncGroupExists(pid))
+            return;
+        clearInterval(probe);
+        clearTimeout(kill);
+    }, exports.__testHooks.killProbeMs ?? exports.SYNC_KILL_PROBE_MS);
+    probe.unref();
+    const kill = setTimeout(() => {
+        clearInterval(probe);
+        if (syncGroupExists(pid))
+            signalSyncGroup(pid, "SIGKILL");
+    }, exports.__testHooks.killGraceMs ?? exports.SYNC_KILL_GRACE_MS);
+    kill.unref();
+}
+// ---------- termination ----------
+/** Process groups of the network git children now running. */
+const inFlightChildren = new Set();
+/** Sync locks this module holds, wrapped by `trackLock`. */
+const heldLocks = new Set();
+const TERMINATION_SIGNALS = ["SIGTERM", "SIGINT"];
+const terminationListeners = {
+    SIGTERM: () => onTerminationSignal("SIGTERM"),
+    SIGINT: () => onTerminationSignal("SIGINT"),
+};
+let guardInstalled = false;
+/**
+ * Kill every network git child's process group and release every sync lock
+ * this process holds. The daemon's SIGTERM handler calls it; so do the guard
+ * listeners below, for processes (the agent worker) with no handler of their own.
+ */
+function abortInFlightSync() {
+    const children = inFlightChildren.size;
+    const locks = heldLocks.size;
+    if (children === 0 && locks === 0)
+        return;
+    for (const pid of inFlightChildren)
+        killSyncGroup(pid);
+    inFlightChildren.clear();
+    for (const handle of [...heldLocks])
+        handle.release();
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_aborted",
+        message: "sync: killed in-flight git and released the bundle lock",
+        meta: { children, locks },
+    });
+}
+/**
+ * The guard is prepended, so it runs before every other listener for the
+ * signal, `once` wrappers included, and sees them all still registered. It
+ * kills sync's git children and releases the locks synchronously, then steps
+ * aside: another component's own shutdown runs to completion. Only when no
+ * other listener exists does it re-raise, restoring the default exit.
+ */
+function onTerminationSignal(signal) {
+    const others = process.rawListeners(signal).filter((listener) => listener !== terminationListeners[signal]);
+    abortInFlightSync();
+    removeTerminationGuard();
+    /* v8 ignore next -- re-raising ends the process; the SIGTERM child-process test covers it @preserve */
+    if (others.length === 0)
+        process.kill(process.pid, signal);
+}
+function installTerminationGuard() {
+    if (guardInstalled)
+        return;
+    guardInstalled = true;
+    for (const signal of TERMINATION_SIGNALS)
+        process.prependListener(signal, terminationListeners[signal]);
+    process.on("exit", abortInFlightSync);
+}
+function removeTerminationGuard() {
+    if (!guardInstalled)
+        return;
+    guardInstalled = false;
+    for (const signal of TERMINATION_SIGNALS)
+        process.removeListener(signal, terminationListeners[signal]);
+    process.removeListener("exit", abortInFlightSync);
+}
+/** While any lock is held, a signal or an exit kills sync's children and releases the lock. */
+function trackLock(handle) {
+    let released = false;
+    const tracked = {
+        release() {
+            if (released)
+                return;
+            released = true;
+            heldLocks.delete(tracked);
+            try {
+                handle.release();
+            }
+            finally {
+                if (heldLocks.size === 0)
+                    removeTerminationGuard();
+            }
+        },
+    };
+    heldLocks.add(tracked);
+    installTerminationGuard();
+    return tracked;
+}
+function describeAsyncFailure(step, run, timeoutMs) {
+    if (run.timedOut)
+        return `git ${step} timed out after ${timeoutMs} ms`;
+    if (run.aborted)
+        return `git ${step} aborted`;
+    return `git ${step} failed: ${run.stderr.trim()}`;
+}
+function hasRemote(agentRoot, agentName, config) {
+    return git(agentRoot, agentName, ["remote"]).split("\n").map((line) => line.trim()).includes(config.remote);
+}
+function remoteTrackingRef(config) {
+    return `refs/remotes/${config.remote}/${branchOf(config)}`;
+}
+function refExists(agentRoot, agentName, ref) {
+    return runGit(agentRoot, agentName, ["rev-parse", "--verify", "--quiet", ref]).status === 0;
+}
+/** Commits on HEAD that the last fetched remote branch lacks. An unborn HEAD has none. */
+function commitsAhead(agentRoot, agentName, config) {
+    if (!refExists(agentRoot, agentName, "HEAD"))
+        return 0;
+    const ref = remoteTrackingRef(config);
+    const range = refExists(agentRoot, agentName, ref) ? `${ref}..HEAD` : "HEAD";
+    return Number.parseInt(git(agentRoot, agentName, ["rev-list", "--count", range]).trim(), 10);
+}
+function unmergedPaths(agentRoot, agentName) {
+    return git(agentRoot, agentName, ["diff", "--name-only", "--diff-filter=U", "-z"]).split("\0").filter((p) => p.length > 0);
+}
+function gitDirEntry(agentRoot, name) {
+    return path.join(agentRoot, ".git", name);
+}
+// ---------- persistent records ----------
 function readPreviousFailure(agentRoot) {
     try {
         return (0, sync_health_1.parseBundleSyncFailure)(JSON.parse(fs.readFileSync(pendingSyncPath(agentRoot), "utf-8")));
@@ -77,7 +436,17 @@ function readPreviousFailure(agentRoot) {
         return null;
     }
 }
-function writePendingSync(agentRoot, error, classification, conflictFiles) {
+/** The repair ref the pending record names, if any. */
+function pendingRepairRef(agentRoot) {
+    try {
+        const record = JSON.parse(fs.readFileSync(pendingSyncPath(agentRoot), "utf-8"));
+        return typeof record?.repairRef === "string" ? record.repairRef : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writePendingSync(agentRoot, error, classification, conflictFiles, repairRef) {
     const previous = readPreviousFailure(agentRoot);
     const failedAt = new Date().toISOString();
     const previousFirst = previous && previous.firstFailedAt !== "unknown" ? previous.firstFailedAt : null;
@@ -89,12 +458,16 @@ function writePendingSync(agentRoot, error, classification, conflictFiles) {
         conflictFiles,
         firstFailedAt: previousFirst ?? failedAt,
         consecutiveFailures: (previous?.consecutiveFailures ?? 0) + 1,
+        ...(repairRef === undefined ? {} : { repairRef }),
     };
     fs.writeFileSync(pendingSyncPath(agentRoot), JSON.stringify(record, null, 2), "utf-8");
 }
-function recordPendingSync(agentRoot, error, classification, conflictFiles) {
+function recordPendingSync(agentRoot, error, classification, conflictFiles, repairRef) {
+    // An incomplete restore outranks later failures: it names the ref holding the agent's work.
+    if (classification !== "repair_restore_incomplete" && readPreviousFailure(agentRoot)?.classification === "repair_restore_incomplete")
+        return;
     try {
-        writePendingSync(agentRoot, error, classification, conflictFiles);
+        writePendingSync(agentRoot, error, classification, conflictFiles, repairRef);
     }
     catch {
         // Best effort: the caller's nerves event still records the failure.
@@ -114,6 +487,16 @@ function clearPendingSync(agentRoot) {
         // Best effort: a stale record is reported again and cleared next time.
     }
 }
+/**
+ * Clear the pending record after a sync step succeeded, unless it reports an
+ * incomplete restore: that one stays until a person clears it
+ * (`clearPendingSync`), since the agent's work is only in the named ref.
+ */
+function settlePendingSync(agentRoot) {
+    if (readPreviousFailure(agentRoot)?.classification === "repair_restore_incomplete")
+        return;
+    clearPendingSync(agentRoot);
+}
 function writeSkippedSyncFiles(agentRoot, files) {
     try {
         if (files.length === 0) {
@@ -132,6 +515,155 @@ function writeSkippedSyncFiles(agentRoot, files) {
         // Best effort: the nerves event emitted by the caller names the files.
     }
 }
+function readConflictState(agentRoot) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(syncConflictStatePath(agentRoot), "utf-8"));
+        return typeof parsed.hash === "string" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeConflictState(agentRoot, state) {
+    try {
+        fs.mkdirSync(path.join(agentRoot, "state"), { recursive: true });
+        fs.writeFileSync(syncConflictStatePath(agentRoot), JSON.stringify(state, null, 2), "utf-8");
+    }
+    catch {
+        // Best effort: without the record the owner may be told twice.
+    }
+}
+function clearConflictState(agentRoot) {
+    try {
+        fs.rmSync(syncConflictStatePath(agentRoot), { force: true });
+    }
+    catch {
+        // Best effort: a stale record only suppresses a repeat notice.
+    }
+}
+// ---------- owner notices ----------
+let ownerNotifier = null;
+/**
+ * Replace how sync tells the owner. Null restores the default: Telegram when
+ * the agent has it; otherwise the notice goes to the agent's private-runtime
+ * pending queue, and the agent tells the owner through whatever sense it has.
+ */
+function setSyncOwnerNotifier(notifier) {
+    ownerNotifier = notifier;
+}
+async function defaultOwnerNotifier(agentRoot, agentName, notice) {
+    try {
+        const { sendTelegramOwnerNotice } = await Promise.resolve().then(() => __importStar(require("../senses/telegram")));
+        await sendTelegramOwnerNotice(agentName, { ...notice, signal: AbortSignal.timeout(30_000) });
+        return;
+    }
+    catch (err) {
+        // Not every agent has Telegram: queue it once, for the agent to relay.
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.sync_owner_notice_telegram_skipped",
+            message: "sync: Telegram did not send the owner notice; queued it instead",
+            meta: { agentRoot, noticeId: notice.noticeId, error: errorText(err) },
+        });
+    }
+    const { getPrivateRuntimePendingDir, queuePendingMessageOnce } = await Promise.resolve().then(() => __importStar(require("../mind/pending")));
+    queuePendingMessageOnce(getPrivateRuntimePendingDir(agentName, agentRoot), {
+        from: agentName,
+        friendId: "self",
+        channel: "inner",
+        key: "dialog",
+        content: `${notice.text}\n\ni should tell my owner.`,
+        timestamp: Date.now(),
+        packetId: notice.noticeId,
+    });
+}
+/** Fire and forget: a turn never waits on a notice. */
+function tellOwner(agentRoot, agentName, notice) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_owner_notice",
+        message: "sync: telling the owner",
+        meta: { agentRoot, noticeId: notice.noticeId },
+    });
+    const send = ownerNotifier ?? ((name, body) => defaultOwnerNotifier(agentRoot, name, body));
+    void Promise.resolve()
+        .then(() => send(agentName, notice))
+        .catch((err) => {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_owner_notice_error",
+            message: "sync: could not tell the owner",
+            meta: { agentRoot, noticeId: notice.noticeId, error: errorText(err) },
+        });
+    });
+}
+/** Read the pause marker without changing anything. */
+function readPauseMarker(agentRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(syncPausedPath(agentRoot), "utf-8");
+    }
+    catch {
+        return { kind: "none" };
+    }
+    let marker;
+    try {
+        marker = JSON.parse(raw);
+    }
+    catch {
+        marker = null;
+    }
+    const expiresAt = marker?.expiresAt;
+    const expiresMs = typeof expiresAt === "string" ? Date.parse(expiresAt) : Number.NaN;
+    const startedMs = typeof marker?.startedAt === "string" ? Date.parse(marker.startedAt) : Number.NaN;
+    const now = Date.now();
+    const longestEnd = (Number.isFinite(startedMs) ? startedMs : now) + exports.SYNC_PAUSE_MAX_MS;
+    if (Number.isFinite(expiresMs) && expiresMs > now && expiresMs <= longestEnd)
+        return { kind: "active", expiresAt: expiresAt };
+    return { kind: "garbage", expiresAt };
+}
+function activePause(agentRoot) {
+    const markerPath = syncPausedPath(agentRoot);
+    const state = readPauseMarker(agentRoot);
+    if (state.kind === "none")
+        return null;
+    if (state.kind === "active")
+        return state.expiresAt;
+    const expiresAt = state.expiresAt;
+    try {
+        fs.rmSync(markerPath, { force: true });
+    }
+    catch (err) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_pause_clear_failed",
+            message: "sync: could not remove an expired or unreadable pause marker",
+            meta: { agentRoot, error: errorText(err) },
+        });
+        return null;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_pause_expired",
+        message: "sync: removed an expired or unreadable pause marker",
+        meta: { agentRoot, expiresAt: typeof expiresAt === "string" ? expiresAt : null },
+    });
+    return null;
+}
+function pausedResult(agentRoot, step) {
+    const until = activePause(agentRoot);
+    if (until === null)
+        return null;
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_paused",
+        message: `${step} skipped: sync is paused`,
+        meta: { agentRoot, expiresAt: until },
+    });
+    return { ok: true, paused: true, pausedUntil: until };
+}
 /** Parse `git diff --cached --name-status -z` output. */
 function parseStagedChanges(output) {
     const tokens = output.split("\0").filter((entry) => entry.length > 0);
@@ -156,13 +688,8 @@ function parseStagedChanges(output) {
  * the deletion of the old path is unstaged too; otherwise the remote would
  * lose the old path while never receiving the new one.
  */
-function unstageOversizedFiles(agentRoot) {
-    const changes = parseStagedChanges((0, child_process_1.execFileSync)("git", ["diff", "--cached", "--name-status", "-M", "-z"], {
-        cwd: agentRoot,
-        stdio: "pipe",
-        timeout: exports.SYNC_GIT_TIMEOUT_MS,
-        maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-    }).toString());
+function unstageOversizedFiles(agentRoot, agentName) {
+    const changes = parseStagedChanges(git(agentRoot, agentName, ["diff", "--cached", "--name-status", "-M", "-z"]));
     const oversized = [];
     const unstage = [];
     for (const change of changes) {
@@ -173,6 +700,7 @@ function unstageOversizedFiles(agentRoot) {
             bytes = fs.lstatSync(path.join(agentRoot, change.path)).size;
         }
         catch {
+            /* v8 ignore next -- the file was removed between `git add` and this stat @preserve */
             continue;
         }
         if (bytes <= exports.SYNC_FILE_SIZE_LIMIT_BYTES)
@@ -184,75 +712,28 @@ function unstageOversizedFiles(agentRoot) {
     }
     if (oversized.length === 0)
         return oversized;
-    (0, child_process_1.execFileSync)("git", ["--literal-pathspecs", "reset", "-q", "--", ...unstage], {
-        cwd: agentRoot,
-        stdio: "pipe",
-        timeout: exports.SYNC_GIT_TIMEOUT_MS,
-    });
+    // An unborn HEAD has nothing to reset to; `rm --cached` drops the new entry instead.
+    if (refExists(agentRoot, agentName, "HEAD"))
+        gitOnPaths(agentRoot, agentName, ["reset", "-q"], unstage);
+    else
+        gitOnPaths(agentRoot, agentName, ["rm", "-q", "--cached"], unstage);
     (0, runtime_1.emitNervesEvent)({
         level: "warn",
         component: "heart",
         event: "heart.sync_oversized_files_skipped",
-        message: "post-turn push: left files over the sync size limit uncommitted",
+        message: "sync: left files over the sync size limit uncommitted",
         meta: { agentRoot, limitBytes: exports.SYNC_FILE_SIZE_LIMIT_BYTES, files: oversized },
     });
     return oversized;
 }
-function hasStagedChanges(agentRoot) {
-    try {
-        (0, child_process_1.execFileSync)("git", ["diff", "--cached", "--quiet"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: exports.SYNC_GIT_TIMEOUT_MS,
-        });
-        return false;
-    }
-    catch {
-        return true;
-    }
-}
-function collectRebaseConflictFiles(agentRoot) {
-    try {
-        const output = (0, child_process_1.execFileSync)("git", ["status", "--porcelain=v1"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: 5000,
-            maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-        }).toString();
-        const files = [];
-        for (const line of output.split("\n")) {
-            // Unmerged paths in porcelain v1 are prefixed with UU/AA/DD/AU/UA/DU/UD
-            if (/^(UU|AA|DD|AU|UA|DU|UD) /.test(line)) {
-                files.push(line.slice(3).trim());
-            }
-        }
-        return files;
-    }
-    catch {
-        /* v8 ignore next -- git status --porcelain failure inside a repo would require a corrupt repo @preserve */
-        return [];
-    }
-}
-/**
- * Check whether the bundle is initialized as a git repo.
- * Used by both pre-turn pull and post-turn push to surface a clear,
- * actionable error when sync is enabled but the user never ran `git init`
- * inside their bundle. This error is propagated all the way into the
- * agent's start-of-turn packet as a Sync warning, so the agent can
- * either ask the user or run `git init` itself.
- */
-function ensureGitRepo(agentRoot) {
-    if (fs.existsSync(path.join(agentRoot, ".git"))) {
-        return { ok: true };
-    }
-    const error = `bundle is not a git repo; run \`git init\` inside ${agentRoot} to enable sync (or disable sync in agent.json)`;
-    return { ok: false, error };
+function hasStagedChanges(agentRoot, agentName) {
+    return runGit(agentRoot, agentName, ["diff", "--cached", "--quiet"]).status !== 0;
 }
 /**
- * Git holds `.git/index.lock` for milliseconds to seconds, and every git call
- * in this module has a timeout of 30s or less. A lock older than this was left
- * behind by a git process that died mid-write; while it exists every `git add`
- * fails, which silently stopped one bundle's sync for three months.
+ * Git holds `.git/index.lock` for milliseconds to seconds, and every local git
+ * call in this module has a timeout well under this. A lock older than this was
+ * left behind by a git process that died mid-write; while it exists every
+ * `git add` fails, which silently stopped one bundle's sync for three months.
  */
 exports.STALE_INDEX_LOCK_MS = 10 * 60 * 1000;
 // Only an empty lock is removed: git writes the new index into the lock right
@@ -260,7 +741,7 @@ exports.STALE_INDEX_LOCK_MS = 10 * 60 * 1000;
 // full, unchanging lock that can be older than the threshold. When `.git` is a
 // gitdir file (worktree), statSync fails and the lock is left alone.
 function clearStaleIndexLock(agentRoot) {
-    const lockPath = path.join(agentRoot, ".git", "index.lock");
+    const lockPath = gitDirEntry(agentRoot, "index.lock");
     let ageMs;
     try {
         const stat = fs.statSync(lockPath);
@@ -281,8 +762,8 @@ function clearStaleIndexLock(agentRoot) {
             level: "warn",
             component: "heart",
             event: "heart.sync_stale_lock_clear_failed",
-            message: "post-turn push: could not remove stale git index.lock",
-            meta: { agentRoot, lockPath, error: err instanceof Error ? err.message : /* v8 ignore next -- defensive non-Error catch @preserve */ String(err) },
+            message: "sync: could not remove stale git index.lock",
+            meta: { agentRoot, lockPath, error: errorText(err) },
         });
         return;
     }
@@ -290,358 +771,635 @@ function clearStaleIndexLock(agentRoot) {
         level: "warn",
         component: "heart",
         event: "heart.sync_stale_lock_cleared",
-        message: "post-turn push: removed stale git index.lock",
+        message: "sync: removed stale git index.lock",
         meta: { agentRoot, lockPath, ageMs },
     });
 }
 /**
- * Pre-turn pull: sync the agent bundle from remote before assembling the start-of-turn packet.
- *
- * If the bundle has no git remote configured, the pull is skipped and the function
- * returns ok — matching the no-remote behavior of postTurnPush. This supports the
- * "local-only sync" mode where the bundle accumulates a commit log without ever
- * pushing or pulling from a remote.
+ * Commit every change in the bundle except files over the size limit, as the
+ * agent. Synchronous, so no turn's file writes interleave with it. Throws with
+ * git's message when git fails; never commits unmerged paths (conflict markers).
  */
-function preTurnPull(agentRoot, config) {
+function commitLocalChanges(agentRoot, agentName, message) {
+    const status = git(agentRoot, agentName, ["status", "--porcelain"]).trim();
+    if (status.length === 0) {
+        // Nothing to commit, so nothing is skipped for size any more.
+        writeSkippedSyncFiles(agentRoot, []);
+        return { committed: false, skipped: [] };
+    }
+    const unmerged = unmergedPaths(agentRoot, agentName);
+    if (unmerged.length > 0)
+        throw new Error(`unmerged paths in the index: ${unmerged.join(", ")}`);
+    clearStaleIndexLock(agentRoot);
+    git(agentRoot, agentName, ["add", "-A"]);
+    const skipped = unstageOversizedFiles(agentRoot, agentName);
+    writeSkippedSyncFiles(agentRoot, skipped);
+    if (!hasStagedChanges(agentRoot, agentName))
+        return { committed: false, skipped };
+    // -q: without it git prints a create/delete line per file, which overran
+    // the output buffer on a 30,000-file commit after the commit had landed.
+    git(agentRoot, agentName, ["commit", "-q", "-m", message]);
+    return { committed: true, skipped };
+}
+// ---------- integrate ----------
+/**
+ * Check whether the bundle is initialized as a git repo. The error reaches the
+ * agent's start-of-turn packet as a sync warning.
+ */
+exports.NOT_A_REPO_ERROR = "my bundle is not a git repository";
+function ensureGitRepo(agentRoot, step) {
+    if (fs.existsSync(path.join(agentRoot, ".git")))
+        return { ok: true };
     (0, runtime_1.emitNervesEvent)({
+        level: "warn",
         component: "heart",
-        event: "heart.sync_pull_start",
-        message: "pre-turn pull starting",
-        meta: { agentRoot, remote: config.remote },
+        event: "heart.sync_not_a_repo",
+        message: `${step} failed: bundle is not a git repo`,
+        meta: { agentRoot },
     });
-    // Check that the bundle is actually a git repo before touching git at all.
-    // Surfaces a clear, actionable error via syncFailure → start-of-turn packet
-    // so the agent can propose running `git init` (or just do it).
-    const repoCheck = ensureGitRepo(agentRoot);
-    if (!repoCheck.ok) {
-        (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            component: "heart",
-            event: "heart.sync_not_a_repo",
-            message: "pre-turn pull failed: bundle is not a git repo",
-            meta: { agentRoot },
-        });
-        return repoCheck;
+    return { ok: false, error: exports.NOT_A_REPO_ERROR };
+}
+const REPAIR_REF_PREFIX = "refs/ouro-sync/repair/";
+/** Repair refs kept regardless of age. */
+const REPAIR_REFS_KEPT = 10;
+/** Repair refs younger than this are kept regardless of count. */
+const REPAIR_REF_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/** Repair refs, newest first (names are ISO timestamps, so they sort by time). */
+function listRepairRefs(agentRoot, agentName) {
+    return git(agentRoot, agentName, ["for-each-ref", "--sort=-refname", "--format=%(refname) %(tree) %(committerdate:unix)", REPAIR_REF_PREFIX])
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const [name, tree, seconds] = line.split(" ");
+        return { name, tree, committedMs: Number(seconds) * 1000 };
+    });
+}
+/** Drop repair refs past the newest ten that are 30 days old, except one the pending record names. */
+function pruneRepairRefs(agentRoot, agentName, refs) {
+    const protectedRef = pendingRepairRef(agentRoot);
+    const now = Date.now();
+    const doomed = refs.filter((ref, i) => i >= REPAIR_REFS_KEPT && now - ref.committedMs >= REPAIR_REF_MAX_AGE_MS && ref.name !== protectedRef);
+    if (doomed.length === 0)
+        return;
+    git(agentRoot, agentName, ["update-ref", "--stdin"], undefined, doomed.map((ref) => `delete ${ref.name}\n`).join(""));
+}
+/**
+ * Commit the whole working tree, as it is now, to `refs/ouro-sync/repair/<ts>`
+ * without touching the real index. Its parent is the current HEAD, which for a
+ * stranded rebase is the detached HEAD, so commits made there stay reachable.
+ * When the newest repair ref already holds this tree, that ref is reused.
+ */
+function snapshotWorkingTree(agentRoot, agentName) {
+    const indexFile = gitDirEntry(agentRoot, `ouro-sync-repair-${process.pid}.index`);
+    const env = { GIT_INDEX_FILE: indexFile };
+    let tree;
+    try {
+        // Seed from HEAD so tracked files that match an ignore rule are kept.
+        git(agentRoot, agentName, ["read-tree", "HEAD"], env);
+        git(agentRoot, agentName, ["add", "-A"], env);
+        tree = git(agentRoot, agentName, ["write-tree"], env).trim();
     }
-    // Check if any remote is configured. If not, skip the pull (local-only mode).
+    finally {
+        fs.rmSync(indexFile, { force: true });
+    }
+    const existing = listRepairRefs(agentRoot, agentName);
+    if (existing[0]?.tree === tree)
+        return existing[0].name;
+    const commit = git(agentRoot, agentName, ["commit-tree", tree, "-p", "HEAD", "-m", "sync: repair snapshot"]).trim();
+    // A refname may not contain ":".
+    const ref = `${REPAIR_REF_PREFIX}${new Date().toISOString().replace(/:/g, "-")}`;
+    git(agentRoot, agentName, ["update-ref", ref, commit]);
+    pruneRepairRefs(agentRoot, agentName, [{ name: ref, tree, committedMs: Date.now() }, ...existing]);
+    return ref;
+}
+/** `merge --abort`, else `reset --merge`, else `reset --hard HEAD` (the snapshot restores the rest). */
+function abortMergeThoroughly(agentRoot, agentName) {
+    if (runGit(agentRoot, agentName, exports.__testHooks.mergeAbortArgs ?? ["merge", "--abort"]).status === 0)
+        return "merge --abort";
+    if (runGit(agentRoot, agentName, ["reset", "-q", "--merge"]).status === 0)
+        return "reset --merge";
+    git(agentRoot, agentName, ["reset", "-q", "--hard", "HEAD"]);
+    return "reset --hard";
+}
+/** Paths whose content in the snapshot differs from HEAD. */
+function pathsChangedInSnapshot(agentRoot, agentName, ref) {
+    return git(agentRoot, agentName, ["diff", "--name-only", "--no-renames", "-z", "HEAD", ref])
+        .split("\0")
+        .filter((p) => p.length > 0);
+}
+const refTimestamp = (ref) => ref.slice(REPAIR_REF_PREFIX.length);
+/**
+ * Abort a rebase or merge left in progress, keeping the work done since. The
+ * working tree is snapshotted first; after the abort, every path the operation
+ * did not conflict on is restored from it. Conflicted paths keep HEAD's
+ * version; edits to them stay in the snapshot ref, which the owner is told about.
+ *
+ * Returns null when there was nothing to repair or the repair completed, else
+ * the failure to report. A failed snapshot touches nothing, so the stranded
+ * state stays exactly as found for a later attempt.
+ */
+function repairInterrupted(agentRoot, agentName) {
+    const rebase = fs.existsSync(gitDirEntry(agentRoot, "rebase-merge")) || fs.existsSync(gitDirEntry(agentRoot, "rebase-apply"));
+    const merge = fs.existsSync(gitDirEntry(agentRoot, "MERGE_HEAD"));
+    if (!rebase && !merge)
+        return null;
+    const operation = rebase ? "rebase" : "merge";
+    const conflicted = unmergedPaths(agentRoot, agentName);
+    let ref;
     try {
-        const remoteOutput = (0, child_process_1.execFileSync)("git", ["remote"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: 5000,
-        }).toString().trim();
-        if (remoteOutput.length === 0) {
-            (0, runtime_1.emitNervesEvent)({
-                component: "heart",
-                event: "heart.sync_pull_end",
-                message: "pre-turn pull skipped: no remote configured",
-                meta: { agentRoot },
-            });
-            return { ok: true };
-        }
+        ref = snapshotWorkingTree(agentRoot, agentName);
     }
     catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        (0, runtime_1.emitNervesEvent)({
-            component: "heart",
-            event: "heart.sync_pull_error",
-            message: "pre-turn pull failed: git remote check failed",
-            meta: { agentRoot, error },
-        });
-        return { ok: false, error };
+        return reportSnapshotFailure(agentRoot, agentName, operation, errorText(err));
     }
+    let abortedWith = "rebase --abort";
+    if (rebase)
+        git(agentRoot, agentName, ["rebase", "--abort"]);
+    else
+        abortedWith = abortMergeThoroughly(agentRoot, agentName);
+    const changed = pathsChangedInSnapshot(agentRoot, agentName, ref);
+    const skip = new Set(conflicted);
+    const restore = changed.filter((p) => !skip.has(p));
+    const kept = changed.filter((p) => skip.has(p));
     try {
-        (0, child_process_1.execFileSync)("git", ["pull", config.remote], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: 30000,
-        });
-        (0, runtime_1.emitNervesEvent)({
-            component: "heart",
-            event: "heart.sync_pull_end",
-            message: "pre-turn pull complete",
-            meta: { agentRoot },
-        });
-        return { ok: true };
+        if (restore.length > 0)
+            gitOnPaths(agentRoot, agentName, ["restore", `--source=${ref}`, "--worktree"], restore);
     }
     catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        (0, runtime_1.emitNervesEvent)({
-            component: "heart",
-            event: "heart.sync_pull_error",
-            message: "pre-turn pull failed",
-            meta: { agentRoot, error },
+        return reportRestoreIncomplete(agentRoot, agentName, operation, ref, errorText(err));
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_repaired",
+        message: "sync: aborted a rebase or merge left in progress",
+        meta: { agentRoot, rebase, merge, ref, conflicted, kept, abortedWith },
+    });
+    if (kept.length === 0)
+        return null;
+    recordPendingSync(agentRoot, `an interrupted ${operation} was aborted; edits to ${kept.join(", ")} are kept in ${ref}`, "unknown", kept, ref);
+    tellOwner(agentRoot, agentName, {
+        noticeId: `sync-repair:${agentName}:${refTimestamp(ref)}`,
+        text: `Sync found an interrupted ${operation} in ${agentName}'s bundle and aborted it. Edits to ${kept.join(", ")} made since are kept in ${ref}.`,
+    });
+    return null;
+}
+function reportSnapshotFailure(agentRoot, agentName, operation, gitError) {
+    const error = `an interrupted ${operation} was left in place: the working tree could not be saved first (${gitError})`;
+    const previous = readPreviousFailure(agentRoot);
+    const repeat = previous?.classification === "repair_snapshot_failed" && previous.error === error;
+    recordPendingSync(agentRoot, error, "repair_snapshot_failed", []);
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_repair_snapshot_failed",
+        message: "sync: could not snapshot before repair; nothing was changed",
+        meta: { agentRoot, operation, error: gitError },
+    });
+    if (!repeat) {
+        tellOwner(agentRoot, agentName, {
+            noticeId: `sync-repair-snapshot:${agentName}:${(0, crypto_1.createHash)("sha256").update(error).digest("hex").slice(0, 16)}`,
+            text: `Sync found an interrupted ${operation} in ${agentName}'s bundle but could not save the working tree first, so it left everything as it is and stopped syncing. git said: ${gitError}`,
         });
-        return { ok: false, error };
     }
+    return { ok: false, error };
+}
+function reportRestoreIncomplete(agentRoot, agentName, operation, ref, gitError) {
+    const error = `an interrupted ${operation} was aborted but not every file was put back; the full working tree is in ${ref} (${gitError})`;
+    recordPendingSync(agentRoot, error, "repair_restore_incomplete", [], ref);
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_repair_restore_incomplete",
+        message: "sync: repair could not restore every file from its snapshot",
+        meta: { agentRoot, operation, ref, error: gitError },
+    });
+    tellOwner(agentRoot, agentName, {
+        noticeId: `sync-repair-restore:${agentName}:${refTimestamp(ref)}`,
+        text: `Sync aborted an interrupted ${operation} in ${agentName}'s bundle but could not put every file back. The working tree as it was is in ${ref}; git said: ${gitError}`,
+    });
+    return { ok: false, error };
+}
+function abortMergeIfAny(agentRoot, agentName) {
+    if (fs.existsSync(gitDirEntry(agentRoot, "MERGE_HEAD")))
+        runGit(agentRoot, agentName, ["merge", "--abort"]);
 }
 /**
- * Post-turn push: discover dirty files via `git status`, commit, and push.
- * Uses git-status-based discovery instead of explicit path tracking, ensuring
- * all file writers are captured regardless of whether they call a tracking API.
+ * Redo a merge whose conflicts are all in `psyche/` so the owner's conflicting
+ * hunks win and the agent's other hunks stay. Delete/modify conflicts take the
+ * owner's side too: removed where the owner deleted, the owner's file where the
+ * owner modified.
  */
-function postTurnPush(agentRoot, config) {
+function mergeOwnerWins(agentRoot, agentName, ref, paths) {
+    git(agentRoot, agentName, ["merge", "--abort"]);
+    const merge = runGit(agentRoot, agentName, ["merge", "--no-edit", "--ff", "-X", "theirs", "-m", exports.OWNER_WINS_MESSAGE, ref]);
+    if (merge.status !== 0) {
+        const remaining = unmergedPaths(agentRoot, agentName);
+        if (remaining.length === 0)
+            throw gitFailure(["merge"], merge);
+        for (const file of remaining) {
+            const stages = git(agentRoot, agentName, ["--literal-pathspecs", "ls-files", "-u", "--", file]);
+            const theirsHasIt = stages.split("\n").some((line) => /^\d+ [0-9a-f]+ 3\t/.test(line));
+            if (theirsHasIt) {
+                git(agentRoot, agentName, ["--literal-pathspecs", "checkout", "--theirs", "--", file]);
+                git(agentRoot, agentName, ["--literal-pathspecs", "add", "--", file]);
+            }
+            else {
+                git(agentRoot, agentName, ["--literal-pathspecs", "rm", "-q", "--", file]);
+            }
+        }
+        git(agentRoot, agentName, ["commit", "-q", "-m", exports.OWNER_WINS_MESSAGE]);
+    }
     (0, runtime_1.emitNervesEvent)({
         component: "heart",
-        event: "heart.sync_push_start",
-        message: "post-turn push starting",
-        meta: { agentRoot, remote: config.remote },
+        event: "heart.sync_owner_wins",
+        message: "sync: merged with the owner's psyche edits winning conflicts",
+        meta: { agentRoot, paths },
     });
-    // Same git-repo check as preTurnPull. This is the more common failure path
-    // since postTurnPush runs after every turn while preTurnPull only runs on
-    // user-initiated turns. Prior to this guard, an un-init'd bundle would fail
-    // the git-status invocation below with a generic "not a git repository"
-    // error; now we catch it explicitly with an actionable message.
-    const repoCheck = ensureGitRepo(agentRoot);
-    if (!repoCheck.ok) {
-        (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            component: "heart",
-            event: "heart.sync_not_a_repo",
-            message: "post-turn push failed: bundle is not a git repo",
-            meta: { agentRoot },
-        });
-        return repoCheck;
-    }
-    let statusOutput;
+}
+function conflictHash(paths) {
+    return (0, crypto_1.createHash)("sha256").update(paths.join("\0")).digest("hex").slice(0, 16);
+}
+function handleNonPsycheConflict(agentRoot, config, agentName, paths) {
+    git(agentRoot, agentName, ["merge", "--abort"]);
+    const sorted = [...paths].sort();
+    const hash = conflictHash(sorted);
+    const error = `merge with ${config.remote}/${branchOf(config)} conflicts in ${sorted.join(", ")}; the merge was aborted and local commits are kept`;
+    recordPendingSync(agentRoot, error, "pull_rebase_conflict", sorted);
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_conflict",
+        message: "sync: merge conflict outside psyche/, merge aborted",
+        meta: { agentRoot, conflictFiles: sorted, hash },
+    });
+    const previous = readConflictState(agentRoot);
+    if (previous?.hash === hash)
+        return { result: { ok: false, error }, conflictBranch: previous };
+    writeConflictState(agentRoot, { hash, paths: sorted });
+    tellOwner(agentRoot, agentName, {
+        noticeId: `sync-conflict:${agentName}:${hash}`,
+        text: `Bundle sync for ${agentName} stopped: ${sorted.join(", ")} changed on both sides. My changes stay committed locally until the conflict is merged.`,
+    });
+    return { result: { ok: false, error } };
+}
+/** Record a successful integrate: a resolved conflict is over, and a synced bundle has nothing pending. */
+function settleIntegrated(agentRoot, config, agentName) {
+    clearConflictState(agentRoot);
+    const pending = readPreviousFailure(agentRoot);
+    if (!pending)
+        return;
+    if (pending.classification === "pull_rebase_conflict" || commitsAhead(agentRoot, agentName, config) === 0)
+        settlePendingSync(agentRoot);
+}
+function integrateCore(agentRoot, config, agentName, commitMessage = "sync: pre-turn update") {
+    // Outside the try: its catch aborts a merge, which must never run before a snapshot.
+    const repairFailure = repairInterrupted(agentRoot, agentName);
+    if (repairFailure)
+        return { result: repairFailure };
     try {
-        statusOutput = (0, child_process_1.execFileSync)("git", ["status", "--porcelain"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: exports.SYNC_GIT_TIMEOUT_MS,
-            maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-        }).toString().trim();
+        commitLocalChanges(agentRoot, agentName, commitMessage);
+        const ref = remoteTrackingRef(config);
+        if (!refExists(agentRoot, agentName, ref)) {
+            settleIntegrated(agentRoot, config, agentName);
+            return { result: { ok: true } };
+        }
+        const shortRef = `${config.remote}/${branchOf(config)}`;
+        const merge = runGit(agentRoot, agentName, ["merge", "--no-edit", "--ff", shortRef]);
+        if (merge.status !== 0) {
+            const paths = unmergedPaths(agentRoot, agentName);
+            if (paths.length === 0) {
+                // Refused before touching anything ("would be overwritten"): no conflict state.
+                abortMergeIfAny(agentRoot, agentName);
+                const error = gitFailure(["merge"], merge).message;
+                recordPendingSync(agentRoot, error, "unknown", []);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "heart",
+                    event: "heart.sync_merge_failed",
+                    message: "sync: merge refused",
+                    meta: { agentRoot, error },
+                });
+                return { result: { ok: false, error } };
+            }
+            if (paths.some((p) => !p.startsWith("psyche/")))
+                return handleNonPsycheConflict(agentRoot, config, agentName, paths);
+            mergeOwnerWins(agentRoot, agentName, shortRef, paths);
+        }
+        settleIntegrated(agentRoot, config, agentName);
+        return { result: { ok: true } };
     }
     catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
+        abortMergeIfAny(agentRoot, agentName);
+        const error = errorText(err);
         recordPendingSync(agentRoot, error, "unknown", []);
         (0, runtime_1.emitNervesEvent)({
+            level: "warn",
             component: "heart",
-            event: "heart.sync_push_error",
-            message: "post-turn push: git status failed",
+            event: "heart.sync_merge_failed",
+            message: "sync: integrate failed",
             meta: { agentRoot, error },
         });
-        return { ok: false, error };
+        return { result: { ok: false, error } };
     }
-    if (statusOutput.length === 0) {
-        // Nothing to commit, so nothing is skipped for size any more.
-        writeSkippedSyncFiles(agentRoot, []);
-        return syncCleanTree(agentRoot, config);
+}
+/**
+ * Merge the fetched remote branch into the bundle. Synchronous. The caller
+ * holds the bundle lock. Steps: repair an interrupted rebase or merge, commit
+ * local changes, then merge `<remote>/<branch>` (fast-forward when possible).
+ * Conflicts only in `psyche/` go to the owner; any other conflict aborts the
+ * merge and is recorded in `state/pending-sync.json`.
+ */
+function integrateFetched(agentRoot, config, agentName) {
+    return integrateCore(agentRoot, config, agentName).result;
+}
+// ---------- network steps ----------
+async function fetchUnlocked(agentRoot, config, agentName, signal) {
+    const branch = branchOf(config);
+    const timeoutMs = exports.__testHooks.fetchTimeoutMs ?? exports.SYNC_FETCH_TIMEOUT_MS;
+    const run = await runGitAsync(agentRoot, agentName, ["fetch", "--no-tags", config.remote, `+refs/heads/${branch}:${remoteTrackingRef(config)}`], timeoutMs, signal);
+    // An empty remote has no branch yet; integrate then only commits.
+    if (run.status === 0 || /couldn't find remote ref/i.test(run.stderr))
+        return { ok: true };
+    const error = describeAsyncFailure("fetch", run, timeoutMs);
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_fetch_error",
+        message: "sync: fetch failed",
+        meta: { agentRoot, remote: config.remote, branch, error },
+    });
+    return { ok: false, error };
+}
+/** `git fetch <remote> <branch>` as a detached child, killed by process group at 10 s or on abort. The caller holds the lock. */
+function fetchRemote(agentRoot, config, signal) {
+    return fetchUnlocked(agentRoot, config, agentNameFromRoot(agentRoot), signal);
+}
+/**
+ * `git ls-remote <remote> [patterns]` the way sync's own fetch and push reach
+ * the remote: the same flags and environment (in the container, the ouro-sync
+ * ssh), detached and killed by process group at the fetch timeout. `refs` are
+ * the ref names listed; an empty remote lists none.
+ */
+async function listRemoteRefs(agentRoot, remote, patterns = [], signal) {
+    const timeoutMs = exports.__testHooks.fetchTimeoutMs ?? exports.SYNC_FETCH_TIMEOUT_MS;
+    const run = await runGitAsync(agentRoot, agentNameFromRoot(agentRoot), ["ls-remote", remote, ...patterns], timeoutMs, signal);
+    if (run.status !== 0)
+        return { ok: false, error: describeAsyncFailure("ls-remote", run, timeoutMs) };
+    const refs = run.stdout.split("\n").map((line) => line.split("\t")[1]).filter((ref) => ref !== undefined && ref.length > 0);
+    return { ok: true, refs };
+}
+/**
+ * Spec R3.10: sync never makes the first push to an empty remote (one with no
+ * refs) without the owner's yes. A remote branch fetched before means the
+ * remote has history, and no network is needed. Otherwise the remote is asked;
+ * when it is empty and no yes came with this push, the push is held and the
+ * owner is told once. A remote that cannot be asked is not pushed to.
+ */
+async function holdFirstPush(agentRoot, config, agentName, options, signal) {
+    if (options.firstPushApproved === true || refExists(agentRoot, agentName, remoteTrackingRef(config)))
+        return null;
+    const listed = await listRemoteRefs(agentRoot, config.remote, [], signal);
+    if (!listed.ok)
+        return { ok: false, error: `could not check whether ${config.remote} is empty before pushing to it: ${listed.error}` };
+    if (listed.refs.length > 0)
+        return null;
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_first_push_held",
+        message: "sync: remote is empty; holding the first push for the owner's yes",
+        meta: { agentRoot, remote: config.remote },
+    });
+    if (!fs.existsSync(firstPushHeldPath(agentRoot))) {
+        fs.mkdirSync(path.dirname(firstPushHeldPath(agentRoot)), { recursive: true });
+        fs.writeFileSync(firstPushHeldPath(agentRoot), `${JSON.stringify({ remote: config.remote, at: new Date().toISOString() })}\n`);
+        tellOwner(agentRoot, agentName, { noticeId: `sync-first-push-held:${agentName}`, text: exports.FIRST_PUSH_HELD_NOTICE });
     }
-    const changedCount = statusOutput.split("\n").length;
-    clearStaleIndexLock(agentRoot);
+    return { ok: false, firstPushHeld: true, error: `${config.remote} is empty, so the first push waits for the owner's yes (bundle_first_push_review)` };
+}
+async function pushUnlocked(agentRoot, config, agentName, signal, options = {}) {
     try {
-        (0, child_process_1.execFileSync)("git", ["add", "-A"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: exports.SYNC_GIT_TIMEOUT_MS,
-            maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-        });
-        const skippedFiles = unstageOversizedFiles(agentRoot);
-        writeSkippedSyncFiles(agentRoot, skippedFiles);
-        if (skippedFiles.length > 0 && !hasStagedChanges(agentRoot)) {
+        if (!hasRemote(agentRoot, agentName, config)) {
+            settlePendingSync(agentRoot);
             (0, runtime_1.emitNervesEvent)({
                 component: "heart",
                 event: "heart.sync_push_end",
-                message: "post-turn push: only oversized files changed, nothing committed",
-                meta: { agentRoot, changedCount, skippedCount: skippedFiles.length },
+                message: "sync: committed locally, no remote configured",
+                meta: { agentRoot },
             });
-            return syncCleanTree(agentRoot, config);
+            return { ok: true };
         }
-        // -q: without it git prints a create/delete line per file, which overran
-        // the output buffer on a 30,000-file commit after the commit had landed.
-        (0, child_process_1.execFileSync)("git", ["commit", "-q", "-m", "sync: post-turn update"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: exports.SYNC_GIT_TIMEOUT_MS,
-            maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-        });
-        if (!hasRemote(agentRoot)) {
+        const held = await holdFirstPush(agentRoot, config, agentName, options, signal);
+        if (held)
+            return held;
+        const branch = branchOf(config);
+        const timeoutMs = exports.__testHooks.pushTimeoutMs ?? exports.SYNC_PUSH_TIMEOUT_MS;
+        const run = await runGitAsync(agentRoot, agentName, ["push", config.remote, `HEAD:refs/heads/${branch}`], timeoutMs, signal);
+        if (run.status === 0) {
+            settlePendingSync(agentRoot);
+            fs.rmSync(firstPushHeldPath(agentRoot), { force: true });
             (0, runtime_1.emitNervesEvent)({
                 component: "heart",
                 event: "heart.sync_push_end",
-                message: "post-turn push: committed locally, no remote configured",
-                meta: { agentRoot, changedCount },
+                message: "sync: push complete",
+                meta: { agentRoot, remote: config.remote, branch },
             });
-            clearPendingSync(agentRoot);
             return { ok: true };
         }
-        return pushWithRebaseRetry(agentRoot, config, changedCount);
+        const rejected = !run.timedOut && !run.aborted && /\[rejected\]|non-fast-forward|fetch first/.test(run.stderr);
+        const error = describeAsyncFailure("push", run, timeoutMs);
+        const classification = rejected ? "push_rejected" : "unknown";
+        recordPendingSync(agentRoot, error, classification, []);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_push_error",
+            message: `sync: push failed: ${classification}`,
+            meta: { agentRoot, error, classification },
+        });
+        return { ok: false, error };
     }
     catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        // Record it so the start-of-turn packet surfaces the failure; otherwise a
-        // failing local commit is visible only in nerves logs.
+        const error = errorText(err);
         recordPendingSync(agentRoot, error, "unknown", []);
         (0, runtime_1.emitNervesEvent)({
+            level: "warn",
             component: "heart",
             event: "heart.sync_push_error",
-            message: "post-turn push failed",
+            message: "sync: push failed",
             meta: { agentRoot, error },
         });
         return { ok: false, error };
     }
 }
-function hasRemote(agentRoot) {
-    return (0, child_process_1.execFileSync)("git", ["remote"], {
-        cwd: agentRoot,
-        stdio: "pipe",
-        timeout: 5000,
-    }).toString().trim().length > 0;
-}
 /**
- * Nothing new to commit. A failure record must not outlive the problem, and
- * commits left behind by an earlier failed push still need to reach the
- * remote: with no remote, or nothing ahead of the upstream, the record is
- * cleared; with unpushed commits, the push is retried.
+ * `git push <remote> HEAD:<branch>` as a detached child, killed by process
+ * group at 60 s. It takes the lock the caller acquired before committing and
+ * releases it when the push ends, so nothing runs between commit and push. A
+ * rejection is recorded as `push_rejected`; the next integrate merges and the
+ * push after it succeeds. Never throws.
  */
-function syncCleanTree(agentRoot, config) {
+async function pushAsync(agentRoot, config, handle, signal) {
     try {
-        if (!hasRemote(agentRoot)) {
-            clearPendingSync(agentRoot);
-        }
-        else {
-            const ahead = Number.parseInt((0, child_process_1.execFileSync)("git", ["rev-list", "--count", "@{upstream}..HEAD"], {
-                cwd: agentRoot,
-                stdio: "pipe",
-                timeout: 5000,
-            }).toString().trim(), 10);
-            if (ahead > 0)
-                return pushWithRebaseRetry(agentRoot, config, 0);
-            if (ahead === 0)
-                clearPendingSync(agentRoot);
-        }
+        return await pushUnlocked(agentRoot, config, agentNameFromRoot(agentRoot), signal);
     }
-    catch (err) {
-        // No upstream tracked (or git failed): nothing to compare against, so
-        // leave any failure record as it is rather than guess.
+    finally {
+        handle.release();
+    }
+}
+// ---------- building blocks for other bundle writers (ouro move, the home check) ----------
+/** The active pause's `expiresAt`, or null. Reads the marker and changes nothing. */
+function syncPausedUntil(agentRoot) {
+    const state = readPauseMarker(agentRoot);
+    return state.kind === "active" ? state.expiresAt : null;
+}
+/** `refs/remotes/<remote>/<branch>`, the ref `fetchRemote` updates. */
+function syncTrackingRef(config) {
+    return remoteTrackingRef(config);
+}
+/**
+ * Take the bundle sync lock, waiting up to `waitMs`. While it is held, a
+ * SIGTERM or SIGINT kills sync's git children and releases it, as for sync itself.
+ */
+async function holdSyncLock(agentRoot, waitMs) {
+    const acquired = waitMs > 0 ? await (0, sync_lock_1.acquireSyncLock)(agentRoot, waitMs) : (0, sync_lock_1.tryAcquireSyncLockSync)(agentRoot);
+    return "busy" in acquired ? acquired : trackLock(acquired);
+}
+/**
+ * `git push <remote> HEAD:refs/heads/<branch>` as a detached child, killed by
+ * process group at 60 s. It records nothing in `state/pending-sync.json`: the
+ * caller, which holds the lock, decides what a refusal means.
+ */
+async function pushHeadToBranch(agentRoot, config, signal) {
+    const timeoutMs = exports.__testHooks.pushTimeoutMs ?? exports.SYNC_PUSH_TIMEOUT_MS;
+    const run = await runGitAsync(agentRoot, agentNameFromRoot(agentRoot), ["push", config.remote, `HEAD:refs/heads/${branchOf(config)}`], timeoutMs, signal);
+    if (run.status === 0)
+        return { ok: true };
+    const rejected = !run.timedOut && !run.aborted && /\[rejected\]|non-fast-forward|fetch first/.test(run.stderr);
+    return { ok: false, rejected, error: describeAsyncFailure("push", run, timeoutMs) };
+}
+/** The same conflict recurred: put the agent's side where the owner can merge it from the Mac. */
+async function pushConflictBranch(agentRoot, config, agentName, state, signal) {
+    const branch = `sync-conflict/${agentName}`;
+    const head = git(agentRoot, agentName, ["rev-parse", "HEAD"]).trim();
+    // Pushed already, and nothing new since: skip the network.
+    if (state.branchPushedHead === head)
+        return;
+    const timeoutMs = exports.__testHooks.pushTimeoutMs ?? exports.SYNC_PUSH_TIMEOUT_MS;
+    const run = await runGitAsync(agentRoot, agentName, ["push", config.remote, `HEAD:refs/heads/${branch}`], timeoutMs, signal);
+    if (run.status !== 0) {
         (0, runtime_1.emitNervesEvent)({
+            level: "warn",
             component: "heart",
-            event: "heart.sync_upstream_unknown",
-            message: "post-turn push: could not compare with upstream",
-            meta: { agentRoot, error: err instanceof Error ? err.message : /* v8 ignore next -- defensive non-Error catch @preserve */ String(err) },
+            event: "heart.sync_conflict_branch_push_error",
+            message: "sync: could not push the conflict branch",
+            meta: { agentRoot, branch, error: describeAsyncFailure("push", run, timeoutMs) },
         });
+        return;
     }
     (0, runtime_1.emitNervesEvent)({
         component: "heart",
-        event: "heart.sync_push_end",
-        message: "post-turn push: no changes to sync",
-        meta: { agentRoot },
+        event: "heart.sync_conflict_branch_pushed",
+        message: "sync: pushed the agent's side of a conflict",
+        meta: { agentRoot, branch },
+    });
+    writeConflictState(agentRoot, { ...state, branchNoticeSent: true, branchPushedHead: head });
+    if (state.branchNoticeSent)
+        return;
+    tellOwner(agentRoot, agentName, {
+        noticeId: `sync-conflict-branch:${agentName}:${state.hash}`,
+        text: `My side of the sync conflict in ${state.paths.join(", ")} is on branch ${branch} in ${config.remote}. Merging it into ${branchOf(config)} from the Mac resumes sync.`,
     });
-    return { ok: true };
 }
-function pushWithRebaseRetry(agentRoot, config, changedCount) {
+/** An unborn HEAD (nothing ever committed) has nothing to push. */
+function pushIfBorn(agentRoot, config, agentName, options) {
+    if (refExists(agentRoot, agentName, "HEAD"))
+        return pushUnlocked(agentRoot, config, agentName, undefined, options);
+    settlePendingSync(agentRoot);
+    return Promise.resolve({ ok: true });
+}
+/** Fetch then integrate. The caller holds the lock. */
+async function pullUnlocked(agentRoot, config, agentName, signal, commitMessage) {
+    let remote;
     try {
-        (0, child_process_1.execFileSync)("git", ["push", config.remote], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: exports.SYNC_GIT_TIMEOUT_MS,
-            maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-        });
+        remote = hasRemote(agentRoot, agentName, config);
     }
-    catch {
-        // Push rejected -- try pull-rebase-push. --autostash: an oversized file
-        // the size guard left uncommitted is an unstaged change, and a plain
-        // rebase refuses to start while one exists.
-        let rebaseError = null;
+    catch (err) {
+        return { ok: false, error: errorText(err) };
+    }
+    if (remote) {
+        const fetched = await fetchUnlocked(agentRoot, config, agentName, signal);
+        if (!fetched.ok)
+            return fetched;
+    }
+    const outcome = integrateCore(agentRoot, config, agentName, commitMessage);
+    if (outcome.conflictBranch)
+        await pushConflictBranch(agentRoot, config, agentName, outcome.conflictBranch, signal);
+    return outcome.result;
+}
+/** Commits on each side of HEAD and the last fetched remote branch. */
+function aheadBehind(agentRoot, agentName, config) {
+    const ahead = commitsAhead(agentRoot, agentName, config);
+    const ref = remoteTrackingRef(config);
+    if (!refExists(agentRoot, agentName, ref))
+        return { ahead, behind: 0 };
+    const range = refExists(agentRoot, agentName, "HEAD") ? `HEAD..${ref}` : ref;
+    return { ahead, behind: Number.parseInt(git(agentRoot, agentName, ["rev-list", "--count", range]).trim(), 10) };
+}
+/**
+ * The boot probe: fetch the remote branch and count commits ahead and behind.
+ * It takes the lock without waiting, never merges, commits or pushes, and
+ * writes nothing under `state/` (an expired pause marker is left for the next
+ * sync to remove).
+ */
+async function probeSync(agentRoot, config, signal) {
+    const agentName = agentNameFromRoot(agentRoot);
+    const pause = readPauseMarker(agentRoot);
+    if (pause.kind === "active")
+        return { ok: true, paused: true, pausedUntil: pause.expiresAt };
+    const repoCheck = ensureGitRepo(agentRoot, "boot probe");
+    if (!repoCheck.ok)
+        return repoCheck;
+    try {
+        const acquired = (0, sync_lock_1.tryAcquireSyncLockSync)(agentRoot);
+        if ("busy" in acquired)
+            return { ok: true, busy: true, holderPid: acquired.holderPid };
+        const lock = trackLock(acquired);
         try {
-            (0, child_process_1.execFileSync)("git", ["pull", "--rebase", "--autostash", config.remote], {
-                cwd: agentRoot,
-                stdio: "pipe",
-                timeout: exports.SYNC_GIT_TIMEOUT_MS,
-                maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-            });
-        }
-        catch (err) {
-            rebaseError = err instanceof Error ? err.message : String(err);
-        }
-        if (rebaseError === null) {
-            try {
-                (0, child_process_1.execFileSync)("git", ["push", config.remote], {
-                    cwd: agentRoot,
-                    stdio: "pipe",
-                    timeout: exports.SYNC_GIT_TIMEOUT_MS,
-                    maxBuffer: exports.SYNC_GIT_MAX_BUFFER_BYTES,
-                });
-                // rebase + retry push both succeeded — fall through to success
-                (0, runtime_1.emitNervesEvent)({
-                    component: "heart",
-                    event: "heart.sync_push_end",
-                    message: "post-turn push complete after rebase retry",
-                    meta: { agentRoot, changedCount },
-                });
-                clearPendingSync(agentRoot);
+            if (!hasRemote(agentRoot, agentName, config))
                 return { ok: true };
-            }
-            catch (retryErr) {
-                // Second push rejected — remote advanced again during rebase
-                const retryError = retryErr instanceof Error ? retryErr.message : /* v8 ignore next -- defensive non-Error catch @preserve */ String(retryErr);
-                recordPendingSync(agentRoot, retryError, "push_rejected", []);
-                (0, runtime_1.emitNervesEvent)({
-                    component: "heart",
-                    event: "heart.sync_push_error",
-                    message: "post-turn push failed after retry: push_rejected",
-                    meta: { agentRoot, error: retryError, classification: "push_rejected" },
-                });
-                return { ok: false, error: retryError };
-            }
+            const fetched = await fetchUnlocked(agentRoot, config, agentName, signal);
+            if (!fetched.ok)
+                return fetched;
+            return { ok: true, ...aheadBehind(agentRoot, agentName, config) };
+        }
+        finally {
+            lock.release();
         }
-        // Rebase failed — detect conflict files via git status. Preserve
-        // the original rebase error message so callers see the real cause.
-        const conflictFiles = collectRebaseConflictFiles(agentRoot);
-        const classification = conflictFiles.length > 0 ? "pull_rebase_conflict" : "unknown";
-        recordPendingSync(agentRoot, rebaseError, classification, conflictFiles);
-        (0, runtime_1.emitNervesEvent)({
-            component: "heart",
-            event: "heart.sync_push_error",
-            message: `post-turn push failed: ${classification}`,
-            meta: { agentRoot, error: rebaseError, classification, conflictFiles },
-        });
-        return { ok: false, error: rebaseError };
     }
-    (0, runtime_1.emitNervesEvent)({
-        component: "heart",
-        event: "heart.sync_push_end",
-        message: "post-turn push complete",
-        meta: { agentRoot, changedCount },
-    });
-    clearPendingSync(agentRoot);
-    return { ok: true };
+    catch (err) {
+        return { ok: false, error: errorText(err) };
+    }
 }
 /**
- * Layer 2 — async, signal-aware sibling of `preTurnPull`.
- *
- * Used by `runBootSyncProbe` (the `ouro up` boot orchestrator) to perform
- * the pre-flight pull with end-to-end `AbortSignal` propagation. The
- * underlying `child_process.execFile` accepts the signal and kills the git
- * child process when it aborts, so a hung remote (DNS hole, slow server)
- * can be cut by the boot timeout wrapper rather than hanging the whole
- * boot.
- *
- * The legacy sync `preTurnPull` is preserved unchanged for the per-turn
- * pipeline at `src/senses/pipeline.ts:522`. The two functions share the
- * same `.git` and remote-availability gates — the only difference is the
- * pull itself: `execFileSync` (no signal) vs `execFile` + `{ signal }`.
- *
- * Honour-the-signal contract:
- *   - If `options.signal` is already aborted at call time, the pull is
- *     skipped and the result is `{ ok: false, error: "aborted" }`.
- *   - If `options.signal` aborts mid-fetch, the child receives `SIGTERM`
- *     via Node's built-in AbortSignal handling, and the result is
- *     `{ ok: false, error: <abort message> }`.
- *   - With no signal supplied, behaviour matches the sync version (subject
- *     to the small differences listed above — same git-repo / no-remote
- *     gates and same nerves events).
+ * Pre-turn pull: under the bundle lock (waiting up to 5 s, then skipping),
+ * fetch the remote branch and merge it, so the turn reads the owner's latest
+ * edits. With no remote, local changes are committed and the result is ok.
  */
-function preTurnPullAsync(agentRoot, config, options = {}) {
+async function preTurnPull(agentRoot, config, options = {}) {
+    const agentName = options.agentName ?? agentNameFromRoot(agentRoot);
     (0, runtime_1.emitNervesEvent)({
         component: "heart",
         event: "heart.sync_pull_start",
-        message: "pre-turn pull starting (async)",
-        meta: { agentRoot, remote: config.remote },
+        message: "pre-turn pull starting",
+        meta: { agentRoot, remote: config.remote, branch: branchOf(config) },
     });
-    // Bail early when the caller has already aborted — saves a git invocation
-    // and signals failure consistently.
+    const paused = pausedResult(agentRoot, "pre-turn pull");
+    if (paused)
+        return paused;
+    const repoCheck = ensureGitRepo(agentRoot, "pre-turn pull");
+    if (!repoCheck.ok)
+        return repoCheck;
     if (options.signal?.aborted) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
@@ -650,77 +1408,172 @@ function preTurnPullAsync(agentRoot, config, options = {}) {
             message: "pre-turn pull skipped: signal already aborted",
             meta: { agentRoot },
         });
-        return Promise.resolve({ ok: false, error: "aborted before pull started" });
+        return { ok: false, error: "aborted before pull started" };
     }
-    // Same .git presence check as the sync version.
-    const repoCheck = ensureGitRepo(agentRoot);
-    if (!repoCheck.ok) {
+    let acquired;
+    try {
+        acquired = await (0, sync_lock_1.acquireSyncLock)(agentRoot, exports.__testHooks.preTurnLockWaitMs ?? exports.PRE_TURN_LOCK_WAIT_MS, options.signal);
+    }
+    catch (err) {
+        return { ok: false, error: `aborted while waiting for the sync lock: ${errorText(err)}` };
+    }
+    if ("busy" in acquired) {
         (0, runtime_1.emitNervesEvent)({
-            level: "warn",
             component: "heart",
-            event: "heart.sync_not_a_repo",
-            message: "pre-turn pull failed: bundle is not a git repo (async)",
-            meta: { agentRoot },
+            event: "heart.sync_pull_end",
+            message: "pre-turn pull skipped: sync lock busy",
+            meta: { agentRoot, holderPid: acquired.holderPid },
         });
-        return Promise.resolve(repoCheck);
+        return { ok: true, busy: true, holderPid: acquired.holderPid };
     }
-    // Remote-presence check stays sync — it's a fast local op and doesn't
-    // need cancellation. The hangable op is the actual pull.
+    const lock = trackLock(acquired);
     try {
-        const remoteOutput = (0, child_process_1.execFileSync)("git", ["remote"], {
-            cwd: agentRoot,
-            stdio: "pipe",
-            timeout: 5000,
-        }).toString().trim();
-        if (remoteOutput.length === 0) {
+        // A pause written while this waited for the lock still wins.
+        const pausedNow = pausedResult(agentRoot, "pre-turn pull");
+        if (pausedNow)
+            return pausedNow;
+        const result = await pullUnlocked(agentRoot, config, agentName, options.signal);
+        if (result.ok) {
+            (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.sync_pull_end", message: "pre-turn pull complete", meta: { agentRoot } });
+        }
+        else {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "heart", event: "heart.sync_pull_error", message: "pre-turn pull failed", meta: { agentRoot, error: result.error } });
+        }
+        return result;
+    }
+    finally {
+        lock.release();
+    }
+}
+/** Same as `preTurnPull`, kept for older callers. */
+function preTurnPullAsync(agentRoot, config, options = {}) {
+    return preTurnPull(agentRoot, config, options);
+}
+/**
+ * Post-turn push. Synchronous up to the push: take the lock without waiting
+ * (busy means skip; the next turn commits), commit, then hand the held lock to
+ * `pushAsync`, which is not awaited. `push` in the result is that promise.
+ */
+function postTurnPush(agentRoot, config, agentName = agentNameFromRoot(agentRoot)) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_push_start",
+        message: "post-turn push starting",
+        meta: { agentRoot, remote: config.remote, branch: branchOf(config) },
+    });
+    const repoCheck = ensureGitRepo(agentRoot, "post-turn push");
+    if (!repoCheck.ok)
+        return repoCheck;
+    const acquired = (0, sync_lock_1.tryAcquireSyncLockSync)(agentRoot);
+    if ("busy" in acquired) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.sync_push_end",
+            message: "post-turn push skipped: sync lock busy",
+            meta: { agentRoot, holderPid: acquired.holderPid },
+        });
+        return { ok: true, busy: true, holderPid: acquired.holderPid };
+    }
+    const lock = trackLock(acquired);
+    let release = true;
+    try {
+        // Checked under the lock, so a pauser that saw the lock free sees no git after it.
+        const paused = pausedResult(agentRoot, "post-turn push");
+        if (paused)
+            return paused;
+        const repairFailure = repairInterrupted(agentRoot, agentName);
+        if (repairFailure)
+            return repairFailure;
+        commitLocalChanges(agentRoot, agentName, "sync: post-turn update");
+        // The turn waits only up to here: the network push, when there is one, runs after it.
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.sync_commit_end", message: "post-turn commit done", meta: { agentRoot } });
+        const remote = hasRemote(agentRoot, agentName, config);
+        if (remote && readPreviousFailure(agentRoot)?.classification === "pull_rebase_conflict") {
+            // The push would be rejected until the conflict is merged; the next integrate retries it.
             (0, runtime_1.emitNervesEvent)({
                 component: "heart",
-                event: "heart.sync_pull_end",
-                message: "pre-turn pull skipped: no remote configured (async)",
+                event: "heart.sync_push_end",
+                message: "post-turn push: committed, push waits for an unresolved conflict",
                 meta: { agentRoot },
             });
-            return Promise.resolve({ ok: true });
+            return { ok: true };
+        }
+        if (remote && commitsAhead(agentRoot, agentName, config) === 0) {
+            settlePendingSync(agentRoot);
+            (0, runtime_1.emitNervesEvent)({
+                component: "heart",
+                event: "heart.sync_push_end",
+                message: "post-turn push: nothing to push",
+                meta: { agentRoot },
+            });
+            return { ok: true };
         }
+        release = false;
+        return { ok: true, push: pushAsync(agentRoot, config, lock) };
     }
     catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
+        const error = errorText(err);
+        recordPendingSync(agentRoot, error, "unknown", []);
         (0, runtime_1.emitNervesEvent)({
+            level: "warn",
             component: "heart",
-            event: "heart.sync_pull_error",
-            message: "pre-turn pull failed: git remote check failed (async)",
+            event: "heart.sync_push_error",
+            message: "post-turn push failed",
             meta: { agentRoot, error },
         });
-        return Promise.resolve({ ok: false, error });
+        return { ok: false, error };
     }
-    // The hangable op. `execFile` accepts `{ signal }` and kills the child
-    // when the signal aborts — that's the whole point of the async path.
-    const execOptions = {
-        cwd: agentRoot,
-        timeout: 30000,
-    };
-    if (options.signal) {
-        execOptions.signal = options.signal;
+    finally {
+        if (release)
+            lock.release();
     }
-    return new Promise((resolve) => {
-        (0, child_process_1.execFile)("git", ["pull", config.remote], execOptions, (err) => {
-            if (err) {
-                const error = err instanceof Error ? err.message : String(err);
-                (0, runtime_1.emitNervesEvent)({
-                    component: "heart",
-                    event: "heart.sync_pull_error",
-                    message: "pre-turn pull failed (async)",
-                    meta: { agentRoot, error },
-                });
-                resolve({ ok: false, error });
-                return;
-            }
-            (0, runtime_1.emitNervesEvent)({
-                component: "heart",
-                event: "heart.sync_pull_end",
-                message: "pre-turn pull complete (async)",
-                meta: { agentRoot },
-            });
-            resolve({ ok: true });
-        });
+}
+/**
+ * Manual sync (`ouro sync`, the bundle tools): under one lock, waiting up to
+ * `waitMs`, fetch, integrate and push. Built on the unlocked internals, so it
+ * never waits on its own lock.
+ */
+async function syncNow(agentRoot, config, agentName, waitMs, options = {}) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.sync_now_start",
+        message: "sync now starting",
+        meta: { agentRoot, remote: config.remote, branch: branchOf(config) },
     });
+    const paused = pausedResult(agentRoot, "sync now");
+    if (paused)
+        return paused;
+    const repoCheck = ensureGitRepo(agentRoot, "sync now");
+    if (!repoCheck.ok)
+        return repoCheck;
+    const acquired = await (0, sync_lock_1.acquireSyncLock)(agentRoot, waitMs);
+    if ("busy" in acquired) {
+        const error = `bundle sync lock is held${acquired.holderPid === null ? "" : ` by pid ${acquired.holderPid}`}`;
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_now_error",
+            message: "sync now: lock busy",
+            meta: { agentRoot, error },
+        });
+        return { ok: false, busy: true, holderPid: acquired.holderPid, error };
+    }
+    const lock = trackLock(acquired);
+    try {
+        const pausedNow = pausedResult(agentRoot, "sync now");
+        if (pausedNow)
+            return pausedNow;
+        const pulled = await pullUnlocked(agentRoot, config, agentName, undefined, "sync: update");
+        const result = pulled.ok ? await pushIfBorn(agentRoot, config, agentName, options) : pulled;
+        if (result.ok) {
+            (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.sync_now_end", message: "sync now complete", meta: { agentRoot } });
+        }
+        else {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "heart", event: "heart.sync_now_error", message: "sync now failed", meta: { agentRoot, error: result.error } });
+        }
+        return result;
+    }
+    finally {
+        lock.release();
+    }
 }