@ouro.bot/cli 0.1.0-alpha.99 → 0.1.0-alpha.991

package/dist/heart/sync.js

@@ -0,0 +1,1579 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+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.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
+ * unpushed commit blocks every later push from the bundle. The guard leaves
+ * the file in the working tree, uncommitted, and records it.
+ */
+exports.SYNC_FILE_SIZE_LIMIT_BYTES = 50 * 1024 * 1024;
+/**
+ * Output buffer for git commands whose output grows with the number of
+ * changed files. Node's 1 MiB default made `git status` fail with ENOBUFS
+ * once a bundle held about 30,000 changed files, which stopped sync.
+ */
+exports.SYNC_GIT_MAX_BUFFER_BYTES = 256 * 1024 * 1024;
+/**
+ * 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")));
+    }
+    catch {
+        return null;
+    }
+}
+/** 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;
+    fs.mkdirSync(path.join(agentRoot, "state"), { recursive: true });
+    const record = {
+        error,
+        failedAt,
+        classification,
+        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, 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, repairRef);
+    }
+    catch {
+        // Best effort: the caller's nerves event still records the failure.
+    }
+}
+/**
+ * Remove `state/pending-sync.json` after a sync that reached the remote (or
+ * committed, for a local-only bundle). The record otherwise stays, so the
+ * start-of-turn packet, `ouro status` and the daemon health check keep
+ * reporting the failure until it is fixed.
+ */
+function clearPendingSync(agentRoot) {
+    try {
+        fs.rmSync(pendingSyncPath(agentRoot), { force: true });
+    }
+    catch {
+        // 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) {
+            fs.rmSync(skippedSyncFilesPath(agentRoot), { force: true });
+            return;
+        }
+        fs.mkdirSync(path.join(agentRoot, "state"), { recursive: true });
+        const record = {
+            updatedAt: new Date().toISOString(),
+            limitBytes: exports.SYNC_FILE_SIZE_LIMIT_BYTES,
+            files,
+        };
+        fs.writeFileSync(skippedSyncFilesPath(agentRoot), JSON.stringify(record, null, 2), "utf-8");
+    }
+    catch {
+        // 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);
+    const changes = [];
+    for (let index = 0; index < tokens.length;) {
+        const status = tokens[index];
+        if (status.startsWith("R") || status.startsWith("C")) {
+            changes.push({ status, fromPath: tokens[index + 1], path: tokens[index + 2] });
+            index += 3;
+        }
+        else {
+            changes.push({ status, path: tokens[index + 1] });
+            index += 2;
+        }
+    }
+    return changes;
+}
+/**
+ * Unstage every staged file larger than `SYNC_FILE_SIZE_LIMIT_BYTES`. The
+ * file stays in the working tree and the previous committed version, if any,
+ * stays in the index, so nothing is deleted on other machines. For a rename,
+ * 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, agentName) {
+    const changes = parseStagedChanges(git(agentRoot, agentName, ["diff", "--cached", "--name-status", "-M", "-z"]));
+    const oversized = [];
+    const unstage = [];
+    for (const change of changes) {
+        if (change.status.startsWith("D"))
+            continue;
+        let bytes;
+        try {
+            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)
+            continue;
+        oversized.push({ path: change.path, bytes });
+        unstage.push(change.path);
+        if (change.status.startsWith("R") && change.fromPath)
+            unstage.push(change.fromPath);
+    }
+    if (oversized.length === 0)
+        return oversized;
+    // 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: "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, agentName) {
+    return runGit(agentRoot, agentName, ["diff", "--cached", "--quiet"]).status !== 0;
+}
+/**
+ * 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
+// after creating it, while a live `git commit` waiting in an editor holds a
+// 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 = gitDirEntry(agentRoot, "index.lock");
+    let ageMs;
+    try {
+        const stat = fs.statSync(lockPath);
+        if (stat.size !== 0)
+            return;
+        ageMs = Date.now() - stat.mtimeMs;
+    }
+    catch {
+        return;
+    }
+    if (ageMs < exports.STALE_INDEX_LOCK_MS)
+        return;
+    try {
+        fs.rmSync(lockPath, { force: true });
+    }
+    catch (err) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_stale_lock_clear_failed",
+            message: "sync: could not remove stale git index.lock",
+            meta: { agentRoot, lockPath, error: errorText(err) },
+        });
+        return;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.sync_stale_lock_cleared",
+        message: "sync: removed stale git index.lock",
+        meta: { agentRoot, lockPath, ageMs },
+    });
+}
+/**
+ * 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 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_not_a_repo",
+        message: `${step} failed: bundle is not a git repo`,
+        meta: { agentRoot },
+    });
+    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();
+    }
+    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 {
+        ref = snapshotWorkingTree(agentRoot, agentName);
+    }
+    catch (err) {
+        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 {
+        if (restore.length > 0)
+            gitOnPaths(agentRoot, agentName, ["restore", `--source=${ref}`, "--worktree"], restore);
+    }
+    catch (err) {
+        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 };
+}
+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"]);
+}
+/**
+ * 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 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_owner_wins",
+        message: "sync: merged with the owner's psyche edits winning conflicts",
+        meta: { agentRoot, paths },
+    });
+}
+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 {
+        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) {
+        abortMergeIfAny(agentRoot, agentName);
+        const error = errorText(err);
+        recordPendingSync(agentRoot, error, "unknown", []);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_merge_failed",
+            message: "sync: integrate failed",
+            meta: { agentRoot, error },
+        });
+        return { result: { ok: false, error } };
+    }
+}
+/**
+ * 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 });
+    }
+    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 {
+        if (!hasRemote(agentRoot, agentName, config)) {
+            settlePendingSync(agentRoot);
+            (0, runtime_1.emitNervesEvent)({
+                component: "heart",
+                event: "heart.sync_push_end",
+                message: "sync: committed locally, no remote configured",
+                meta: { agentRoot },
+            });
+            return { ok: true };
+        }
+        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: "sync: push complete",
+                meta: { agentRoot, remote: config.remote, branch },
+            });
+            return { ok: true };
+        }
+        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 = errorText(err);
+        recordPendingSync(agentRoot, error, "unknown", []);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_push_error",
+            message: "sync: push failed",
+            meta: { agentRoot, error },
+        });
+        return { ok: false, error };
+    }
+}
+/**
+ * `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.
+ */
+async function pushAsync(agentRoot, config, handle, signal) {
+    try {
+        return await pushUnlocked(agentRoot, config, agentNameFromRoot(agentRoot), signal);
+    }
+    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_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_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.`,
+    });
+}
+/** 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 {
+        remote = hasRemote(agentRoot, agentName, config);
+    }
+    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 {
+            if (!hasRemote(agentRoot, agentName, config))
+                return { ok: true };
+            const fetched = await fetchUnlocked(agentRoot, config, agentName, signal);
+            if (!fetched.ok)
+                return fetched;
+            return { ok: true, ...aheadBehind(agentRoot, agentName, config) };
+        }
+        finally {
+            lock.release();
+        }
+    }
+    catch (err) {
+        return { ok: false, error: errorText(err) };
+    }
+}
+/**
+ * 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.
+ */
+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",
+        meta: { agentRoot, remote: config.remote, branch: branchOf(config) },
+    });
+    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",
+            component: "heart",
+            event: "heart.sync_pull_aborted",
+            message: "pre-turn pull skipped: signal already aborted",
+            meta: { agentRoot },
+        });
+        return { ok: false, error: "aborted before pull started" };
+    }
+    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)({
+            component: "heart",
+            event: "heart.sync_pull_end",
+            message: "pre-turn pull skipped: sync lock busy",
+            meta: { agentRoot, holderPid: acquired.holderPid },
+        });
+        return { ok: true, busy: true, holderPid: acquired.holderPid };
+    }
+    const lock = trackLock(acquired);
+    try {
+        // 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_push_end",
+                message: "post-turn push: committed, push waits for an unresolved conflict",
+                meta: { agentRoot },
+            });
+            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 = errorText(err);
+        recordPendingSync(agentRoot, error, "unknown", []);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "heart",
+            event: "heart.sync_push_error",
+            message: "post-turn push failed",
+            meta: { agentRoot, error },
+        });
+        return { ok: false, error };
+    }
+    finally {
+        if (release)
+            lock.release();
+    }
+}
+/**
+ * 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();
+    }
+}