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

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-authority-root-lifecycle.js

@@ -36,6 +36,7 @@ var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SanctuaryAuthorityRootLifecycle = exports.SANCTUARY_UPGRADE_STEPS = exports.SANCTUARY_KEEPER_BOOT_LINES = void 0;
 exports.predecessorExpectsPsycheMount = predecessorExpectsPsycheMount;
+exports.predecessorHasBundleSync = predecessorHasBundleSync;
 exports.recordSanctuaryRootLifecycleFailure = recordSanctuaryRootLifecycleFailure;
 exports.runSanctuaryAuthorityRootCli = runSanctuaryAuthorityRootCli;
 const node_child_process_1 = require("node:child_process");
@@ -57,6 +58,8 @@ const OFFSET = `${BUNDLE}/state/senses/telegram/offset.json`;
 const SOCKET = "/run/ouro-authority";
 // Operator-set grants, root-owned on the host and mounted read-only into the Butler at /etc/ouro/trust/sanctuary.
 const TRUST = "/mnt/user/appdata/ouro-butler/trust/sanctuary";
+// The bundle sync deploy key's host folder, mounted read-only where the sync wrapper reads it (from alpha.991).
+const SYNC = "/mnt/user/appdata/ouro-butler/sync";
 const STAGING = "/var/lib/ouro-authority/staging";
 const CGROUP = "/sys/fs/cgroup/ouro-authority";
 const BOOT = "/boot/config/custom/ouro-authority/start.sh";
@@ -855,7 +858,7 @@ class SanctuaryAuthorityRootLifecycle {
         const steps = {
             stop: () => this.#halt(),
             switch: async () => { await this.#halt(); this.#switchPackage(journal); },
-            resident: () => this.#recreateResident(journal.to.imageReference, journal.to.imageId, { psycheMount: false }),
+            resident: () => this.#recreateResident(journal.to.imageReference, journal.to.imageId, { psycheMount: false, syncMount: true }),
             migrate: () => target().#bundle(["--operation", "migrate", "--rollback-image-id", journal.from.imageId, "--target-image-id", journal.to.imageId]),
             start: () => target().#startUpgraded(),
         };
@@ -918,7 +921,7 @@ class SanctuaryAuthorityRootLifecycle {
         predecessor.#publishBoot();
         if (this.#containers().find((container) => container.Name === "/ouro-butler")?.Image !== journal.from.imageId) {
             // A predecessor up to alpha.978 expects its psyche read-only over the bundle; alpha.979 and later own a writable one.
-            predecessor.#recreateResident(journal.from.imageReference, journal.from.imageId, { psycheMount: predecessorExpectsPsycheMount(journal.from.imageReference) });
+            predecessor.#recreateResident(journal.from.imageReference, journal.from.imageId, { psycheMount: predecessorExpectsPsycheMount(journal.from.imageReference), syncMount: predecessorHasBundleSync(journal.from.imageReference) });
         }
         await predecessor.#startUpgraded(PREDECESSOR_READY_TIMEOUT_MS);
         this.#remove(UPGRADE);
@@ -1027,8 +1030,12 @@ class SanctuaryAuthorityRootLifecycle {
     #publishBoot() {
         this.#write(BOOT, fs.readFileSync(this.#p(`${ROOT}/package/deploy/unraid/sanctuary-authority-service.sh`), "utf8"));
     }
-    /** `psycheMount` adds the read-only psyche mount that releases up to alpha.978 expect; only a rollback to such a release passes true. */
-    #recreateResident(reference, imageId, { psycheMount }) {
+    /**
+     * `psycheMount` adds the read-only psyche mount that releases up to alpha.978 expect; only a rollback to such a release
+     * passes true. `syncMount` adds the read-only bundle sync key mount that releases from alpha.991 carry; an older
+     * release's audit refuses it.
+     */
+    #recreateResident(reference, imageId, { psycheMount, syncMount }) {
         if (this.#containers().some((container) => container.Name === "/ouro-butler"))
             this.#docker(["rm", "-f", "ouro-butler"]);
         this.#docker(["create", "--name", "ouro-butler", "--network", "host", "--restart", "unless-stopped", "--user", "10001:10001",
@@ -1036,7 +1043,8 @@ class SanctuaryAuthorityRootLifecycle {
             "-v", `${RUNTIME}:/home/ouro/.ouro-cli:rw`, "-v", `${BUNDLE}:/home/ouro/AgentBundles/sanctuary.ouro:rw`,
             "-v", `${EVENTS}:/run/ouro-events:ro`, "-v", `${SOCKET}:${SOCKET}:ro`,
             ...(psycheMount ? ["-v", `${BUNDLE}/psyche:/home/ouro/AgentBundles/sanctuary.ouro/psyche:ro`] : []),
-            "-v", `${TRUST}:/etc/ouro/trust/sanctuary:ro`, reference]);
+            "-v", `${TRUST}:/etc/ouro/trust/sanctuary:ro`,
+            ...(syncMount ? ["-v", `${SYNC}:/run/ouro-sync:ro`] : []), reference]);
         const resident = this.#containers().find((container) => container.Name === "/ouro-butler");
         if (resident?.Image !== imageId || resident.State.Running)
             throw new Error("Sanctuary resident recreation readback failed");
@@ -1260,6 +1268,14 @@ function predecessorExpectsPsycheMount(imageReference) {
     const release = /^0\.1\.0-alpha\.(\d+)$/u.exec(imageReference.slice(imageReference.lastIndexOf(":") + 1));
     return release !== null && Number(release[1]) <= 978;
 }
+/** Whether a release's image carries bundle sync (alpha.991 or later, or a release with no prerelease tag), so its resident gets the sync key mount. */
+function predecessorHasBundleSync(imageReference) {
+    const tag = imageReference.slice(imageReference.lastIndexOf(":") + 1);
+    if (/^\d+\.\d+\.\d+$/u.test(tag))
+        return true;
+    const release = /^0\.1\.0-alpha\.(\d+)$/u.exec(tag);
+    return release !== null && Number(release[1]) >= 991;
+}
 /**
  * Keep the real failure where only root can read it (D-034). Stderr stays generic
  * because a parse error can quote private bytes; the authority root is as private