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

package/dist/heart/daemon/cli-exec.js

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runMcpServeCliLifecycle = runMcpServeCliLifecycle;
 exports.summarizeDaemonStartupFailure = summarizeDaemonStartupFailure;
 exports.writeSyncProbeSummary = writeSyncProbeSummary;
+exports.writeSyncProbeStatuses = writeSyncProbeStatuses;
 exports.summarizeSyncProbeFindings = summarizeSyncProbeFindings;
 exports.mergeStartupStability = mergeStartupStability;
 exports.ensureDaemonRunning = ensureDaemonRunning;
@@ -54,6 +55,7 @@ exports.resolveMailImportFilePath = resolveMailImportFilePath;
 exports.runOuroCli = runOuroCli;
 const child_process_1 = require("child_process");
 const bluebubbles_host_account_1 = require("../bluebubbles-host-account");
+const sanctuary_bundle_migration_1 = require("./sanctuary-bundle-migration");
 const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
@@ -563,6 +565,7 @@ function agentResolutionFailureMode(command) {
         case "setup":
         case "bluebubbles.replay":
         case "bluebubbles.context-smoke":
+        case "sync":
             return "throw";
         default:
             return undefined;
@@ -744,6 +747,10 @@ function writeSyncProbeSummary(deps, findings) {
     }
     deps.writeStdout(lines.join("\n"));
 }
+/** What the boot probe saw in each bundle: paused, busy, or commits ahead and behind. */
+function writeSyncProbeStatuses(deps, statuses) {
+    deps.writeStdout(["sync status:", ...statuses.map((status) => `  ${status.agent}: ${status.text}`)].join("\n"));
+}
 function bootPhasePlan(_daemonAlive) {
     return ["update check", "system setup", "sync probe", "starting daemon", "provider checks", "final daemon check"];
 }
@@ -1621,24 +1628,63 @@ function readAgentSyncConfigForCliMutation(agent, deps) {
         return {
             enabled: parsed.sync?.enabled === true,
             remote: typeof parsed.sync?.remote === "string" && parsed.sync.remote.trim() ? parsed.sync.remote : "origin",
+            branch: typeof parsed.sync?.branch === "string" && parsed.sync.branch.trim() ? parsed.sync.branch : "main",
         };
     }
     catch {
         /* v8 ignore next -- defensive: post-mutation sync should not break an already-successful CLI repair if agent.json becomes unreadable @preserve */
-        return { enabled: false, remote: "origin" };
+        return { enabled: false, remote: "origin", branch: "main" };
     }
 }
-function pushAgentBundleAfterCliMutation(agent, deps) {
+/** How long a CLI command waits for the bundle sync lock before reporting busy. */
+const CLI_SYNC_LOCK_WAIT_MS = 60_000;
+/**
+ * Sync the bundle after a CLI change and report what actually happened. The
+ * sync is awaited: a one-shot CLI that exits explicitly would otherwise kill a
+ * push it had already reported.
+ */
+async function pushAgentBundleAfterCliMutation(agent, deps) {
     const sync = readAgentSyncConfigForCliMutation(agent, deps);
     if (!sync.enabled)
         return null;
     const agentRoot = providerCliAgentRoot({ agent }, deps);
-    const result = (0, sync_1.postTurnPush)(agentRoot, { enabled: true, remote: sync.remote });
+    const result = await (0, sync_1.syncNow)(agentRoot, sync, agent, deps.syncLockWaitMs ?? CLI_SYNC_LOCK_WAIT_MS);
+    if (result.paused)
+        return `bundle sync: paused until ${result.pausedUntil}; nothing pushed`;
     if (result.ok) {
         return `bundle sync: ran post-change sync (remote: ${sync.remote})`;
     }
     return `bundle sync: could not push bundle changes (${result.error})`;
 }
+function bundleHasRemote(agentRoot, remote) {
+    try {
+        return (0, child_process_1.execFileSync)("git", ["remote"], { cwd: agentRoot, stdio: "pipe" }).toString().split("\n").map((line) => line.trim()).includes(remote);
+    }
+    catch {
+        /* v8 ignore next -- syncNow just ran git in this bundle; this only words the success line @preserve */
+        return false;
+    }
+}
+/** `ouro sync`: one fetch, merge and push, reported as it happened. Exits 1 unless the bundle synced. */
+async function executeSync(agent, deps) {
+    const sync = readAgentSyncConfigForCliMutation(agent, deps);
+    if (!sync.enabled)
+        return returnCliFailure(deps, `sync is off for ${agent}: agent.json has no "sync": { "enabled": true }`);
+    const agentRoot = providerCliAgentRoot({ agent }, deps);
+    const result = await (0, sync_1.syncNow)(agentRoot, sync, agent, deps.syncLockWaitMs ?? CLI_SYNC_LOCK_WAIT_MS);
+    if (result.paused)
+        return returnCliFailure(deps, `sync paused until ${result.pausedUntil}`);
+    if (result.busy) {
+        return returnCliFailure(deps, `sync busy: another sync holds the lock${result.holderPid == null ? "" : ` (pid ${result.holderPid})`}`);
+    }
+    if (!result.ok)
+        return returnCliFailure(deps, `sync failed for ${agent}: ${result.error}`);
+    const message = bundleHasRemote(agentRoot, sync.remote)
+        ? `synced ${agent}: up to date with ${sync.remote}/${sync.branch}`
+        : `synced ${agent}: committed locally; no remote "${sync.remote}"`;
+    deps.writeStdout(message);
+    return message;
+}
 function writeAgentVaultConfig(agentName, configPath, config, vault) {
     const nextConfig = {
         ...config,
@@ -1907,7 +1953,7 @@ async function executeVaultCreate(command, deps) {
     /* v8 ignore next -- defensive: success path assigns store before continuing @preserve */
     if (!store)
         throw new Error(`vault create failed for ${command.agent}: local unlock material was not saved`);
-    const syncSummary = pushAgentBundleAfterCliMutation(command.agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(command.agent, deps);
     const fallbackLines = [
         `vault created for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
@@ -1983,7 +2029,7 @@ async function executeVaultReplace(command, deps) {
         throw new Error(`vault replace failed for ${command.agent}: no vault repair result`);
     if (!repair.ok)
         return repair.message;
-    const syncSummary = pushAgentBundleAfterCliMutation(command.agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(command.agent, deps);
     const fallbackLines = [
         `vault replaced for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
@@ -2095,7 +2141,7 @@ async function executeVaultRecover(command, deps) {
         progress.end();
     }
     const providerList = [...importedProviders].sort();
-    const syncSummary = pushAgentBundleAfterCliMutation(command.agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(command.agent, deps);
     const fallbackLines = [
         `vault recovered for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
@@ -2269,13 +2315,13 @@ function currentMachineId(deps) {
         now: () => providerCliNow(deps),
     }).machineId;
 }
-function executeAgentMove(command, deps) {
+async function executeAgentMove(command, deps) {
     const identity = (0, machine_identity_1.loadOrCreateMachineIdentity)({ homeDir: providerCliHomeDir(deps), now: () => providerCliNow(deps) });
     /* v8 ignore next -- production default: uses real bundles root @preserve */
     const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
     const discover = () => (0, agent_discovery_1.listAllBundleAgents)({ bundlesRoot, machineId: identity.machineId });
     const fallbackBefore = new Set(discover().filter((row) => row.homeState === "fallback").map((row) => row.name));
-    const result = (0, agent_home_1.moveAgentHomeHere)({
+    const result = await (0, agent_home_1.moveAgentHomeHere)({
         agent: command.agent,
         machineId: identity.machineId,
         machineName: (0, agent_home_1.machineDisplayName)(os.hostname(), identity.machineId),
@@ -3682,7 +3728,7 @@ async function executeConnectTeams(agent, deps) {
     finally {
         progress.end();
     }
-    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(agent, deps);
     return writeCapabilityOutcome(deps, {
         subtitle: `${agent}'s Teams sense is configured.`,
         summary: `Teams is ready for ${agent}.`,
@@ -3910,7 +3956,7 @@ async function executeConnectBlueBubbles(agent, deps) {
         progress.end();
         throw error;
     }
-    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(agent, deps);
     return writeCapabilityOutcome(deps, {
         subtitle: `${agent}'s local bridge is attached.`,
         summary: `BlueBubbles is attached on this machine for ${agent}.`,
@@ -4256,7 +4302,7 @@ async function ensureAgentMailroom(agent, input, deps, progressLabel) {
     /* v8 ignore next -- defensive: successful setup always stores before leaving the guarded block. @preserve */
     if (!stored)
         throw new Error("Mailroom setup did not store runtime credentials");
-    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(agent, deps);
     return { mailboxAddress, sourceAlias, mode, registryPath, storePath, hostedControlUrl, blobStoreLabel, stored, syncSummary };
 }
 async function executeConnectMail(agent, deps, input = {}) {
@@ -5154,7 +5200,7 @@ async function executeConnectVoice(agent, deps) {
 async function executeConnectA2A(agent, deps, bind = {}) {
     const { defaultA2APort } = await Promise.resolve().then(() => __importStar(require("../../a2a/config")));
     enableAgentSense(agent, "a2a", deps);
-    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(agent, deps);
     // Bind address, port and advertised URL are per machine (D-038): a tailnet IP on one
     // host means nothing on another, so they live in this machine's runtime config.
     const a2a = {
@@ -5221,7 +5267,7 @@ async function executeConnectTelegram(agent, deps) {
     finally {
         progress.end();
     }
-    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+    const syncSummary = await pushAgentBundleAfterCliMutation(agent, deps);
     return writeCapabilityOutcome(deps, {
         subtitle: `${agent}'s private Telegram sense is configured.`,
         summary: `Telegram is ready for ${agent}.`,
@@ -5248,7 +5294,7 @@ async function executeConnectTelegram(agent, deps) {
 async function executeConnectWorkbench(agent, deps) {
     const { workbenchMcpCommand, workbenchHasStaleBundleEntry } = readConnectBaySenseFlags(agent, deps);
     const changed = removeWorkbenchMcpRegistration(agent, deps);
-    const syncSummary = changed ? pushAgentBundleAfterCliMutation(agent, deps) : "";
+    const syncSummary = changed ? await pushAgentBundleAfterCliMutation(agent, deps) : "";
     const executablePath = findInstalledWorkbenchMcp(deps, workbenchMcpCommand);
     if (!executablePath) {
         throw new Error([
@@ -5404,8 +5450,8 @@ function writeAgentProviderBinding(input) {
         meta: { agent: input.agent, lane: input.lane, provider: input.provider, model: input.model, configPath },
     });
 }
-function appendBundleSyncSummary(message, agent, deps) {
-    const syncSummary = pushAgentBundleAfterCliMutation(agent, deps);
+async function appendBundleSyncSummary(message, agent, deps) {
+    const syncSummary = await pushAgentBundleAfterCliMutation(agent, deps);
     return syncSummary ? [message, syncSummary].join("\n") : message;
 }
 async function executeProviderUse(command, deps, options = {}) {
@@ -5445,7 +5491,7 @@ async function executeProviderUse(command, deps, options = {}) {
                 model: command.model,
                 deps,
             });
-            const message = appendBundleSyncSummary(`forced ${command.agent} ${command.lane} to ${command.provider} / ${command.model}: failed (${credential.error})`, command.agent, deps);
+            const message = await appendBundleSyncSummary(`forced ${command.agent} ${command.lane} to ${command.provider} / ${command.model}: failed (${credential.error})`, command.agent, deps);
             return writeMessage(message);
         }
         progress?.completePhase(`reading ${command.provider} credentials`, "found");
@@ -5472,7 +5518,7 @@ async function executeProviderUse(command, deps, options = {}) {
             model: command.model,
             deps,
         });
-        const message = appendBundleSyncSummary(`${command.force ? "forced " : ""}${command.agent} ${command.lane} ${command.provider} / ${command.model}: ${status}`, command.agent, deps);
+        const message = await appendBundleSyncSummary(`${command.force ? "forced " : ""}${command.agent} ${command.lane} ${command.provider} / ${command.model}: ${status}`, command.agent, deps);
         (0, runtime_1.emitNervesEvent)({
             component: "daemon",
             event: "daemon.provider_use_completed",
@@ -6003,7 +6049,7 @@ async function executeLegacyConfigModel(command, deps) {
         },
     };
     fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
-    const message = appendBundleSyncSummary(`deprecated: updated ${command.agent} model in agent.json on ${lane}/${binding.provider}: ${binding.model} -> ${command.modelName}\nUse \`ouro use --agent ${command.agent} --lane ${lane} --provider ${binding.provider} --model ${command.modelName}\` next time.`, command.agent, deps);
+    const message = await appendBundleSyncSummary(`deprecated: updated ${command.agent} model in agent.json on ${lane}/${binding.provider}: ${binding.model} -> ${command.modelName}\nUse \`ouro use --agent ${command.agent} --lane ${lane} --provider ${binding.provider} --model ${command.modelName}\` next time.`, command.agent, deps);
     return writeMessage(message);
 }
 // ── System setup ──
@@ -6647,6 +6693,12 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "nerves-review") {
         return executeNervesReviewCommand(command, deps);
     }
+    // Pure: no daemon, no network, no bundle. The cutover runs it in a container with --network none.
+    if (command.kind === "sanctuary.git-exclude") {
+        const text = (0, sanctuary_bundle_migration_1.sanctuaryGitExcludeText)();
+        deps.writeStdout(text);
+        return text;
+    }
     if (args.length === 0) {
         const discovered = await Promise.resolve(deps.listDiscoveredAgents ? deps.listDiscoveredAgents() : (0, cli_defaults_1.defaultListDiscoveredAgents)());
         /* v8 ignore start -- the interactive home shell is exercised extensively in daemon-cli tests; V8 miscounts this orchestrator because it chains through recursive command handoffs and early chat health exits @preserve */
@@ -7146,6 +7198,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             if (syncProbeResult.findings.length > 0) {
                 writeSyncProbeSummary(deps, syncProbeResult.findings);
             }
+            if (syncProbeResult.statuses && syncProbeResult.statuses.length > 0) {
+                writeSyncProbeStatuses(deps, syncProbeResult.statuses);
+            }
         }
         catch (probeError) {
             const message = probeError instanceof Error ? probeError.message : String(probeError);
@@ -9081,6 +9136,10 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         }
         return output;
     }
+    // ── sync: fetch, merge and push one bundle now ──
+    if (command.kind === "sync") {
+        return executeSync(command.agent, deps);
+    }
     // ── clone: clone an agent bundle from a git remote ──
     if (command.kind === "clone") {
         (0, runtime_1.emitNervesEvent)({
@@ -9149,7 +9208,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         }
         // 8. Output success message
         (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_complete", message: "clone complete", meta: { agentName, targetPath } });
-        const syncSummary = syncEnabled ? pushAgentBundleAfterCliMutation(agentName, deps) : null;
+        const syncSummary = syncEnabled ? await pushAgentBundleAfterCliMutation(agentName, deps) : null;
         const syncMsg = syncEnabled ? "\nsync enabled (remote: origin)" : "\nwarning: no agent.json found — this may not be a valid agent bundle";
         const syncPushMsg = syncSummary ? `\n${syncSummary}` : "";
         deps.writeStdout(`cloned ${agentName} to ${targetPath}${syncMsg}${syncPushMsg}`);

package/dist/heart/daemon/cli-help.js

@@ -80,6 +80,12 @@ exports.COMMAND_REGISTRY = {
         usage: "ouro clone <remote> [--agent <name>]",
         example: "ouro clone https://github.com/user/myagent.ouro.git",
     },
+    sync: {
+        category: "Lifecycle",
+        description: "Sync an agent bundle with its git remote now: fetch, merge, push",
+        usage: "ouro sync [--agent <name>]",
+        example: "ouro sync --agent slugger",
+    },
     doctor: {
         category: "Lifecycle",
         description: "Run diagnostic checks on the ouro installation",
@@ -211,6 +217,12 @@ exports.COMMAND_REGISTRY = {
         example: "ouro work sentinel --agent my-agent --format json",
         subcommands: ["card", "gauntlet", "sentinel"],
     },
+    sanctuary: {
+        category: "Internal",
+        description: "Print the git exclude list for the Butler's bundle, one entry per line. Starts nothing and reads nothing.",
+        usage: "ouro sanctuary git-exclude --print",
+        example: "ouro sanctuary git-exclude --print",
+    },
     "nerves-review": {
         category: "Internal",
         description: `Read-only review of recent nerves events from one agent log stream (default: ${core_1.DEFAULT_NERVES_PROCESS})`,

package/dist/heart/daemon/cli-parse.js

@@ -327,6 +327,7 @@ function usage() {
         "  ouro rollback [<version>]",
         "  ouro versions",
         "  ouro clone <remote> [--agent <name>]",
+        "  ouro sync [--agent <name>]",
         "  ouro doctor",
     ].join("\n");
 }
@@ -2163,6 +2164,12 @@ function parseCloneCommand(args) {
         ? { kind: "clone", remote, agent }
         : { kind: "clone", remote };
 }
+function parseSyncCommand(args) {
+    const { agent, rest } = extractAgentFlag(args);
+    if (rest.length > 0)
+        throw new Error("Usage: ouro sync [--agent <name>]");
+    return agent ? { kind: "sync", agent } : { kind: "sync" };
+}
 function parseMcpServeCommand(args) {
     let agent;
     let friendId;
@@ -3281,6 +3288,11 @@ function parseOuroCommand(args) {
         return parsePokeCommand(args.slice(1));
     if (head === "nerves-review")
         return parseNervesReviewCommand(args.slice(1));
+    if (head === "sanctuary") {
+        if (args.length === 3 && args[1] === "git-exclude" && args[2] === "--print")
+            return { kind: "sanctuary.git-exclude" };
+        throw new Error("Usage: ouro sanctuary git-exclude --print");
+    }
     if (head === "link")
         return parseLinkCommand(args.slice(1));
     if (head === "acp-serve")
@@ -3293,6 +3305,8 @@ function parseOuroCommand(args) {
         return parsePluginCommand(args.slice(1));
     if (head === "clone")
         return parseCloneCommand(args.slice(1));
+    if (head === "sync")
+        return parseSyncCommand(args.slice(1));
     if (head === "doctor") {
         const tail = args.slice(1);
         const json = tail.includes("--json");

package/dist/heart/daemon/container-spec-auditor-main.js

@@ -67,7 +67,22 @@ function parseSingleInspect(raw) {
         return null;
     }
 }
-function runContainerSpecAuditorCli(args, deps = {}) {
+function splitSyncFlag(args) {
+    const index = args.indexOf("--sync-enabled");
+    if (index === -1)
+        return { args, syncEnabled: false };
+    const value = args[index + 1];
+    if (value !== "true" && value !== "false")
+        return null;
+    const rest = [...args.slice(0, index), ...args.slice(index + 2)];
+    if (rest.includes("--sync-enabled"))
+        return null;
+    return { args: rest, syncEnabled: value === "true" };
+}
+function runContainerSpecAuditorCli(rawArgs, deps = {}) {
+    const sync = splitSyncFlag(rawArgs);
+    const args = sync?.args ?? [];
+    const syncEnabled = sync?.syncEnabled === true;
     const readFile = deps.readFile ?? ((filePath) => fs.readFileSync(filePath));
     const readText = (filePath) => decodeUtf8(readFile(filePath));
     const write = deps.write ?? ((text) => process.stdout.write(text));
@@ -78,14 +93,14 @@ function runContainerSpecAuditorCli(args, deps = {}) {
     const sourceContract = sourceCandidate?.["--mount-contract"];
     const sourceEffective = sourceContract === "legacy-alpha742" ? sourceCandidate : null;
     const selectedEffective = effective ?? sourceEffective;
-    if (!staged && !persistent && !selectedEffective) {
-        write(JSON.stringify({ ok: false, error: "usage: all modes require --mount-contract canonical-pre-gateway|canonical-gateway; staged --template <path> --runtime-policy <path> --expected-image <id>; persistent --persistent-template <path> --runtime-policy <path> --expected-image-reference <tag>; effective --inspect <path> --image-inspect <path> --expected-image <id> --expected-image-reference <tag> --expected-icon <url>; source compatibility effective --inspect <path> --image-inspect <path> --expected-image <id> --mount-contract legacy-alpha742" }) + "\n");
+    if (!sync || (!staged && !persistent && !selectedEffective)) {
+        write(JSON.stringify({ ok: false, error: "usage: all modes require --mount-contract canonical-pre-gateway|canonical-gateway and accept --sync-enabled true|false; staged --template <path> --runtime-policy <path> --expected-image <id>; persistent --persistent-template <path> --runtime-policy <path> --expected-image-reference <tag>; effective --inspect <path> --image-inspect <path> --expected-image <id> --expected-image-reference <tag> --expected-icon <url>; source compatibility effective --inspect <path> --image-inspect <path> --expected-image <id> --mount-contract legacy-alpha742" }) + "\n");
         (0, runtime_1.emitNervesEvent)({
             level: "error",
             component: "daemon",
             event: "daemon.container_spec_auditor_cli_error",
             message: "container spec auditor arguments were invalid",
-            meta: { argumentCount: args.length },
+            meta: { argumentCount: rawArgs.length },
         });
         return 2;
     }
@@ -130,6 +145,7 @@ function runContainerSpecAuditorCli(args, deps = {}) {
             expectedImageReference: selectedEffective["--expected-image-reference"],
             expectedIcon: selectedEffective["--expected-icon"],
             mountContract: selectedEffective["--mount-contract"],
+            syncEnabled,
         });
         if (imageInspect.Id !== selectedEffective["--expected-image"]) {
             result.ok = false;
@@ -159,8 +175,8 @@ function runContainerSpecAuditorCli(args, deps = {}) {
         return 2;
     }
     const result = persistent
-        ? (0, container_spec_auditor_1.auditSanctuaryPersistentTemplate)({ templateXml, runtimePolicyText, expectedImageReference: persistent["--expected-image-reference"], mountContract })
-        : (0, container_spec_auditor_1.auditSanctuaryStagedFiles)({ templateXml, runtimePolicyText, expectedImage: staged["--expected-image"], mountContract });
+        ? (0, container_spec_auditor_1.auditSanctuaryPersistentTemplate)({ templateXml, runtimePolicyText, expectedImageReference: persistent["--expected-image-reference"], mountContract, syncEnabled })
+        : (0, container_spec_auditor_1.auditSanctuaryStagedFiles)({ templateXml, runtimePolicyText, expectedImage: staged["--expected-image"], mountContract, syncEnabled });
     write(JSON.stringify(result) + "\n");
     return result.ok ? 0 : 1;
 }

package/dist/heart/daemon/container-spec-auditor.js

@@ -15,6 +15,8 @@ const EXPECTED_BINDS = [
     "/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche:/home/ouro/AgentBundles/sanctuary.ouro/psyche:ro",
     // Operator-set grants, root-owned on the host and read-only inside the Butler (the Butler honours a grant only from here).
     "/mnt/user/appdata/ouro-butler/trust/sanctuary:/etc/ouro/trust/sanctuary:ro",
+    // The bundle sync deploy key, root-owned on the host and read-only inside the Butler. The key can push to the owner's repo.
+    "/mnt/user/appdata/ouro-butler/sync:/run/ouro-sync:ro",
 ];
 const EXPECTED_MOUNTS = [
     ["/mnt/user/appdata/ouro-butler/runtime/.ouro-cli", "/home/ouro/.ouro-cli", true, "rprivate"],
@@ -23,11 +25,25 @@ const EXPECTED_MOUNTS = [
     ["/run/ouro-authority", "/run/ouro-authority", false, "rprivate"],
     ["/mnt/user/appdata/ouro-butler/agent/sanctuary.ouro/psyche", "/home/ouro/AgentBundles/sanctuary.ouro/psyche", false, "rprivate"],
     ["/mnt/user/appdata/ouro-butler/trust/sanctuary", "/etc/ouro/trust/sanctuary", false, "rprivate"],
+    ["/mnt/user/appdata/ouro-butler/sync", "/run/ouro-sync", false, "rprivate"],
 ];
 const PSYCHE_TARGET = "/home/ouro/AgentBundles/sanctuary.ouro/psyche";
 /** The current resident shape: the canonical-gateway set without the separate read-only psyche mount. */
 const GATEWAY_BINDS_WITHOUT_PSYCHE = EXPECTED_BINDS.filter((bind) => !bind.includes(`:${PSYCHE_TARGET}:`));
 const GATEWAY_MOUNTS_WITHOUT_PSYCHE = EXPECTED_MOUNTS.filter((mount) => mount[1] !== PSYCHE_TARGET);
+const SYNC_TARGET = "/run/ouro-sync";
+/**
+ * The canonical-gateway shapes. With sync on, the key mount is required. With sync off (the live Butler until the
+ * cutover, and a rollback to a release without the mount) each shape is accepted with or without it.
+ */
+function gatewayBinds(syncEnabled) {
+    const shapes = [EXPECTED_BINDS, GATEWAY_BINDS_WITHOUT_PSYCHE];
+    return syncEnabled ? shapes : [...shapes, ...shapes.map((binds) => binds.filter((bind) => !bind.includes(`:${SYNC_TARGET}:`)))];
+}
+function gatewayMounts(syncEnabled) {
+    const shapes = [EXPECTED_MOUNTS, GATEWAY_MOUNTS_WITHOUT_PSYCHE];
+    return syncEnabled ? shapes : [...shapes, ...shapes.map((mounts) => mounts.filter((mount) => mount[1] !== SYNC_TARGET))];
+}
 const PRE_GATEWAY_BINDS = EXPECTED_BINDS.slice(0, 3);
 const PRE_GATEWAY_MOUNTS = EXPECTED_MOUNTS.slice(0, 3);
 const LEGACY_ALPHA742_IMAGE = "sha256:681449ad47a2621705cd339b481e6339236b31dc65e195b1cf5025d0f2191d7d";
@@ -71,7 +87,7 @@ function auditSanctuaryContainerSpec(value, options) {
             violations.push("unsupported mount contract");
         if (mountContract === "legacy-alpha742" && options.expectedImage !== LEGACY_ALPHA742_IMAGE)
             violations.push("legacy mount exception requires the pinned alpha.742 image ID");
-        const acceptedMounts = mountContract === "legacy-alpha742" ? [LEGACY_ALPHA742_MOUNTS] : mountContract === "canonical-pre-gateway" ? [PRE_GATEWAY_MOUNTS] : [EXPECTED_MOUNTS, GATEWAY_MOUNTS_WITHOUT_PSYCHE];
+        const acceptedMounts = mountContract === "legacy-alpha742" ? [LEGACY_ALPHA742_MOUNTS] : mountContract === "canonical-pre-gateway" ? [PRE_GATEWAY_MOUNTS] : gatewayMounts(options.syncEnabled === true);
         const expectedArgs = mountContract !== "legacy-alpha742" ? PACKAGE_DAEMON_ARGS : LEGACY_DAEMON_ARGS;
         const expectedEntrypoint = mountContract !== "legacy-alpha742" ? PACKAGE_ENTRYPOINT : LEGACY_ENTRYPOINT;
         if (root.Image !== options.expectedImage)
@@ -180,7 +196,7 @@ function auditTemplate(input, expectedRepository, repositoryIsValid, repositoryV
     const violations = [];
     if (input.mountContract !== "canonical-pre-gateway" && input.mountContract !== "canonical-gateway")
         violations.push("unsupported template mount contract");
-    const acceptedBinds = input.mountContract === "canonical-pre-gateway" ? [PRE_GATEWAY_BINDS] : [EXPECTED_BINDS, GATEWAY_BINDS_WITHOUT_PSYCHE];
+    const acceptedBinds = input.mountContract === "canonical-pre-gateway" ? [PRE_GATEWAY_BINDS] : gatewayBinds(input.syncEnabled === true);
     const template = parseDockerManTemplateXml(input.templateXml);
     if (!template)
         violations.push("canonical DockerMan XML structure is invalid");

package/dist/heart/daemon/daemon-entry.js

@@ -84,6 +84,8 @@ const sanctuary_scheduler_liveness_1 = require("./sanctuary-scheduler-liveness")
 const sanctuary_scheduler_origin_1 = require("./sanctuary-scheduler-origin");
 const telegram_1 = require("../../senses/telegram");
 const sync_health_1 = require("../sync-health");
+const sync_1 = require("../sync");
+const sync_lock_1 = require("../sync-lock");
 function parseSocketPath(argv) {
     const socketIndex = argv.indexOf("--socket");
     if (socketIndex >= 0) {
@@ -701,6 +703,23 @@ void (0, daemon_bootstrap_startup_1.startDaemonAfterContainerCredentialBootstrap
     supercronicSupervisor?.start();
     const providerPreload = Promise.resolve();
     const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();
+    // The daemon is PID 1 on every container boot, so a lock an earlier boot left looks like ours.
+    // Clearing a lock never stops the boot; an unreadable one is judged again by the next sync.
+    try {
+        for (const row of (0, agent_discovery_1.listBundleSyncRows)({ bundlesRoot })) {
+            if (!row.enabled || !row.gitInitialized)
+                continue;
+            try {
+                (0, sync_lock_1.clearOwnStaleSyncLock)(path.join(bundlesRoot, `${row.agent}.ouro`));
+            }
+            catch {
+                // Next bundle.
+            }
+        }
+    }
+    catch {
+        // The bundle list could not be read.
+    }
     const ouroPath = supercronicSupervisor
         ? "/usr/local/bin/node /opt/ouro/dist/heart/daemon/ouro-entry.js"
         : (0, os_cron_deps_1.resolveOuroBinaryPath)();
@@ -964,6 +983,7 @@ process.on("SIGINT", () => {
     // daemon kept dying. Tombstones are informational — having a "sigint"
     // tombstone is strictly better than silence.
     _tombstoneWritten = true;
+    (0, sync_1.abortInFlightSync)();
     (0, daemon_tombstone_1.writeDaemonTombstone)("sigint", new Error("daemon received SIGINT"));
     const forcedExit = setTimeout(() => process.exit(1), 12_000);
     forcedExit.unref();
@@ -977,6 +997,8 @@ process.on("SIGINT", () => {
 });
 process.on("SIGTERM", () => {
     _tombstoneWritten = true;
+    // Kill sync's git process groups and release the bundle locks before anything slower.
+    (0, sync_1.abortInFlightSync)();
     (0, daemon_tombstone_1.writeDaemonTombstone)("sigterm", new Error("daemon received SIGTERM"));
     const forcedExit = setTimeout(() => process.exit(1), 12_000);
     forcedExit.unref();

package/dist/heart/daemon/sanctuary-acceptance-harness.js

@@ -60,7 +60,7 @@ function exactSanctuaryContainmentProfileBoundaries(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
     const boundaries = value;
-    const versions = { "sanctuary-owner": 17, "sanctuary-household": 5, "sanctuary-event": 4 };
+    const versions = { "sanctuary-owner": 18, "sanctuary-household": 5, "sanctuary-event": 4 };
     if (!(0, node_util_1.isDeepStrictEqual)(Object.keys(boundaries).sort(), Object.keys(versions).sort()))
         return false;
     const packageRoot = path.resolve(__dirname, "../../../deploy/unraid/sanctuary.ouro");

package/dist/heart/daemon/sanctuary-bundle-migration.js

@@ -33,7 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = exports.SANCTUARY_STARTER_PSYCHE_FILES = exports.SANCTUARY_PACKAGE_MANAGED_FILES = void 0;
+exports.SANCTUARY_GIT_EXCLUDES = exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = exports.SANCTUARY_STARTER_PSYCHE_FILES = exports.SANCTUARY_PACKAGE_MANAGED_FILES = void 0;
+exports.sanctuaryGitExcludeText = sanctuaryGitExcludeText;
+exports.bundleSyncEnabled = bundleSyncEnabled;
+exports.writeSanctuaryGitExclude = writeSanctuaryGitExclude;
 exports.inspectSanctuaryDirectoryFromBase = inspectSanctuaryDirectoryFromBase;
 exports.sanctuaryDirectoriesShareIdentity = sanctuaryDirectoriesShareIdentity;
 exports.inspectSanctuaryPackageManagedBundle = inspectSanctuaryPackageManagedBundle;
@@ -45,6 +48,7 @@ exports.commitSanctuaryPackageManagedBundle = commitSanctuaryPackageManagedBundl
 exports.migrateSanctuaryPackageManagedBundle = migrateSanctuaryPackageManagedBundle;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const runtime_1 = require("../../nerves/runtime");
 const house_names_1 = require("../../mind/house-names");
@@ -64,6 +68,98 @@ const PSYCHE_SEED_STAGE_NAME = /^\.psyche-seed\.[A-Za-z0-9]{6}$/u;
 const STARTER_PSYCHE_NAMES = new Set(exports.SANCTUARY_STARTER_PSYCHE_FILES.map((relative) => path.basename(relative)));
 exports.SANCTUARY_BUNDLE_ROLLBACK_FILE = ".sanctuary-package-managed-rollback.json";
 const SANCTUARY_BUNDLE_COMMITTING_FILE = `${exports.SANCTUARY_BUNDLE_ROLLBACK_FILE}.committing`;
+/**
+ * What sync never commits from the Butler's bundle. The first block is the hourly host backup's own list, copied from
+ * bundle-backup/repo.git/info/exclude on 2026-11-06. Then any MCP credential file, the files each release installs, and
+ * the release's own bookkeeping, then the transient temp and lock files written inside the bundle. The cutover writes this list with `ouro sanctuary git-exclude --print`, and every boot
+ * writes it again.
+ */
+exports.SANCTUARY_GIT_EXCLUDES = [
+    "**/credentials.json",
+    "mcp/media-credentials.json",
+    "books/hey/.config/",
+    "**/*.key",
+    "**/*.pem",
+    "**/deploy_key*",
+    "**/id_rsa*",
+    "**/id_ed25519*",
+    "**/id_ecdsa*",
+    "**/.env",
+    "state/",
+    "inbox/",
+    "arc/flight-recorder/",
+    "arc/obligations/",
+    "arc/packets/",
+    "books/bin/",
+    "books/vendor/",
+    "books/work/",
+    "books/fonts/",
+    "mcp/*.pre-*",
+    "books/hey/",
+    "**/__pycache__/",
+    "mcp/*credentials*",
+    ...exports.SANCTUARY_PACKAGE_MANAGED_FILES,
+    "bundle-meta.json",
+    `${exports.SANCTUARY_BUNDLE_ROLLBACK_FILE}*`,
+    `${PSYCHE_SEED_STAGE_PREFIX}*`,
+    // The upgrade's release marker and its staged copy, planted in psyche/ for the length of a gated ship.
+    "psyche/.release-marker*",
+    // Transient files the runtime and the replay gate write inside the bundle: atomic-write temps and lock files.
+    "*.tmp",
+    "*.tmp-*",
+    "*.tmp.*",
+    "*.lock",
+    "*.lock.reclaim",
+    "*.turn.lock-*",
+    ".locks/",
+];
+/** The exclude file's content: one entry per line. */
+function sanctuaryGitExcludeText() {
+    return `${exports.SANCTUARY_GIT_EXCLUDES.join("\n")}\n`;
+}
+/** Whether the bundle's agent.json turns sync on. An unreadable agent.json reads as off. */
+function bundleSyncEnabled(agentRoot) {
+    try {
+        const sync = readObject(path.join(agentRoot, "agent.json")).sync;
+        return sync?.enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write the bundle's `.git/info/exclude`. A bundle with sync on and no repository yet (a fresh install) gets
+ * `git init -b main` first; sync makes the first commit on the first turn. A bundle with sync off and no
+ * repository is left alone. A tracked .gitignore is the owner's and is never touched.
+ */
+function writeSanctuaryGitExclude(agentRoot) {
+    const gitDir = path.join(agentRoot, ".git");
+    let initialized = false;
+    if (!fs.existsSync(gitDir)) {
+        if (!bundleSyncEnabled(agentRoot))
+            return { initialized: false, written: false };
+        const run = (0, node_child_process_1.spawnSync)("git", ["init", "-q", "-b", "main"], { cwd: agentRoot, env: { ...process.env, LC_ALL: "C", LANG: "C" }, encoding: "utf8" });
+        if (run.status !== 0)
+            throw new Error(`git init failed: ${run.error ? run.error.message : run.stderr.trim()}`);
+        initialized = true;
+    }
+    const excludePath = path.join(gitDir, "info", "exclude");
+    const text = sanctuaryGitExcludeText();
+    let current = null;
+    try {
+        current = fs.readFileSync(excludePath, "utf8");
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    if (current === text)
+        return { initialized, written: false };
+    fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+    writeAtomic(excludePath, text, 0o644);
+    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.sanctuary_git_exclude_written", message: "wrote the Sanctuary bundle's git exclude", meta: { initialized, entries: exports.SANCTUARY_GIT_EXCLUDES.length } });
+    return { initialized, written: true };
+}
 const BUNDLE_META_VERSION_FIELDS = ["runtimeVersion", "bundleSchemaVersion", "lastUpdated"];
 class SanctuaryInspectionFault extends Error {
     code;