@ouro.bot/cli 0.1.0-alpha.934 → 0.1.0-alpha.936

package/changelog.json

@@ -1,6 +1,24 @@
 {
   "_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.936",
+      "changes": [
+        "Add live Ouro Mailbox Supervision with aged terminal observations, explicit source failures, historical judgments and held-input visibility.",
+        "Add existing-owner local commands for mandate revisions, session pauses, exact custody inspection, evidence-derived retirement and recoverable offline archives.",
+        "Preserve original uncertain outcomes and replay barriers through reconciliation, migration, archive interruption and retry.",
+        "Trace unavailable supervision observations and verified maintenance quiescence without leaking source contents, and preserve CLI startup telemetry when command parsing fails.",
+        "Keep Herdr observation watchers stopped during callback-driven shutdown and prevent obsolete inventory refreshes from creating duplicate polling timers.",
+        "Explicitly label retained legacy automation and receipt-less sends as unqualified; stored mandates do not yet govern every trigger, and Shepherd v1 remains unqualified."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.935",
+      "changes": [
+        "Keep Teams requests running when advisory typing updates are rejected, with correlated warnings and unchanged single-attempt reply custody.",
+        "Run foreground shell commands without blocking receiver I/O, preserving timeouts, closed stdin and command error output."
+      ]
+    },
     {
       "version": "0.1.0-alpha.934",
       "changes": [

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

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.934",
+  "runtimeVersion": "0.1.0-alpha.936",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

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

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

@@ -733,6 +733,11 @@ async function defaultRunSerpentGuide() {
 function createDefaultOuroCliDeps(socketPath = socket_client_1.DEFAULT_DAEMON_SOCKET_PATH) {
     return {
         socketPath,
+        runShepherdOperation: async (command) => {
+            const { runShepherdOperation } = await Promise.resolve().then(() => __importStar(require("../../senses/shepherd/operations")));
+            const { createDefaultShepherdOperationDeps } = await Promise.resolve().then(() => __importStar(require("../../senses/shepherd/operations-defaults")));
+            return runShepherdOperation(command, createDefaultShepherdOperationDeps(async (agent) => (0, socket_client_1.sendDaemonCommand)(socketPath, { kind: "daemon.shepherd_quiesce", agent }, { timeoutMs: socket_client_1.DEFAULT_DAEMON_COMMAND_TIMEOUT_MS })));
+        },
         sendCommand: (commandSocketPath, command) => (0, socket_client_1.sendDaemonCommand)(commandSocketPath, command, {
             timeoutMs: command.kind === "daemon.status"
                 ? socket_client_1.DEFAULT_DAEMON_STATUS_TIMEOUT_MS

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

@@ -7897,6 +7897,15 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         await runMcpServeCliLifecycle(server, mcpInput);
         return "";
     }
+    if (command.kind === "shepherd.status" || command.kind === "shepherd.inspect" || command.kind === "shepherd.pause"
+        || command.kind === "shepherd.resume" || command.kind === "shepherd.mandate.grant" || command.kind === "shepherd.mandate.revoke"
+        || command.kind === "shepherd.reconcile" || command.kind === "shepherd.maintenance") {
+        if (!deps.runShepherdOperation)
+            throw new Error("Shepherd local administration service is unavailable");
+        const text = JSON.stringify(await deps.runShepherdOperation(command), null, 2);
+        deps.writeStdout(text);
+        return text;
+    }
     if (command.kind === "shepherd.chat") {
         const daemonResult = deps.ensureDaemonForFrontend
             ? await deps.ensureDaemonForFrontend(command.agent)

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

@@ -120,10 +120,10 @@ exports.COMMAND_REGISTRY = {
     },
     shepherd: {
         category: "Agents",
-        description: "Open an independent Ouro composer for one coding terminal. --web opens the compact graphical view in cmux; the managed cmux Shepherd sense also installs a native Talk to Ouro button. Without --web, /cancel cancels only Ouro's turn and /quit exits. Not an input hook in the coding agent.",
+        description: "Open an independent Ouro composer or administer Shepherd as the existing local owner. Administration is same-UID authority, not proof of human presence. status/inspect are read-only; mutations require --expected-revision and --request-id. pause/resume require --host and --session; resume never releases held custody. mandate grant requires --project, --task, --expires-at; revoke requires --id. reconcile --id --resolution retired derives host evidence; delivered is unsupported until native receipt lookup is qualified. maintenance --destination requires fresh disabled-and-stopped daemon proof and retired terminals. --web opens the compact graphical view in cmux. Not an input hook in the coding agent.",
         usage: "ouro shepherd chat --agent <name> [--session <UUID>] [--web]",
         example: "ouro shepherd chat --agent ouroboros",
-        subcommands: ["chat"],
+        subcommands: ["chat", "status", "inspect", "pause", "resume", "mandate", "reconcile", "maintenance"],
     },
     config: {
         category: "Agents",

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

@@ -53,6 +53,7 @@ const path = __importStar(require("path"));
 const friends_1 = require("@ouro.bot/friends");
 const cli_help_1 = require("./cli-help");
 const surface_1 = require("../../senses/shepherd/surface");
+const operations_1 = require("../shepherd/operations");
 const local_audio_control_1 = require("../../senses/voice/local-audio-control");
 const cli_desk_1 = require("./cli-desk");
 const flight_recorder_1 = require("../../arc/flight-recorder");
@@ -3124,7 +3125,7 @@ function parseOuroCommand(args) {
     if (head === "shepherd") {
         const usage = "Usage: ouro shepherd chat --agent <name> [--session <UUID>] [--web]";
         if (args[1] !== "chat")
-            throw new Error(usage);
+            return (0, operations_1.parseShepherdOperation)(args.slice(1));
         const values = new Map();
         for (let i = 2; i < args.length; i += 1) {
             const flag = args[i];

package/dist/heart/daemon/daemon.js

@@ -1931,6 +1931,20 @@ class OuroDaemon {
                     data,
                 };
             }
+            case "daemon.shepherd_stopped": {
+                if (typeof command.agent !== "string" || !this.senseManager?.shepherdStoppedProof) {
+                    return { ok: false, error: "Shepherd lifecycle proof is unavailable" };
+                }
+                const data = this.senseManager.shepherdStoppedProof(command.agent);
+                return { ok: true, data };
+            }
+            case "daemon.shepherd_quiesce": {
+                if (typeof command.agent !== "string" || !this.senseManager?.quiesceShepherd) {
+                    return { ok: false, error: "Shepherd lifecycle control is unavailable" };
+                }
+                const data = await this.senseManager.quiesceShepherd(command.agent);
+                return { ok: true, data };
+            }
             case "daemon.health": {
                 const checks = await this.healthMonitor.runChecks();
                 const summary = checks.map((check) => `${check.name}:${check.status}:${check.message}`).join("\n");

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

@@ -5,7 +5,10 @@ const runtime_1 = require("../../nerves/runtime");
 const cli_arg_redaction_1 = require("./cli-arg-redaction");
 const daemon_cli_1 = require("./daemon-cli");
 const runtime_logging_1 = require("./runtime-logging");
-(0, runtime_logging_1.configureDaemonRuntimeLogger)("ouro");
+if (process.argv[2] === "shepherd" && process.argv[3] !== "chat")
+    (0, runtime_logging_1.configureDaemonRuntimeLogger)("ouro", { machine: true });
+else
+    (0, runtime_logging_1.configureDaemonRuntimeLogger)("ouro");
 (0, runtime_1.emitNervesEvent)({
     component: "daemon",
     event: "daemon.cli_entry_start",

package/dist/heart/daemon/runtime-logging.js

@@ -125,7 +125,7 @@ function resolveLoggingPathTarget(explicit) {
     }
 }
 function configureDaemonRuntimeLogger(processName, options = {}) {
-    const pathTarget = resolveLoggingPathTarget(options.agentName);
+    const pathTarget = options.machine ? { kind: "machine" } : resolveLoggingPathTarget(options.agentName);
     const configPath = options.configPath
         ?? (pathTarget.kind === "machine"
             ? machineDaemonLoggingConfigPath(options.homeDir)

package/dist/heart/daemon/sense-manager.js

@@ -593,6 +593,8 @@ class DaemonSenseManager {
     configRefreshRetryTimers = new Map();
     configRefreshRetryAttempts = new Map();
     bundlesRoot;
+    quiescedShepherdOwners = new Set();
+    initiallyUnmanagedShepherdOwners;
     constructor(options) {
         const bundlesRoot = options.bundlesRoot ?? path.join(os.homedir(), "AgentBundles");
         this.bundlesRoot = bundlesRoot;
@@ -601,6 +603,7 @@ class DaemonSenseManager {
             const facts = senseFactsFromRuntimeConfig(agent, senses, (0, runtime_credentials_1.readRuntimeCredentialConfig)(agent), (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agent), workbenchHasStaleBundleEntry);
             return [agent, { senses, workbenchHasStaleBundleEntry, facts }];
         }));
+        this.initiallyUnmanagedShepherdOwners = new Set([...this.contexts.entries()].filter(([, context]) => !context.senses.shepherd.enabled).map(([agent]) => agent));
         const managedSenseAgents = [...this.contexts.entries()].flatMap(([agent, context]) => {
             return ["teams", "bluebubbles", "mail", "voice", "a2a", "telegram", "shepherd"]
                 .filter((sense) => context.senses[sense].enabled)
@@ -620,6 +623,8 @@ class DaemonSenseManager {
                 const parsed = parseSenseSnapshotName(name);
                 if (!parsed)
                     return { ok: true };
+                if (parsed.sense === "shepherd" && this.quiescedShepherdOwners.has(parsed.agent))
+                    return { ok: false, skip: true, error: "Shepherd is quiesced for maintenance until daemon restart" };
                 const context = this.contexts.get(parsed.agent);
                 if (!context)
                     return { ok: true };
@@ -711,6 +716,8 @@ class DaemonSenseManager {
             /* v8 ignore next -- defensive: config refreshes are only scheduled for known agent contexts @preserve */
             if (!context)
                 return;
+            if (parsed.sense === "shepherd" && this.quiescedShepherdOwners.has(parsed.agent))
+                return;
             context.facts = senseFactsFromRuntimeConfig(parsed.agent, context.senses, refreshed, machineRefreshed, context.workbenchHasStaleBundleEntry);
             if (!context.facts[parsed.sense].configured) {
                 if (this.shouldRetryConfigRefresh(parsed.agent, parsed.sense, refreshed, machineRefreshed)) {
@@ -723,6 +730,8 @@ class DaemonSenseManager {
             }
             this.clearConfigRetryState(name);
             setTimeout(() => {
+                if (parsed.sense === "shepherd" && this.quiescedShepherdOwners.has(parsed.agent))
+                    return;
                 void this.processManager.startAgent?.(name).catch((error) => {
                     (0, runtime_1.emitNervesEvent)({
                         level: "error",
@@ -814,6 +823,47 @@ class DaemonSenseManager {
             .filter((pid) => pid !== null && pid !== undefined);
     }
     /* v8 ignore stop */
+    assertShepherdDisabled(agent) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent) || !this.contexts.has(agent))
+            throw new Error("unknown Shepherd owner");
+        const config = JSON.parse(fs.readFileSync(path.join(this.bundlesRoot, `${agent}.ouro`, "agent.json"), "utf8"));
+        const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+        if (!object(config) || !object(config.senses) || !object(config.senses.shepherd) || config.senses.shepherd.enabled !== false) {
+            throw new Error("maintenance requires explicitly disabled Shepherd in fresh agent.json");
+        }
+    }
+    async quiesceShepherd(agent) {
+        this.assertShepherdDisabled(agent);
+        this.quiescedShepherdOwners.add(agent);
+        this.contexts.get(agent).senses.shepherd.enabled = false;
+        const managedName = `${agent}:shepherd`;
+        const snapshot = this.processManager.listAgentSnapshots().find(row => row.name === managedName);
+        if (snapshot && (snapshot.status !== "stopped" || snapshot.pid !== null)) {
+            if (!this.processManager.stopAgent)
+                throw new Error("managed Shepherd stop is unavailable");
+            const retry = this.configRefreshRetryTimers.get(managedName);
+            if (retry)
+                clearTimeout(retry);
+            this.configRefreshRetryTimers.delete(managedName);
+            this.configRefreshRetryAttempts.delete(managedName);
+            await this.processManager.stopAgent(managedName);
+        }
+        return this.shepherdStoppedProof(agent);
+    }
+    shepherdStoppedProof(agent) {
+        this.assertShepherdDisabled(agent);
+        const snapshots = this.processManager.listAgentSnapshots().filter(row => row.name === `${agent}:shepherd`);
+        // Disabled-at-startup senses are never registered with this process manager.
+        if (snapshots.length === 0 && this.initiallyUnmanagedShepherdOwners.has(agent)) {
+            return { kind: "daemon_lifecycle", checkedAt: new Date().toISOString(), enabled: false, processState: "stopped" };
+        }
+        if (snapshots.length !== 1)
+            throw new Error("actual managed Shepherd process snapshot is unavailable");
+        const snapshot = snapshots[0];
+        if (snapshot.status !== "stopped" || snapshot.pid !== null)
+            throw new Error("maintenance requires stopped Shepherd with no active PID");
+        return { kind: "daemon_lifecycle", checkedAt: new Date().toISOString(), enabled: false, processState: "stopped" };
+    }
     listHealthProbes() {
         const probes = [];
         for (const [agent, context] of this.contexts.entries()) {
@@ -854,6 +904,9 @@ class DaemonSenseManager {
         return probes;
     }
     async restartSense(managedName) {
+        const parsed = parseSenseSnapshotName(managedName);
+        if (parsed?.sense === "shepherd" && this.quiescedShepherdOwners.has(parsed.agent))
+            throw new Error("Shepherd is quiesced for maintenance until daemon restart");
         if (this.processManager.restartAgent) {
             await this.processManager.restartAgent(managedName);
             return;

package/dist/heart/mailbox/mailbox-http-hooks.js

@@ -66,6 +66,7 @@ function createMailboxHttpReadHooks(options) {
     const agentRoot = (agentName) => resolveAgentRoot(bundlesRoot, agentName);
     return {
         agentRoot,
+        readAgentSupervision: options.readAgentSupervision ?? ((agentName) => (0, mailbox_read_1.readMailboxSupervision)(agentName, { agentRoot: agentRoot(agentName) })),
         readAgentSessions: options.readAgentSessions ?? ((agentName) => (0, mailbox_read_1.readSessionInventory)(agentName, readOptions)),
         readAgentTranscript: options.readAgentTranscript ?? ((agentName, friendId, channel, key) => (0, mailbox_read_1.readSessionTranscript)(agentName, friendId, channel, key, readOptions)),
         readAgentCoding: options.readAgentCoding ?? ((agentName) => (0, mailbox_read_1.readCodingDeep)(agentRoot(agentName))),

package/dist/heart/mailbox/mailbox-http-routes.js

@@ -173,6 +173,14 @@ function createMailboxHttpRequestHandler(options) {
 }
 async function handleAgentRoute(request, response, context) {
     const { agent, surface, options } = context;
+    if (surface === "supervision") {
+        if (request.method !== "GET") {
+            (0, mailbox_http_response_1.writeJson)(response, 405, { ok: false, error: "Supervision is read-only; use the local owner CLI for administration" });
+            return;
+        }
+        (0, mailbox_http_response_1.writeJson)(response, 200, options.hooks.readAgentSupervision(agent));
+        return;
+    }
     if (!surface) {
         const view = options.readAgentView?.(agent);
         if (view) {

package/dist/heart/mailbox/mailbox-read.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readSelfFixView = exports.readMailboxContinuity = exports.readOrientationView = exports.readObligationDetailView = exports.readNoteDecisionView = exports.readSentinelView = exports.readContextLossGauntletView = exports.readChangesView = exports.readNeedsMeView = exports.readNotesView = exports.readLogView = exports.readContextPacketView = exports.readContextPacketListView = exports.readHabitView = exports.readHabitRunView = exports.readHabitRunReceiptView = exports.readHabitSessionSummaryView = exports.readHabitSessionSummaryListView = exports.readFriendView = exports.readDeskPrefs = exports.readDaemonHealthDeep = exports.readCodingDeep = exports.readBridgeInventory = exports.readAttentionView = exports.readMailView = exports.readMailMessageView = exports.readSessionTranscript = exports.readSessionInventory = exports.readMailboxMachineState = exports.readMailboxAgentState = exports.readObligationSummary = void 0;
+exports.readSelfFixView = exports.readMailboxContinuity = exports.readOrientationView = exports.readObligationDetailView = exports.readNoteDecisionView = exports.readSentinelView = exports.readContextLossGauntletView = exports.readChangesView = exports.readNeedsMeView = exports.readNotesView = exports.readLogView = exports.readContextPacketView = exports.readContextPacketListView = exports.readHabitView = exports.readHabitRunView = exports.readHabitRunReceiptView = exports.readHabitSessionSummaryView = exports.readHabitSessionSummaryListView = exports.readFriendView = exports.readDeskPrefs = exports.readDaemonHealthDeep = exports.readCodingDeep = exports.readBridgeInventory = exports.readAttentionView = exports.readMailView = exports.readMailMessageView = exports.readSessionTranscript = exports.readSessionInventory = exports.readMailboxMachineState = exports.readMailboxAgentState = exports.readObligationSummary = exports.readMailboxSupervision = void 0;
+var mailbox_supervision_1 = require("./mailbox-supervision");
+Object.defineProperty(exports, "readMailboxSupervision", { enumerable: true, get: function () { return mailbox_supervision_1.readMailboxSupervision; } });
 var agent_machine_1 = require("./readers/agent-machine");
 Object.defineProperty(exports, "readObligationSummary", { enumerable: true, get: function () { return agent_machine_1.readObligationSummary; } });
 Object.defineProperty(exports, "readMailboxAgentState", { enumerable: true, get: function () { return agent_machine_1.readMailboxAgentState; } });

package/dist/heart/mailbox/mailbox-supervision.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMailboxSupervision = readMailboxSupervision;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+const supervision_1 = require("../shepherd/supervision");
+function owned(metadata) {
+    if (!process.getuid || metadata.uid !== process.getuid())
+        throw new Error("Observation requires current-user ownership");
+}
+function directory(candidate, privateMode) {
+    const metadata = fs.lstatSync(candidate, { throwIfNoEntry: false });
+    if (!metadata)
+        return false;
+    owned(metadata);
+    if (!metadata.isDirectory() || (privateMode ? (metadata.mode & 0o7777) !== 0o700 : (metadata.mode & 0o022) !== 0)) {
+        throw new Error("Observation requires unlinked private directories and non-writable ancestors");
+    }
+    return true;
+}
+function regular(metadata) {
+    owned(metadata);
+    if (!metadata.isFile() || (metadata.mode & 0o7777) !== 0o600 || metadata.nlink !== 1
+        || metadata.size > supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES)
+        throw new Error("Observation requires a bounded private regular file");
+}
+function unavailable(agentName, nowMs, code) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart", level: "warn", event: "heart.shepherd_observation_unavailable",
+        message: "Supervision observation is unavailable; no current terminal counts can be established", meta: { code },
+    });
+    const view = (0, supervision_1.buildShepherdSupervisionView)({
+        schemaVersion: 1, agentName, observedAt: new Date(nowMs).toISOString(),
+        sourceHealth: { host: "missing", guidance: "missing", mandates: "missing", returns: "missing", custody: "missing", notices: "missing" },
+        sessions: { totalCount: null, truncated: true, items: [] },
+        timeline: { totalCount: null, truncated: true, items: [] },
+        custody: { revision: null, bytes: null, capacity: "unknown", claims: { totalCount: null, truncated: true, items: [] } },
+        sourceErrors: [{ source: "replica", code, detail: code === "observation_missing"
+                    ? "No Shepherd observation is available. Check that the Shepherd sense is running."
+                    : "The Shepherd observation could not be read safely or has an invalid schema." }],
+    }, nowMs);
+    view.freshness = { status: "unknown", observedAt: null, ageMs: null };
+    return view;
+}
+/** A bounded read-only replica, never an authority file or a live terminal access path. */
+function readMailboxSupervision(agentName, options) {
+    const nowMs = options.nowMs ?? Date.now();
+    try {
+        let current = path.resolve(options.agentRoot);
+        if (!directory(current, false))
+            return unavailable(agentName, nowMs, "observation_missing");
+        for (const name of ["state", "senses", "shepherd"]) {
+            current = path.join(current, name);
+            if (!directory(current, name === "shepherd"))
+                return unavailable(agentName, nowMs, "observation_missing");
+        }
+        const file = path.join(current, supervision_1.SHEPHERD_OBSERVATION_FILE);
+        const before = fs.lstatSync(file, { throwIfNoEntry: false });
+        if (!before)
+            return unavailable(agentName, nowMs, "observation_missing");
+        regular(before);
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        let raw;
+        try {
+            const opened = fs.fstatSync(fd);
+            regular(opened);
+            if (opened.ino !== before.ino || opened.dev !== before.dev)
+                throw new Error("Observation changed during read");
+            const buffer = Buffer.alloc(supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES + 1);
+            let size = 0;
+            while (size < buffer.length) {
+                const received = fs.readSync(fd, buffer, size, buffer.length - size, null);
+                if (!received)
+                    break;
+                size += received;
+            }
+            if (size > supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES)
+                throw new Error("Observation exceeds read limit");
+            const after = fs.fstatSync(fd);
+            if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) {
+                throw new Error("Observation changed during read");
+            }
+            raw = buffer.toString("utf8", 0, size);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const snapshot = JSON.parse(raw);
+        if (!(0, supervision_1.isShepherdSupervisionSnapshot)(snapshot) || snapshot.agentName !== agentName)
+            throw new Error("Invalid observation identity or schema");
+        return (0, supervision_1.buildShepherdSupervisionView)(snapshot, nowMs);
+    }
+    catch {
+        // Do not echo untrusted file contents, paths or operating-system errors into the browser.
+        return unavailable(agentName, nowMs, "observation_invalid");
+    }
+}

package/dist/heart/shepherd/custody-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });