@ouro.bot/cli 0.1.0-alpha.755 → 0.1.0-alpha.757

package/changelog.json

@@ -1,6 +1,19 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.757",
+      "changes": [
+        "Allow authenticated steward policy writes to use the current version when the agent omits an explicit concurrency token.",
+        "Keep private external-event turns bound to their exact leased batch, with prompt-safe lease context and deterministic disposition completeness."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.756",
+      "changes": [
+        "Recover private-runtime turns safely across container restarts and restore Sanctuary steward-policy context."
+      ]
+    },
     {
       "version": "0.1.0-alpha.755",
       "changes": [

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.755",
+  "runtimeVersion": "0.1.0-alpha.757",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-08-30T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>Mendelow Cloud Butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.755</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.757</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/mind/session-transaction.js

@@ -51,6 +51,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const runtime_1 = require("../nerves/runtime");
+const habit_lifecycle_1 = require("../heart/habits/habit-lifecycle");
 class SessionTurnBusyError extends Error {
     retryable = true;
     constructor(message = "session turn is busy") {
@@ -101,34 +102,71 @@ function openLeaseDatabase(lockPath, busyTimeoutMs = 0) {
       owner_token TEXT NOT NULL
     )
   `);
+    const columns = new Set(database.prepare(`PRAGMA table_info(session_turn_lease)`).all().map((column) => column.name));
+    if (!columns.has("boot_identity"))
+        database.exec(`ALTER TABLE session_turn_lease ADD COLUMN boot_identity TEXT`);
+    if (!columns.has("process_started_at"))
+        database.exec(`ALTER TABLE session_turn_lease ADD COLUMN process_started_at TEXT`);
     return database;
 }
-function claimLeaseRecord(lockPath, record, isProcessAlive) {
+function acquisitionRecord(options) {
+    const pid = options.pid ?? process.pid;
+    const bootIdentity = (options.getBootIdentity ?? habit_lifecycle_1.probeHabitBootIdentity)();
+    const processStartedAt = (options.getProcessStartedAt ?? habit_lifecycle_1.probeHabitProcessStartedAt)(pid);
+    if (!bootIdentity || !processStartedAt)
+        throw new SessionTransactionError("current process identity is unavailable");
+    return {
+        pid,
+        ownerId: options.ownerId ?? (0, node_crypto_1.randomUUID)(),
+        ownerToken: options.ownerToken ?? (0, node_crypto_1.randomUUID)(),
+        bootIdentity,
+        processStartedAt,
+    };
+}
+function claimLeaseRecord(lockPath, record, isProcessAlive, getProcessStartedAt) {
     const database = openLeaseDatabase(lockPath);
     try {
         return database.transaction(() => {
             const current = database.prepare(`
-        SELECT pid, owner_id, owner_token FROM session_turn_lease WHERE singleton = 1
+        SELECT pid, owner_id, owner_token, boot_identity, process_started_at FROM session_turn_lease WHERE singleton = 1
       `).get();
             if (!current) {
                 database.prepare(`
-          INSERT INTO session_turn_lease (singleton, pid, owner_id, owner_token) VALUES (1, ?, ?, ?)
-        `).run(record.pid, record.ownerId, record.ownerToken);
+          INSERT INTO session_turn_lease (singleton, pid, owner_id, owner_token, boot_identity, process_started_at) VALUES (1, ?, ?, ?, ?, ?)
+        `).run(record.pid, record.ownerId, record.ownerToken, record.bootIdentity, record.processStartedAt);
                 return { acquired: true, stale: null };
             }
             if (!Number.isSafeInteger(current.pid) || current.pid <= 0
                 || typeof current.owner_id !== "string" || current.owner_id.length === 0
-                || typeof current.owner_token !== "string" || current.owner_token.length === 0) {
+                || typeof current.owner_token !== "string" || current.owner_token.length === 0
+                || !((current.boot_identity === null && current.process_started_at === null)
+                    || (typeof current.boot_identity === "string" && current.boot_identity.length > 0
+                        && typeof current.process_started_at === "string" && current.process_started_at.length > 0))) {
                 throw new SessionTransactionError("invalid session lease record");
             }
-            const observed = { pid: current.pid, ownerId: current.owner_id, ownerToken: current.owner_token };
-            if (isProcessAlive(observed.pid))
+            const observed = {
+                pid: current.pid,
+                ownerId: current.owner_id,
+                ownerToken: current.owner_token,
+                bootIdentity: current.boot_identity,
+                processStartedAt: current.process_started_at,
+            };
+            const differentBoot = observed.bootIdentity !== null && observed.bootIdentity !== record.bootIdentity;
+            let differentProcess = false;
+            if (observed.bootIdentity !== null && !differentBoot) {
+                const liveStartedAt = getProcessStartedAt(observed.pid);
+                differentProcess = liveStartedAt !== null && liveStartedAt !== observed.processStartedAt;
+                if (liveStartedAt === observed.processStartedAt)
+                    return { acquired: false, stale: null };
+            }
+            if (!differentBoot && !differentProcess && isProcessAlive(observed.pid))
                 return { acquired: false, stale: null };
-            database.prepare(`
-        UPDATE session_turn_lease SET pid = ?, owner_id = ?, owner_token = ?
+            const changed = database.prepare(`
+        UPDATE session_turn_lease SET pid = ?, owner_id = ?, owner_token = ?, boot_identity = ?, process_started_at = ?
         WHERE singleton = 1 AND pid = ? AND owner_id = ? AND owner_token = ?
-      `).run(record.pid, record.ownerId, record.ownerToken, observed.pid, observed.ownerId, observed.ownerToken);
-            return { acquired: true, stale: observed };
+          AND boot_identity IS ? AND process_started_at IS ?
+      `).run(record.pid, record.ownerId, record.ownerToken, record.bootIdentity, record.processStartedAt, observed.pid, observed.ownerId, observed.ownerToken, observed.bootIdentity, observed.processStartedAt).changes;
+            return changed === 1 ? { acquired: true, stale: observed } : { acquired: false, stale: null };
         })();
     }
     finally {
@@ -140,7 +178,8 @@ function releaseLeaseRecord(lockPath, record) {
     try {
         return database.prepare(`
       DELETE FROM session_turn_lease WHERE singleton = 1 AND pid = ? AND owner_id = ? AND owner_token = ?
-    `).run(record.pid, record.ownerId, record.ownerToken).changes === 1;
+        AND boot_identity IS ? AND process_started_at IS ?
+    `).run(record.pid, record.ownerId, record.ownerToken, record.bootIdentity, record.processStartedAt).changes === 1;
     }
     finally {
         database.close();
@@ -180,9 +219,8 @@ async function acquireSessionTurnLease(sessionPath, options = {}) {
             return makeLease(existing);
         }
     }
-    const ownerId = options.ownerId ?? (0, node_crypto_1.randomUUID)();
-    const ownerToken = options.ownerToken ?? (0, node_crypto_1.randomUUID)();
-    const pid = options.pid ?? process.pid;
+    const record = acquisitionRecord(options);
+    const { ownerId } = record;
     const timeoutMs = options.timeoutMs ?? 5_000;
     const pollIntervalMs = options.pollIntervalMs ?? 10;
     const isProcessAlive = options.isProcessAlive ?? processAlive;
@@ -192,14 +230,14 @@ async function acquireSessionTurnLease(sessionPath, options = {}) {
     for (;;) {
         let claim = null;
         try {
-            claim = claimLeaseRecord(lockPath, { pid, ownerId, ownerToken }, isProcessAlive);
+            claim = claimLeaseRecord(lockPath, record, isProcessAlive, options.getProcessStartedAt ?? habit_lifecycle_1.probeHabitProcessStartedAt);
         }
         catch (error) {
             if (!isSqliteBusy(error))
                 throw error;
         }
         if (claim?.acquired) {
-            const held = { sessionPath: canonical, lockPath, pid, ownerId, ownerToken, depth: 1, released: false };
+            const held = { sessionPath: canonical, lockPath, ...record, depth: 1, released: false };
             heldLeases.set(canonical, held);
             (0, runtime_1.emitNervesEvent)({
                 component: "mind",
@@ -246,15 +284,13 @@ function withImmediateSessionTurnLease(sessionPath, work, options = {}) {
     const contextual = currentSessionTurnLease(canonical);
     if (contextual)
         return work(contextual);
-    const ownerId = options.ownerId ?? (0, node_crypto_1.randomUUID)();
-    const ownerToken = options.ownerToken ?? (0, node_crypto_1.randomUUID)();
-    const pid = options.pid ?? process.pid;
+    const record = acquisitionRecord(options);
     const lockPath = `${canonical}.turn.lock`;
     fs.mkdirSync(path.dirname(canonical), { recursive: true });
     const tryAcquire = () => {
         let claim;
         try {
-            claim = claimLeaseRecord(lockPath, { pid, ownerId, ownerToken }, options.isProcessAlive ?? processAlive);
+            claim = claimLeaseRecord(lockPath, record, options.isProcessAlive ?? processAlive, options.getProcessStartedAt ?? habit_lifecycle_1.probeHabitProcessStartedAt);
         }
         catch (error) {
             if (isSqliteBusy(error))
@@ -262,7 +298,7 @@ function withImmediateSessionTurnLease(sessionPath, work, options = {}) {
             throw error;
         }
         if (claim.acquired) {
-            const held = { sessionPath: canonical, lockPath, pid, ownerId, ownerToken, depth: 1, released: false };
+            const held = { sessionPath: canonical, lockPath, ...record, depth: 1, released: false };
             heldLeases.set(canonical, held);
             if (claim.stale) {
                 options.onStaleLease?.(claim.stale);

package/dist/repertoire/tools-continuity.js

@@ -204,6 +204,7 @@ exports.continuityToolDefinitions = [
                         verificationRefs,
                     },
                 });
+                ctx?.externalEventAuthority?.recordCommittedDisposition?.(turnEvent);
                 (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.external_event_disposition", message: "external event disposition recorded", meta: { agentName, eventId: record.eventId, generation: record.generation, classification, decision } });
                 return JSON.stringify(handled, null, 2);
             };

package/dist/repertoire/tools-steward-policy.js

@@ -16,12 +16,12 @@ exports.stewardPolicyToolDefinition = {
         type: "function",
         function: {
             name: "steward_policy_manage",
-            description: "Read or update the household steward's typed desired-state and routine-action policy. Updates require the current authenticated family request and exact policy version.",
+            description: "Read or update the household steward's typed desired-state and routine-action policy. Updates require the current authenticated family request. expectedVersion is optional; omit it to apply against the current policy version, or supply a version from read for explicit stale-write detection.",
             parameters: {
                 type: "object",
                 properties: {
                     action: { type: "string", enum: ["read", "set_desired_state", "grant_routine_action"] },
-                    expectedVersion: { type: "integer", minimum: 0 },
+                    expectedVersion: { type: "integer", minimum: 0, description: "Optional version returned by read. When omitted, the runtime uses the current policy version." },
                     key: { type: "string" },
                     value: { type: "string" },
                     provenance: { type: "string", enum: ["stated", "observed", "default", "installed_explicit_policy"] },
@@ -51,7 +51,9 @@ exports.stewardPolicyToolDefinition = {
         const actor = ctx.relationshipAuthorization?.actor;
         if (!actor)
             throw new Error("steward policy mutation requires authenticated relationship authority");
-        const expectedVersion = Number(args.expectedVersion);
+        const expectedVersion = args.expectedVersion === undefined
+            ? (0, steward_policy_1.readStewardPolicy)(ctx.agentRoot).version
+            : Number(args.expectedVersion);
         if (!Number.isInteger(expectedVersion) || expectedVersion < 0)
             throw new Error("expectedVersion must be a nonnegative integer");
         let mutation;

package/dist/senses/private-runtime-worker.js

@@ -515,6 +515,7 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
                 const currentHabitName = nextHabitName;
                 const currentTrigger = nextTrigger ?? "overdue";
                 const currentNoSend = nextNoSend;
+                const currentExternalEvent = nextExternalEvent;
                 const currentExternalEventHeartbeat = nextExternalEventHeartbeat;
                 nextExternalEventHeartbeat = undefined;
                 const currentHabitRun = currentReason === "habit" && currentHabitName
@@ -655,6 +656,11 @@ function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1
                 // would cause hasPendingWork() to be true here, producing a
                 // self-sustaining "instinct" loop with no external input. Cap it.
                 if (hasPendingWork(currentHabitRun?.paths.pendingDir)) {
+                    if (currentExternalEvent && (turnErrors.length > 0
+                        || (turnResult && typeof turnResult === "object" && "turnOutcome" in turnResult && turnResult.turnOutcome === "errored"))) {
+                        finalizeCurrentHabitRun();
+                        break;
+                    }
                     clearHeartbeatRestShield();
                     if (consecutiveInstinctTurns >= exports.MAX_CONSECUTIVE_INSTINCT_TURNS) {
                         (0, runtime_1.emitNervesEvent)({

package/dist/senses/private-runtime.js

@@ -835,6 +835,24 @@ function buildHeldReturnWakeMessage() {
         "Return each listed item with surface(delegationId=...) before resting or settling.",
     ].join("\n");
 }
+function buildExternalEventLeaseMessage(event) {
+    const members = [event, ...(event.relatedEvents ?? [])];
+    return [
+        "[current external-event disposition contract]",
+        "This exact lease frame is authoritative for this turn. Ignore older receipts, failed tool arguments, held-work summaries, and checkpoints when choosing disposition arguments.",
+        "Investigate the current observation, then call external_event_disposition once for every listed lease before settling.",
+        ...members.flatMap((member, index) => [
+            "",
+            `lease ${index + 1}:`,
+            `recordPath: ${JSON.stringify(member.recordPath)}`,
+            `expectedGeneration: ${member.generation}`,
+            `classifiedRevision: ${JSON.stringify(member.observationRevision)}`,
+        ]),
+    ].join("\n");
+}
+function externalEventLeaseKey(event) {
+    return JSON.stringify([event.recordPath, event.generation, event.observationRevision, event.claimOwner]);
+}
 function buildAlsoDueLine(agentRoot, currentHabitName, now) {
     const habitsDir = path.join(agentRoot, "habits");
     let files;
@@ -1126,7 +1144,10 @@ async function runPrivateRuntimeTurn(options) {
                     userContent = buildInstinctUserMessage(instincts, reason, state);
                 }
             }
-            if (shouldUseHeldReturnWake) {
+            if (options?.externalEvent) {
+                userContent = buildExternalEventLeaseMessage(options.externalEvent);
+            }
+            else if (shouldUseHeldReturnWake) {
                 userContent = buildHeldReturnWakeMessage();
             }
             // ── Session loader: wraps existing session logic ──────────────────
@@ -1197,6 +1218,7 @@ async function runPrivateRuntimeTurn(options) {
                     };
                 })()
                 : undefined;
+            const committedExternalEventLeases = new Set();
             const externalEventRelationship = options?.externalEvent
                 ? await (async () => {
                     const agentRoot = (0, identity_1.getAgentRoot)(agentName);
@@ -1231,6 +1253,9 @@ async function runPrivateRuntimeTurn(options) {
                                 const decision = initial.authorizeTool("external_event_disposition");
                                 return decision.allowed ? { allowed: true, reason: "relationship-authorized" } : { allowed: false, reason: decision.reason };
                             },
+                            recordCommittedDisposition: (event) => {
+                                committedExternalEventLeases.add(externalEventLeaseKey(event));
+                            },
                         },
                         externalEventEffects: {
                             deliverOwnerDecision: async (input) => {
@@ -1403,6 +1428,13 @@ async function runPrivateRuntimeTurn(options) {
                         ...(effectiveHabitSession ? { habitSession: effectiveHabitSession } : {}),
                     },
                 });
+                if (options?.externalEvent && ["settled", "observed", "rested"].includes(String(result.turnOutcome))) {
+                    const incomplete = [options.externalEvent, ...(options.externalEvent.relatedEvents ?? [])]
+                        .filter((event) => !committedExternalEventLeases.has(externalEventLeaseKey(event)));
+                    if (incomplete.length > 0) {
+                        throw new Error(`External-event turn did not commit dispositions for every exact lease (${incomplete.length} incomplete)`);
+                    }
+                }
                 if (externalRunBase) {
                     const lifecycle = result.turnOutcome === "settled" || result.turnOutcome === "observed" || result.turnOutcome === "rested"
                         ? "completed"

package/dist/senses/sanctuary-runtime.js

@@ -120,10 +120,10 @@ function persistAttempt(filePath, attempt) {
     fs.writeFileSync(temporary, `${JSON.stringify(attempt)}\n`, { mode: 0o600 });
     fs.renameSync(temporary, filePath);
 }
-async function appendAcceptanceAttempt(agentName, attempt) {
+async function appendAcceptanceAttempt(agentRoot, attempt) {
     if (!attempt.scenarioHandleDigest)
         return;
-    const filePath = path.join((0, identity_1.getAgentRoot)(agentName), "state", "acceptance", "restart-attempts.ndjson");
+    const filePath = path.join(agentRoot, "state", "acceptance", "restart-attempts.ndjson");
     const previous = acceptanceLedgerTails.get(filePath) ?? Promise.resolve();
     const current = previous.catch(() => undefined).then(() => {
         fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
@@ -187,6 +187,7 @@ function createSanctuaryToolContext(agentName) {
         message: "creating typed Sanctuary tool context",
         meta: { agentName },
     });
+    const agentRoot = (0, identity_1.getAgentRoot)(agentName);
     const initial = machineConfig(agentName);
     const endpoint = required(initial, "unraidGraphqlUrl");
     const readClient = new unraid_client_1.UnraidClient({ endpoint, apiKey: required(initial, "unraidReadApiKey") });
@@ -216,15 +217,16 @@ function createSanctuaryToolContext(agentName) {
         listContainers: reads.listContainers,
         loadWriteApiKey: async () => required(machineConfig(agentName), "unraidWriteApiKey"),
         persistAttempt: async (attempt) => {
-            persistAttempt(path.join((0, identity_1.getAgentRoot)(agentName), "state", "approvals", "unraid-restart-attempt.json"), attempt);
-            await appendAcceptanceAttempt(agentName, attempt);
+            persistAttempt(path.join(agentRoot, "state", "approvals", "unraid-restart-attempt.json"), attempt);
+            await appendAcceptanceAttempt(agentRoot, attempt);
         },
         acceptanceScenarioHandleDigest: () => (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(agentName)?.scenarioHandleDigest,
         acceptanceApproval: sanctuary_acceptance_marker_1.readSanctuaryAcceptanceApproval,
-        reserveRoutineAction: (input) => (0, steward_policy_1.consumeRoutineActionGrant)((0, identity_1.getAgentRoot)(agentName), input),
-        transitionRoutineAction: (input) => (0, steward_policy_1.transitionRoutineActionReceipt)((0, identity_1.getAgentRoot)(agentName), input),
+        reserveRoutineAction: (input) => (0, steward_policy_1.consumeRoutineActionGrant)(agentRoot, input),
+        transitionRoutineAction: (input) => (0, steward_policy_1.transitionRoutineActionReceipt)(agentRoot, input),
     });
     return {
+        agentRoot,
         sanctuary: {
             listContainers: acceptanceRead("unraid_list_containers", reads.listContainers),
             getContainerLogs: acceptanceRead("unraid_get_container_logs", reads.getContainerLogs),
@@ -255,7 +257,7 @@ function createSanctuaryToolContext(agentName) {
                 collectToolResult(result);
                 return result;
             },
-            recoverRoutineActions: () => (0, steward_policy_1.recoverRoutineActionReceipts)((0, identity_1.getAgentRoot)(agentName), {
+            recoverRoutineActions: () => (0, steward_policy_1.recoverRoutineActionReceipts)(agentRoot, {
                 observeTarget: async (target) => {
                     const observed = await reads.listContainers();
                     if (!observed.ok)

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.755",
+  "version": "0.1.0-alpha.757",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.755",
+      "version": "0.1.0-alpha.757",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.755",
+  "version": "0.1.0-alpha.757",
   "engines": {
     "node": ">=22"
   },