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

package/dist/senses/shepherd/observation-publisher.js

@@ -0,0 +1,320 @@
+"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.createShepherdObservationPublisher = createShepherdObservationPublisher;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const mandates_1 = require("../../heart/shepherd/mandates");
+const supervision_1 = require("../../heart/shepherd/supervision");
+const runtime_1 = require("../../nerves/runtime");
+const guidance_1 = require("./guidance");
+const notice_outbox_1 = require("./notice-outbox");
+const recovery_1 = require("./recovery");
+const checkin_store_1 = require("./checkin-store");
+const returns_1 = require("./returns");
+const redact_1 = require("./redact");
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const kinds = new Set(["premature", "gate", "done", "working", "waiting", "unclear", "error", "loop_guard"]);
+const safe = (value) => (0, redact_1.redactSecrets)(value).replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]+/g, " ").trim().slice(0, 2000) || "(unnamed)";
+const idFor = (value) => (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(value)).digest("hex");
+const iso = (at) => {
+    if (!Number.isFinite(Date.parse(at)))
+        throw new Error("Invalid observation source timestamp");
+    return new Date(at).toISOString();
+};
+const emptyPage = () => ({ totalCount: 0, truncated: false, items: [] });
+const unknownCustody = () => ({
+    revision: null, bytes: null, capacity: "unknown", claims: { totalCount: null, truncated: true, items: [] },
+});
+function page(events, totalCount) {
+    const unique = [...new Map(events.map(event => [event.id, event])).values()];
+    const count = totalCount === undefined ? unique.length : totalCount;
+    const items = unique.sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, supervision_1.SHEPHERD_SUPERVISION_LIMIT);
+    return { items, totalCount: count, truncated: count === null || count > items.length };
+}
+/** Unlike the legacy convenience reader, a malformed row never becomes a healthy empty history. */
+function readReturnSummaries(root) {
+    const file = (0, returns_1.returnsLogPath)(root);
+    const metadata = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!metadata)
+        return null;
+    if (!metadata.isFile() || metadata.nlink !== 1 || metadata.size > supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES)
+        throw new Error("Invalid returns source");
+    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);
+        if (opened.ino !== metadata.ino || opened.dev !== metadata.dev)
+            throw new Error("Returns source changed");
+        const bytes = Buffer.alloc(supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES + 1);
+        let size = 0;
+        while (size < bytes.length) {
+            const received = fs.readSync(fd, bytes, size, bytes.length - size, null);
+            if (!received)
+                break;
+            size += received;
+        }
+        if (size > supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES)
+            throw new Error("Returns source exceeds limit");
+        raw = bytes.toString("utf8", 0, size);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return raw.split("\n").filter(line => line.trim()).map(line => {
+        const value = JSON.parse(line);
+        if (!object(value) || typeof value.at !== "string" || typeof value.host !== "string" || typeof value.session !== "string"
+            || typeof value.transition !== "string" || typeof value.kind !== "string" || !kinds.has(value.kind)
+            || !value.host || !value.session || !value.transition || (value.action !== "respond" && value.action !== "let_through")
+            || typeof value.reason !== "string")
+            throw new Error("Invalid returns source schema");
+        return { at: iso(value.at), host: safe(value.host), session: safe(value.session), transition: value.transition, kind: value.kind,
+            action: value.action, reason: safe(value.reason) };
+    });
+}
+function createShepherdObservationPublisher(options) {
+    const now = options.now ?? Date.now;
+    let stopped = false;
+    let observed = null;
+    let returns = [];
+    let custody = unknownCustody();
+    const events = { returns: emptyPage(), custody: emptyPage(), notices: emptyPage() };
+    let observations = emptyPage();
+    function projectAndPublish() {
+        const at = now();
+        const health = {
+            host: observed && !observed.error ? "ok" : "missing", guidance: "ok", mandates: "ok", returns: "ok", custody: "ok", notices: "ok",
+        };
+        const errors = [];
+        const fail = (source) => {
+            health[source] = "error";
+            errors.push({ source, code: "read_failed", detail: `The ${source} source could not be read. Any retained history is not current.` });
+        };
+        const read = (source, fn) => {
+            try {
+                return fn();
+            }
+            catch {
+                fail(source);
+                return null;
+            }
+        };
+        const guidance = read("guidance", () => (0, guidance_1.readGuidance)(options.agentRoot));
+        const mandates = read("mandates", () => (0, mandates_1.readShepherdMandates)(options.agentRoot));
+        try {
+            const current = readReturnSummaries(options.agentRoot);
+            if (current === null)
+                health.returns = "missing";
+            else {
+                returns = current;
+                events.returns = page(current.map(record => ({
+                    id: `return:${idFor([record.host, record.session, record.transition, record.at])}`,
+                    host: record.host, session: record.session, instance: null, at: record.at, kind: "judgment", summary: record.kind,
+                })));
+            }
+        }
+        catch {
+            fail("returns");
+        }
+        try {
+            const current = (0, recovery_1.readCheckInSnapshot)((0, checkin_store_1.checkInStorePath)(options.agentRoot), { limit: supervision_1.SHEPHERD_SUPERVISION_LIMIT });
+            if (current.state === "missing")
+                health.custody = "missing";
+            else {
+                custody = {
+                    revision: current.revision, bytes: current.bytes, capacity: current.capacity,
+                    claims: { totalCount: current.totalCount, truncated: current.nextCursor !== null, items: current.entries.map(entry => ({
+                            id: entry.id, host: safe(entry.host), session: safe(entry.session), instance: entry.instance === null ? null : safe(entry.instance),
+                            state: entry.state, claimedAt: iso(entry.claimedAt), reason: entry.reason === null ? null : safe(entry.reason), retired: entry.retired,
+                        })) },
+                };
+                events.custody = page(current.entries.flatMap(entry => {
+                    const base = { host: safe(entry.host), session: safe(entry.session), instance: entry.instance === null ? null : safe(entry.instance) };
+                    const boundAdmission = entry.receipt?.requestId === entry.id && entry.receipt.surfaceId === entry.session
+                        && entry.receipt.processInstance === entry.instance && entry.receipt.pasteAdmitted && entry.receipt.submitAdmitted;
+                    return [{
+                            ...base, id: `input:${entry.id}`, at: iso(entry.claimedAt),
+                            kind: entry.state === "sent" ? boundAdmission ? "input_admitted" : "legacy_input_reported"
+                                : entry.state === "not_sent" ? "observation" : "input_unknown",
+                            summary: entry.state === "sent" ? boundAdmission ? "Bound host receipt reports paste and submit admission; not proof of task completion"
+                                : "Legacy dispatcher reported sent; no qualified bound paste-and-submit receipt. Not proof of input admission or task completion."
+                                : entry.state === "not_sent" ? "Input refused; no terminal input"
+                                    : "Claim held; input outcome is unknown. Reconcile evidence, do not retry blindly.",
+                        }, ...entry.reconciliations.map(receipt => ({
+                            ...base, id: `recovery:${entry.id}:${receipt.revision}`, at: iso(receipt.at),
+                            kind: "recovery", summary: `Owner acknowledged recovery: ${receipt.resolution}; original state ${receipt.originalState}`,
+                        }))];
+                }), current.nextCursor === null ? undefined : null);
+            }
+        }
+        catch {
+            fail("custody");
+        }
+        try {
+            events.notices = page((0, notice_outbox_1.readNoticeOutbox)(options.agentRoot).flatMap(entry => {
+                const base = { host: safe(entry.record.host), session: safe(entry.record.session), instance: null };
+                return [{
+                        ...base, id: `notice:${entry.id}`, at: iso(entry.record.at), kind: "notification_queued", summary: "Owner notification queued",
+                    }, ...Object.entries(entry.deliveries).map(([recipient, delivery]) => ({
+                        ...base, id: `notice:${entry.id}:${idFor(recipient)}`, at: iso(delivery.at),
+                        kind: delivery.state === "sent" ? "notification_delivered"
+                            : delivery.state === "unknown" ? "notification_unknown" : "notification_queued",
+                        summary: delivery.state === "sent" ? "Owner notification accepted by transport; not proof the owner read it"
+                            : delivery.state === "unknown" ? "Owner notification delivery is unknown" : "Owner notification pending transport",
+                    }))];
+            }));
+        }
+        catch {
+            fail("notices");
+        }
+        if (observed?.error)
+            errors.push({ source: "host", code: observed.error, detail: observed.error === "sense_stopped"
+                    ? "The Shepherd sense is stopped. Retained observations are historical."
+                    : "The terminal host is unavailable. Retained observations are historical." });
+        const sessions = (observed?.sessions ?? []).slice(0, supervision_1.SHEPHERD_SUPERVISION_LIMIT).map(row => {
+            const session = row.session;
+            let authority = "unknown";
+            let withheldReason = row.error ? "Terminal could not be read; no current policy assessment" : "Guarded automatic input is not qualified for this host";
+            if (row.error && errors.length < 50)
+                errors.push({ source: "host", code: "row_read_failed", detail: `Terminal ${safe(session.id)} could not be read` });
+            if (guidance && mandates) {
+                if ((0, guidance_1.applicableGuidance)(guidance, { host: options.host, session: session.id, cwd: session.cwd ?? null, task: null }).paused)
+                    authority = "paused";
+                else if (session.cwd) {
+                    const resolution = (0, mandates_1.resolveShepherdMandate)(mandates, {
+                        project: session.cwd, host: options.host, session: session.id, ...(session.instance ? { instance: session.instance } : {}),
+                    }, at);
+                    authority = resolution.state === "authorized" ? "active" : resolution.reason === "ambiguous_mandates" ? "ambiguous" : "absent";
+                }
+                else
+                    authority = "absent";
+                if (authority === "paused")
+                    withheldReason = "Stored terminal pause is set";
+                else if (authority === "absent")
+                    withheldReason = "No applicable stored mandate; legacy automatic paths are not uniformly mandate-enforced";
+                else if (authority === "ambiguous")
+                    withheldReason = "Multiple stored mandates apply; policy scope is ambiguous";
+            }
+            const last = returns.filter(record => record.host === options.host && record.session === safe(session.id)).sort((a, b) => b.at.localeCompare(a.at))[0];
+            return {
+                host: safe(options.host), session: safe(session.id), instance: session.instance ? safe(session.instance) : null,
+                label: safe(session.title || session.ref || session.id), harness: session.agent ? safe(session.agent) : null,
+                project: session.cwd ? safe(session.cwd) : null, activity: row.activity,
+                observedAt: row.observedAt === null ? null : new Date(row.observedAt).toISOString(),
+                lastDecision: last?.kind ?? null, lastAction: last?.action ?? null, lastReason: last?.reason ?? null,
+                lastActionAt: last?.at ?? null, withheldReason, authority, capability: "unsupported",
+            };
+        });
+        const allEvents = [...Object.values(events), observations];
+        const total = allEvents.some(value => value.totalCount === null) ? null : allEvents.reduce((sum, value) => sum + value.totalCount, 0);
+        const snapshot = {
+            schemaVersion: 1, agentName: options.agentName, observedAt: new Date(observed?.at ?? at).toISOString(),
+            sourceHealth: health, sourceErrors: errors,
+            sessions: { totalCount: observed ? observed.sessions.length : null,
+                truncated: !observed || observed.sessions.length > sessions.length, items: sessions },
+            timeline: page(allEvents.flatMap(value => value.items), total), custody,
+        };
+        try {
+            if (!(0, supervision_1.isShepherdSupervisionSnapshot)(snapshot))
+                throw new Error("Invalid bounded observation projection");
+            const encoded = JSON.stringify(snapshot);
+            if (Buffer.byteLength(encoded) > supervision_1.SHEPHERD_OBSERVATION_MAX_BYTES)
+                throw new Error("Observation exceeds publication limit");
+            const dir = (0, returns_1.shepherdStateDir)(options.agentRoot);
+            (0, checkin_store_1.validateCustodyDirectory)(dir, true);
+            const temporary = path.join(dir, `${supervision_1.SHEPHERD_OBSERVATION_FILE}.${(0, node_crypto_1.randomUUID)()}.tmp`);
+            const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            try {
+                fs.writeFileSync(fd, encoded);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.renameSync(temporary, path.join(dir, supervision_1.SHEPHERD_OBSERVATION_FILE));
+            const directory = fs.openSync(dir, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+            return true;
+        }
+        catch {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_observation_failed",
+                message: "Could not publish a safe Shepherd observation; the previous replica must age out", meta: { agent: options.agentName } });
+            return false;
+        }
+    }
+    function publish() {
+        try {
+            return projectAndPublish();
+        }
+        catch {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_observation_failed",
+                message: "Could not assemble a Shepherd observation; the previous replica must age out", meta: { agent: options.agentName } });
+            return false;
+        }
+    }
+    return {
+        observe(observation) {
+            if (stopped)
+                return false;
+            observed = structuredClone(observation);
+            if (!observation.error) {
+                const current = observation.sessions.slice(0, supervision_1.SHEPHERD_SUPERVISION_LIMIT).map(row => ({
+                    id: `observation:${idFor([options.host, row.session.id, row.session.instance ?? null, observation.at])}`,
+                    host: safe(options.host), session: safe(row.session.id), instance: row.session.instance ? safe(row.session.instance) : null,
+                    at: new Date(observation.at).toISOString(), kind: "observation",
+                    summary: row.error ? "Terminal observation failed" : `Observed terminal activity: ${row.activity}`,
+                }));
+                const unique = new Map([...current, ...observations.items].map(event => [event.id, event]));
+                observations = page([...unique.values()], observations.totalCount
+                    + current.filter(event => !observations.items.some(previous => previous.id === event.id)).length);
+            }
+            return publish();
+        },
+        refresh() { return !stopped && publish(); },
+        stop() {
+            if (stopped)
+                return;
+            observed = { ...(observed ?? { at: 0, sessions: [] }), error: "sense_stopped" };
+            publish();
+            stopped = true;
+        },
+    };
+}

package/dist/senses/shepherd/operations-defaults.js

@@ -0,0 +1,86 @@
+"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.createDefaultShepherdOperationDeps = createDefaultShepherdOperationDeps;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+const identity_1 = require("../../heart/identity");
+const runtime_credentials_1 = require("../../heart/runtime-credentials");
+const shepherd_config_1 = require("../../heart/shepherd-config");
+const host_1 = require("./host");
+const surface_1 = require("./surface");
+const runtime_1 = require("../../nerves/runtime");
+function createDefaultShepherdOperationDeps(lifecycle) {
+    return {
+        agentRoot: agent => path.join((0, identity_1.getAgentBundlesRoot)(), `${agent}.ouro`),
+        resolveOwner: async (agent) => {
+            if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent))
+                throw new Error("existing local owner requires a safe agent name");
+            const root = path.join((0, identity_1.getAgentBundlesRoot)(), `${agent}.ouro`);
+            if (!fs.lstatSync(root, { throwIfNoEntry: false })?.isDirectory()
+                || !fs.lstatSync(path.join(root, "friends"), { throwIfNoEntry: false })?.isDirectory()) {
+                throw new Error("existing local owner linking is required; no bundle or friends directory was created");
+            }
+            return { actorId: await (0, surface_1.resolveExistingLocalOwner)((0, surface_1.localShepherdFriendStore)(agent)) };
+        },
+        host: async (agent) => {
+            const machine = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agent);
+            if (!machine.ok)
+                throw new Error("machine Shepherd connection configuration is unavailable");
+            const connection = (0, shepherd_config_1.resolveShepherdConnection)(agent, machine.config);
+            if (!connection.ok)
+                throw new Error(connection.error);
+            return (0, host_1.createShepherdHost)(connection.connection, { agentName: agent });
+        },
+        senseStopped: async (agent) => {
+            const response = await lifecycle(agent);
+            if (!response.ok)
+                throw new Error(response.error ?? "daemon lifecycle unavailable");
+            const value = response.data;
+            if (value === null || typeof value !== "object" || !("kind" in value) || value.kind !== "daemon_lifecycle"
+                || !("enabled" in value) || value.enabled !== false || !("processState" in value) || value.processState !== "stopped"
+                || !("checkedAt" in value) || typeof value.checkedAt !== "string" || !Number.isFinite(Date.parse(value.checkedAt))
+                || Date.parse(value.checkedAt) > Date.now() || Date.now() - Date.parse(value.checkedAt) > 30_000) {
+                throw new Error("fresh disabled and stopped daemon lifecycle proof is unavailable");
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses", event: "senses.shepherd_maintenance_quiescence_confirmed",
+                message: "validated fresh daemon proof that Shepherd is disabled and stopped",
+                meta: { agent, processState: "stopped" },
+            });
+            return { kind: "daemon_lifecycle", enabled: false, processState: "stopped", checkedAt: value.checkedAt };
+        },
+    };
+}

package/dist/senses/shepherd/operations.js

@@ -0,0 +1,159 @@
+"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.runShepherdOperation = runShepherdOperation;
+const node_crypto_1 = require("node:crypto");
+const path = __importStar(require("node:path"));
+const mandates_1 = require("../../heart/shepherd/mandates");
+const mailbox_supervision_1 = require("../../heart/mailbox/mailbox-supervision");
+const supervision_1 = require("../../heart/shepherd/supervision");
+const guidance_1 = require("./guidance");
+const checkin_store_1 = require("./checkin-store");
+const recovery_1 = require("./recovery");
+const runtime_1 = require("../../nerves/runtime");
+function fingerprint(command) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(command, Object.keys(command).sort())).digest("hex");
+}
+/** Same-UID local administration only. No evidence, actor, or lifecycle claims come from argv. */
+async function runShepherdOperation(command, deps) {
+    try {
+        const { actorId } = await deps.resolveOwner(command.agent);
+        const actor = { kind: "local_owner_administration", actorId };
+        const root = deps.agentRoot(command.agent);
+        const file = (0, checkin_store_1.checkInStorePath)(root);
+        if (command.kind === "shepherd.status")
+            return {
+                boundary: "same_uid_local_owner_administration_not_human_presence",
+                automation: { mode: "legacy_unqualified", mandatesEnforcedForAllTriggers: false, unattendedKeysPossible: false, warning: supervision_1.SHEPHERD_ALPHA_AUTOMATION_WARNING },
+                supervision: (0, mailbox_supervision_1.readMailboxSupervision)(command.agent, { agentRoot: root }),
+                guidance: (0, guidance_1.readGuidance)(root), mandates: (0, mandates_1.readShepherdMandates)(root),
+                custody: (0, recovery_1.readCheckInSnapshot)(file, { limit: 50 }),
+            };
+        if (command.kind === "shepherd.inspect")
+            return (0, recovery_1.readCheckInSnapshot)(file, command);
+        if (command.kind === "shepherd.mandate.grant")
+            return await (0, mandates_1.updateShepherdMandate)(root, {
+                operation: "grant", context: { ...actor, requestId: command.requestId }, expectedRevision: command.expectedRevision,
+                target: {
+                    project: command.project, ...(command.host ? { host: command.host } : {}),
+                    ...(command.session ? { session: command.session } : {}), ...(command.instance ? { instance: command.instance } : {}),
+                },
+                task: command.task, expiresAt: command.expiresAt,
+            });
+        if (command.kind === "shepherd.mandate.revoke")
+            return await (0, mandates_1.updateShepherdMandate)(root, {
+                operation: "revoke", context: { ...actor, requestId: command.requestId }, expectedRevision: command.expectedRevision,
+                mandateId: command.id.startsWith("mandate:") ? command.id : `mandate:${command.id}`,
+            });
+        if (command.kind === "shepherd.pause" || command.kind === "shepherd.resume") {
+            const host = await deps.host(command.agent);
+            if (host.name !== command.host)
+                throw new Error("requested host does not match the configured host");
+            const matches = (await host.list()).filter(session => session.id === command.session);
+            if (matches.length !== 1)
+                throw new Error("a unique verified live terminal is required");
+            const target = { host: host.name, session: matches[0].id, cwd: matches[0].cwd ?? null, task: null };
+            return await (0, guidance_1.setShepherdSessionPause)(root, {
+                actorId, requestId: command.requestId, expectedRevision: command.expectedRevision,
+                requestFingerprint: fingerprint(command), target, paused: command.kind === "shepherd.pause",
+            }, [target]);
+        }
+        if (command.kind === "shepherd.reconcile") {
+            if (command.resolution === "delivered")
+                throw new Error("confirmed delivery is unsupported: no qualified guarded host receipt lookup is available");
+            const snapshot = (0, recovery_1.readCheckInSnapshot)(file, { limit: 1, id: command.id });
+            const entry = snapshot.entries[0];
+            if (!entry)
+                throw new Error("dispatch not found");
+            const host = await deps.host(command.agent);
+            if (host.name !== entry.host)
+                throw new Error("custody host does not match the configured host");
+            // Foreground inventories cannot prove that an older process in a surviving terminal exited.
+            if (!host.retirementInventory)
+                throw new Error("qualified complete retirement inventory is unavailable");
+            if ((await host.retirementInventory()).includes(entry.session))
+                throw new Error("terminal still exists; foreground inventory cannot prove process retirement");
+            const evidence = {
+                kind: "host_process_inventory", host: entry.host, session: entry.session, instance: entry.instance,
+                checkedAt: new Date().toISOString(), gone: true, wholeSessionRetired: true,
+            };
+            return await (0, recovery_1.reconcileShepherdDispatch)(root, { id: command.id, expectedRevision: command.expectedRevision, requestId: command.requestId, actor, evidence });
+        }
+        if (command.kind !== "shepherd.maintenance")
+            throw new Error("unsupported Shepherd administration operation");
+        const sense = await deps.senseStopped(command.agent);
+        const host = await deps.host(command.agent);
+        if (!host.retirementInventory)
+            throw new Error("qualified complete retirement inventory is unavailable");
+        const sessions = await host.retirementInventory();
+        const retiredInstances = [];
+        const seen = new Set();
+        let cursor;
+        do {
+            const page = (0, recovery_1.readMaintenanceCheckInSnapshot)(file, { limit: 200, ...(cursor ? { cursor } : {}) }, sense);
+            if (page.state !== "ready")
+                throw new Error("custody store is missing");
+            for (const entry of page.entries) {
+                if (entry.host !== host.name || sessions.includes(entry.session))
+                    continue;
+                const key = JSON.stringify([entry.host, entry.session, entry.instance]);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                retiredInstances.push({
+                    kind: "host_process_inventory", host: entry.host, session: entry.session, instance: entry.instance,
+                    checkedAt: new Date().toISOString(), gone: true, wholeSessionRetired: true,
+                });
+                if (retiredInstances.length > 200)
+                    throw new Error("maintenance exceeds 200 retired instances; narrower native retirement qualification is required");
+            }
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+        if (!path.isAbsolute(command.destination))
+            throw new Error("maintenance destination must be absolute");
+        return await (0, recovery_1.maintainShepherdCustody)(root, {
+            expectedRevision: command.expectedRevision, requestId: command.requestId, actor, sense, retiredInstances,
+            destination: command.destination, requestFingerprint: fingerprint(command),
+        });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses", level: "warn", event: "senses.shepherd_administration_failed",
+            message: "local-owner Shepherd operation failed; no inferred authority or evidence substituted",
+            meta: { operation: command.kind },
+        });
+        throw error;
+    }
+}