@ouro.bot/cli 0.1.0-alpha.97 → 0.1.0-alpha.970

package/dist/heart/shepherd/mandates.js

@@ -0,0 +1,352 @@
+"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.readShepherdMandates = readShepherdMandates;
+exports.updateShepherdMandate = updateShepherdMandate;
+exports.resolveShepherdMandate = resolveShepherdMandate;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const file_lock_1 = require("../file-lock");
+const runtime_1 = require("../../nerves/runtime");
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_LIFETIME = 7 * 86_400_000;
+const empty = () => ({ version: 1, revision: 0, mandates: [], requests: [] });
+const digest = (value) => (0, node_crypto_1.createHash)("sha256").update(value).digest("hex");
+const mandateId = (actorId, requestId) => `mandate:${digest(JSON.stringify([actorId, requestId]))}`;
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const integer = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const text = (value, max) => typeof value === "string" && value.trim().length > 0 && value.length <= max && !/[\x00-\x08\x0b-\x1f\x7f-\x9f]/.test(value);
+const identity = (value) => text(value, 200) && value === value.trim() && !/[\r\n\t]/.test(value);
+const iso = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const exactKeys = (value, required, optional = []) => required.every(key => Object.hasOwn(value, key)) && Object.keys(value).every(key => required.includes(key) || optional.includes(key));
+const canonicalProjectShape = (value) => typeof value === "string" && path.isAbsolute(value) && path.normalize(value) === value
+    && (value === path.parse(value).root || !value.endsWith(path.sep)) && !/[\x00-\x1f\x7f-\x9f]/.test(value);
+function validContext(value) {
+    return object(value) && exactKeys(value, ["kind", "actorId", "requestId"]) && value.kind === "local_owner_administration"
+        && identity(value.actorId) && identity(value.requestId);
+}
+function validProvenance(value) {
+    return object(value) && exactKeys(value, ["kind", "actorId", "requestId", "at"])
+        && validContext({ kind: value.kind, actorId: value.actorId, requestId: value.requestId }) && iso(value.at);
+}
+function validTarget(value) {
+    return object(value) && exactKeys(value, ["project"], ["host", "session", "instance"]) && canonicalProjectShape(value.project)
+        && ["host", "session", "instance"].every(key => !Object.hasOwn(value, key) || identity(value[key]))
+        && (value.session === undefined || value.host !== undefined)
+        && (value.instance === undefined || value.session !== undefined);
+}
+function validRequest(value) {
+    if (!object(value) || !validContext(value.context) || !integer(value.expectedRevision))
+        return false;
+    return value.operation === "grant"
+        ? exactKeys(value, ["operation", "context", "expectedRevision", "target", "task", "expiresAt"])
+            && validTarget(value.target) && text(value.task, 2000) && iso(value.expiresAt)
+        : value.operation === "revoke" && exactKeys(value, ["operation", "context", "expectedRevision", "mandateId"])
+            && identity(value.mandateId);
+}
+function validMandate(value) {
+    return object(value) && exactKeys(value, ["id", "revision", "target", "task", "action", "createdAt", "expiresAt", "status", "provenance", "revoked"])
+        && typeof value.id === "string" && /^mandate:[a-f0-9]{64}$/.test(value.id) && integer(value.revision) && value.revision > 0
+        && validTarget(value.target) && text(value.task, 2000) && value.action === "continue_text"
+        && iso(value.createdAt) && iso(value.expiresAt) && Date.parse(value.expiresAt) > Date.parse(value.createdAt)
+        && Date.parse(value.expiresAt) - Date.parse(value.createdAt) <= MAX_LIFETIME
+        && validProvenance(value.provenance) && value.provenance.at === value.createdAt
+        && value.id === mandateId(value.provenance.actorId, value.provenance.requestId)
+        && (value.status === "active" ? value.revoked === null : value.status === "revoked" && validProvenance(value.revoked)
+            && Date.parse(value.revoked.at) >= Date.parse(value.createdAt));
+}
+function validReceipt(value) {
+    return object(value) && exactKeys(value, ["revision", "operation", "mandateId", "provenance"])
+        && integer(value.revision) && value.revision > 0 && (value.operation === "grant" || value.operation === "revoke")
+        && typeof value.mandateId === "string" && /^mandate:[a-f0-9]{64}$/.test(value.mandateId) && validProvenance(value.provenance);
+}
+function validState(value, nowMs = Date.now()) {
+    if (!object(value) || !exactKeys(value, ["version", "revision", "mandates", "requests"])
+        || value.version !== 1 || !integer(value.revision) || !Array.isArray(value.mandates) || !Array.isArray(value.requests)
+        || !value.mandates.every(validMandate) || value.revision !== value.requests.length)
+        return false;
+    const ids = new Set(value.mandates.map(mandate => mandate.id));
+    if (ids.size !== value.mandates.length
+        || value.mandates.filter(mandate => mandate.status === "active" && Date.parse(mandate.expiresAt) > nowMs).length > 100)
+        return false;
+    const requests = new Set();
+    const grants = new Map();
+    const revocations = new Map();
+    for (const [index, request] of value.requests.entries()) {
+        if (!object(request) || !exactKeys(request, ["actorId", "requestId", "hash", "receipt"])
+            || !identity(request.actorId) || !identity(request.requestId) || typeof request.hash !== "string" || !/^[a-f0-9]{64}$/.test(request.hash)
+            || !validReceipt(request.receipt) || request.receipt.revision !== index + 1
+            || request.actorId !== request.receipt.provenance.actorId || request.requestId !== request.receipt.provenance.requestId
+            || !ids.has(request.receipt.mandateId))
+            return false;
+        const key = JSON.stringify([request.actorId, request.requestId]);
+        const operations = request.receipt.operation === "grant" ? grants : revocations;
+        if (requests.has(key) || operations.has(request.receipt.mandateId))
+            return false;
+        requests.add(key);
+        operations.set(request.receipt.mandateId, request.receipt);
+    }
+    return value.mandates.every(mandate => {
+        const grant = grants.get(mandate.id);
+        const revoked = revocations.get(mandate.id);
+        return grant && canonical(grant.provenance) === canonical(mandate.provenance)
+            && (mandate.status === "active" ? !revoked && mandate.revision === grant.revision
+                : revoked && revoked.revision > grant.revision && revoked.revision === mandate.revision
+                    && canonical(revoked.provenance) === canonical(mandate.revoked));
+    });
+}
+function owned(metadata) {
+    if (!process.getuid || metadata.uid !== process.getuid())
+        throw new Error("Shepherd mandates require current-user ownership");
+}
+function directory(candidate, privateMode, create) {
+    let metadata = fs.lstatSync(candidate, { throwIfNoEntry: false });
+    if (!metadata && create) {
+        try {
+            fs.mkdirSync(candidate, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        metadata = fs.lstatSync(candidate);
+    }
+    if (!metadata)
+        return false;
+    owned(metadata);
+    if (!metadata.isDirectory())
+        throw new Error("Shepherd mandate directory must be a directory, not a link");
+    if (privateMode ? (metadata.mode & 0o7777) !== 0o700 : (metadata.mode & 0o022) !== 0) {
+        throw new Error("Shepherd mandate directory requires 0700 mode and non-writable ancestors");
+    }
+    return true;
+}
+function storeDirectory(root, create = false) {
+    const base = path.resolve(root);
+    if (!directory(base, false, false))
+        throw new Error("Shepherd mandate bundle directory is missing");
+    let current = base;
+    for (const name of ["state", "senses", "shepherd"]) {
+        current = path.join(current, name);
+        if (!directory(current, name === "shepherd", create))
+            return null;
+    }
+    return current;
+}
+function regularFile(metadata) {
+    owned(metadata);
+    if (!metadata.isFile())
+        throw new Error("Shepherd mandates require a regular file, not a link");
+    if ((metadata.mode & 0o7777) !== 0o600)
+        throw new Error("Shepherd mandate file requires 0600 mode");
+    if (metadata.nlink !== 1)
+        throw new Error("Shepherd mandate file requires a single link");
+    if (metadata.size > MAX_BYTES)
+        throw new Error("Shepherd mandates exceed 2 MiB");
+}
+/** Missing is empty, not a grant. No read creates, repairs, or changes any filesystem entry. */
+function readShepherdMandates(agentRoot) {
+    const dir = storeDirectory(agentRoot);
+    if (!dir)
+        return empty();
+    const file = path.join(dir, "mandates.json");
+    const metadata = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!metadata)
+        return empty();
+    regularFile(metadata);
+    const handle = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    let raw;
+    try {
+        const opened = fs.fstatSync(handle);
+        regularFile(opened);
+        if (opened.ino !== metadata.ino || opened.dev !== metadata.dev)
+            throw new Error("Shepherd mandate file changed during read");
+        const bytes = Buffer.alloc(MAX_BYTES + 1);
+        let count = 0;
+        while (count < bytes.length) {
+            const received = fs.readSync(handle, bytes, count, bytes.length - count, null);
+            if (received === 0)
+                break;
+            count += received;
+        }
+        if (count > MAX_BYTES)
+            throw new Error("Shepherd mandates exceed 2 MiB");
+        raw = bytes.toString("utf8", 0, count);
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+    let state;
+    try {
+        state = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Shepherd mandates contain malformed JSON");
+    }
+    if (!validState(state))
+        throw new Error("Shepherd mandates contain an invalid or unsupported schema");
+    return state;
+}
+function requireCanonicalProject(project) {
+    try {
+        if (canonicalProjectShape(project) && fs.realpathSync.native(project) === project && fs.statSync(project).isDirectory())
+            return;
+    }
+    catch (error) {
+        if (!["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code ?? ""))
+            throw error;
+    }
+    throw new Error("Shepherd mandates require an exact existing canonical project directory");
+}
+function canonical(value) {
+    return JSON.stringify(value, (_key, item) => object(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+}
+function persist(dir, state) {
+    const snapshot = JSON.stringify(state);
+    if (Buffer.byteLength(snapshot) > MAX_BYTES)
+        throw new Error("Shepherd mandates exceed 2 MiB; no change was written");
+    const temporary = path.join(dir, `mandates.${(0, node_crypto_1.randomUUID)()}.tmp`);
+    const handle = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        fs.writeFileSync(handle, snapshot, "utf8");
+        fs.fsyncSync(handle);
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+    fs.renameSync(temporary, path.join(dir, "mandates.json"));
+    const directoryHandle = fs.openSync(dir, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(directoryHandle);
+    }
+    finally {
+        fs.closeSync(directoryHandle);
+    }
+}
+/** Caller has already validated the local-family owner; this is not exposed as an agent/browser grant tool. */
+async function updateShepherdMandate(agentRoot, request) {
+    if (!validRequest(request))
+        throw new Error("Invalid Shepherd mandate administrative request: requires canonical project, bounded task and expiry");
+    // Never hold a caller-owned mutable object across the asynchronous lock acquisition.
+    request = structuredClone(request);
+    const bodyHash = digest(canonical(request));
+    // Read before creating state so malformed existing authority is never repaired by a mutation.
+    const initial = readShepherdMandates(agentRoot);
+    const existingDir = storeDirectory(agentRoot);
+    const now = Date.now();
+    // A replay remains a replay after expiry; expiry is checked only for a new grant under the lock.
+    if (!existingDir && request.operation === "grant" && (Date.parse(request.expiresAt) <= now || Date.parse(request.expiresAt) - now > MAX_LIFETIME)) {
+        throw new Error("Shepherd mandate expiry must be in the future and within seven days");
+    }
+    if (!existingDir) {
+        if (request.operation === "revoke")
+            throw new Error("Shepherd mandate not found");
+        if (request.expectedRevision !== initial.revision)
+            throw new Error("Shepherd mandate revision conflict");
+        requireCanonicalProject(request.target.project);
+    }
+    const dir = storeDirectory(agentRoot, true);
+    return (0, file_lock_1.withFileLock)(dir, "mandates", () => {
+        const state = readShepherdMandates(agentRoot);
+        const prior = state.requests.find(item => item.actorId === request.context.actorId && item.requestId === request.context.requestId);
+        if (prior) {
+            if (prior.hash !== bodyHash)
+                throw new Error("Shepherd mandate request ID was already used with different arguments");
+            return prior.receipt;
+        }
+        if (state.revision !== request.expectedRevision)
+            throw new Error(`Shepherd mandate revision conflict: expected ${request.expectedRevision}, current ${state.revision}`);
+        const committedAt = Date.now();
+        const provenance = { ...request.context, at: new Date(committedAt).toISOString() };
+        const revision = state.revision + 1;
+        let id;
+        if (request.operation === "grant") {
+            if (Date.parse(request.expiresAt) <= committedAt || Date.parse(request.expiresAt) - committedAt > MAX_LIFETIME) {
+                throw new Error("Shepherd mandate expiry must be in the future and within seven days");
+            }
+            if (state.mandates.filter(item => item.status === "active" && Date.parse(item.expiresAt) > committedAt).length >= 100) {
+                throw new Error("Shepherd already has 100 active mandates; revoke one explicitly");
+            }
+            requireCanonicalProject(request.target.project);
+            id = mandateId(request.context.actorId, request.context.requestId);
+            state.mandates.push({
+                id, revision, target: { ...request.target }, task: request.task, action: "continue_text",
+                createdAt: provenance.at, expiresAt: request.expiresAt, status: "active", provenance, revoked: null,
+            });
+        }
+        else {
+            const mandate = state.mandates.find(item => item.id === request.mandateId);
+            if (!mandate)
+                throw new Error("Shepherd mandate not found");
+            if (mandate.status === "revoked")
+                throw new Error("Shepherd mandate is already revoked");
+            if (committedAt < Date.parse(mandate.createdAt))
+                throw new Error("Shepherd mandate clock moved before grant time; no change was written");
+            id = mandate.id;
+            mandate.status = "revoked";
+            mandate.revoked = provenance;
+            mandate.revision = revision;
+        }
+        const receipt = { revision, operation: request.operation, mandateId: id, provenance };
+        state.revision = revision;
+        state.requests.push({ actorId: request.context.actorId, requestId: request.context.requestId, hash: bodyHash, receipt });
+        persist(dir, state);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.shepherd_mandate_mutated", message: "committed a trusted Shepherd mandate revision", meta: { operation: request.operation, revision } });
+        return receipt;
+    });
+}
+function resolveShepherdMandate(state, target, nowMs) {
+    if (!validState(state, nowMs) || !Number.isFinite(nowMs))
+        return { state: "withheld", reason: "invalid_mandate_state" };
+    if (!validTarget(target))
+        return { state: "withheld", reason: "invalid_project" };
+    try {
+        requireCanonicalProject(target.project);
+    }
+    catch (error) {
+        if (error.message !== "Shepherd mandates require an exact existing canonical project directory")
+            throw error;
+        return { state: "withheld", reason: "invalid_project" };
+    }
+    const matches = state.mandates.filter(mandate => mandate.status === "active"
+        && Date.parse(mandate.createdAt) <= nowMs && Date.parse(mandate.expiresAt) > nowMs
+        && mandate.target.project === target.project
+        && ["host", "session", "instance"].every(key => mandate.target[key] === undefined || mandate.target[key] === target[key]));
+    if (matches.length !== 1)
+        return { state: "withheld", reason: matches.length ? "ambiguous_mandates" : "no_applicable_mandate" };
+    return { state: "authorized", mandate: matches[0] };
+}

package/dist/heart/shepherd/operation-commands.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shepherdInspectionCommand = shepherdInspectionCommand;
+exports.shepherdRetirementCommand = shepherdRetirementCommand;
+const safeOwner = (agent) => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent);
+const claimId = (id) => /^[a-f0-9]{64}$/.test(id);
+/** Display-only local commands; no browser action or observation is an authorization grant. */
+function shepherdInspectionCommand(agent, id) {
+    if (!safeOwner(agent) || (id !== undefined && !claimId(id)))
+        return null;
+    return id === undefined
+        ? `ouro shepherd status --agent '${agent}' --json`
+        : `ouro shepherd inspect --agent '${agent}' --id '${id}' --json`;
+}
+function shepherdRetirementCommand(agent, id, revision) {
+    if (!safeOwner(agent) || !claimId(id) || revision === null || !Number.isSafeInteger(revision) || revision < 0)
+        return null;
+    return `ouro shepherd reconcile --agent '${agent}' --id '${id}' --resolution retired --expected-revision ${revision} --request-id 'supervision-retire-${id}-r${revision}' --json`;
+}

package/dist/heart/shepherd/operations.js

@@ -0,0 +1,135 @@
+"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.SHEPHERD_ADMIN_USAGE = void 0;
+exports.parseShepherdOperation = parseShepherdOperation;
+const path = __importStar(require("node:path"));
+exports.SHEPHERD_ADMIN_USAGE = "Usage: ouro shepherd status|inspect|pause|resume|mandate grant|mandate revoke|reconcile|maintenance --agent <name> [operation options]; ouro shepherd chat --agent <name> [--session <UUID>] [--web]";
+const nonempty = (value) => !!value && value === value.trim() && value.length <= 2000 && !/[\x00-\x1f\x7f-\x9f]/.test(value);
+const absolute = (value) => path.isAbsolute(value) && path.normalize(value) === value;
+function parseShepherdOperation(args) {
+    const fail = () => { throw new Error(exports.SHEPHERD_ADMIN_USAGE); };
+    let operation = args[0];
+    let offset = 1;
+    if (operation === "mandate") {
+        operation += `.${args[1]}`;
+        offset = 2;
+    }
+    const mutation = !["status", "inspect"].includes(operation ?? "");
+    const operationFlags = {
+        status: [], inspect: ["id", "cursor", "limit"],
+        pause: ["host", "session"], resume: ["host", "session"],
+        "mandate.grant": ["project", "task", "expires-at", "host", "session", "instance"],
+        "mandate.revoke": ["id"], reconcile: ["id", "resolution"], maintenance: ["destination"],
+    };
+    if (!operation || !Object.hasOwn(operationFlags, operation))
+        return fail();
+    const allowed = new Set(["agent", "json", ...operationFlags[operation], ...(mutation ? ["expected-revision", "request-id"] : [])]);
+    const values = new Map();
+    for (let i = offset; i < args.length; i++) {
+        const flag = args[i];
+        const key = flag.slice(2);
+        if (!flag.startsWith("--") || !allowed.has(key) || values.has(key))
+            return fail();
+        if (key === "json") {
+            values.set(key, "true");
+            continue;
+        }
+        const value = args[++i];
+        if (!nonempty(value) || value.startsWith("--"))
+            return fail();
+        values.set(key, value);
+    }
+    const required = (key) => values.get(key) ?? fail();
+    const integer = (key, fallback) => {
+        const value = values.get(key);
+        if (value === undefined && fallback !== undefined)
+            return fallback;
+        if (!value || !/^(0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value)))
+            return fail();
+        return Number(value);
+    };
+    const agent = required("agent");
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent))
+        return fail();
+    const common = { agent, ...(values.has("json") ? { json: true } : {}) };
+    const host = () => {
+        const value = required("host");
+        return value === "cmux" || value === "herdr" || value === "copilot-app" ? value : fail();
+    };
+    if (operation === "status")
+        return { kind: "shepherd.status", ...common };
+    const id = () => {
+        const value = required("id");
+        if (!(operation === "mandate.revoke" ? /^mandate:[a-f0-9]{64}$|^[a-f0-9]{64}$/ : /^[a-f0-9]{64}$/).test(value))
+            return fail();
+        return value;
+    };
+    if (operation === "inspect") {
+        const limit = integer("limit", 50);
+        if (limit < 1 || limit > 200 || (values.has("id") && values.has("cursor")))
+            return fail();
+        return { kind: "shepherd.inspect", ...common, limit, ...(values.has("id") ? { id: id() } : {}), ...(values.has("cursor") ? { cursor: required("cursor") } : {}) };
+    }
+    const admin = { ...common, expectedRevision: integer("expected-revision"), requestId: required("request-id") };
+    if (admin.requestId.length > 200)
+        return fail();
+    if (operation === "pause" || operation === "resume")
+        return { kind: `shepherd.${operation}`, ...admin, host: host(), session: required("session") };
+    if (operation === "mandate.revoke")
+        return { kind: "shepherd.mandate.revoke", ...admin, id: id() };
+    if (operation === "reconcile") {
+        const resolution = required("resolution");
+        if (resolution !== "delivered" && resolution !== "retired")
+            return fail();
+        return { kind: "shepherd.reconcile", ...admin, id: id(), resolution };
+    }
+    if (operation === "maintenance") {
+        const destination = required("destination");
+        if (!absolute(destination))
+            return fail();
+        return { kind: "shepherd.maintenance", ...admin, destination };
+    }
+    const project = required("project");
+    const expiresAt = required("expires-at");
+    if (!absolute(project) || !Number.isFinite(Date.parse(expiresAt)) || new Date(expiresAt).toISOString() !== expiresAt
+        || (values.has("session") && !values.has("host")) || (values.has("instance") && !values.has("session")))
+        return fail();
+    return {
+        kind: "shepherd.mandate.grant", ...admin, project, task: required("task"), expiresAt,
+        ...(values.has("host") ? { host: host() } : {}), ...(values.has("session") ? { session: required("session") } : {}),
+        ...(values.has("instance") ? { instance: required("instance") } : {}),
+    };
+}

package/dist/heart/shepherd/supervision.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHEPHERD_SUPERVISION_SOURCES = exports.SHEPHERD_ALPHA_AUTOMATION_WARNING = exports.SHEPHERD_OBSERVATION_MAX_BYTES = exports.SHEPHERD_OBSERVATION_FILE = exports.SHEPHERD_SUPERVISION_STALE_MS = exports.SHEPHERD_SUPERVISION_LIMIT = void 0;
+exports.buildShepherdSupervisionView = buildShepherdSupervisionView;
+exports.isShepherdSupervisionSnapshot = isShepherdSupervisionSnapshot;
+exports.SHEPHERD_SUPERVISION_LIMIT = 200;
+exports.SHEPHERD_SUPERVISION_STALE_MS = 30_000;
+exports.SHEPHERD_OBSERVATION_FILE = "supervision-observation.json";
+exports.SHEPHERD_OBSERVATION_MAX_BYTES = 2 * 1024 * 1024;
+exports.SHEPHERD_ALPHA_AUTOMATION_WARNING = "This alpha retains unqualified legacy automation. Legacy immediate/network automation may still type text without mandate enforcement. Automatic keys are refused. Absent or revoked mandates do not disable those text paths. Disable Shepherd to stop legacy automation.";
+exports.SHEPHERD_SUPERVISION_SOURCES = ["host", "guidance", "mandates", "returns", "custody", "notices"];
+function freshness(at, nowMs) {
+    const ageMs = at === null ? NaN : nowMs - Date.parse(at);
+    return !Number.isFinite(ageMs) || ageMs < 0
+        ? { status: "unknown", observedAt: at, ageMs: null }
+        : { status: ageMs > exports.SHEPHERD_SUPERVISION_STALE_MS ? "stale" : "fresh", observedAt: at, ageMs };
+}
+/** Observation is not authority; aging may only weaken current claims, never promote them. */
+function buildShepherdSupervisionView(snapshot, nowMs) {
+    const current = freshness(snapshot.observedAt, nowMs);
+    const hostAvailable = snapshot.sourceHealth.host === "ok" && current.status !== "unknown";
+    const sessions = snapshot.sessions.items.map(row => {
+        const observed = freshness(row.observedAt, nowMs);
+        const fresh = hostAvailable && current.status === "fresh" && observed.status === "fresh";
+        return {
+            ...row,
+            freshness: observed,
+            activity: fresh ? row.activity : "unknown",
+            authority: fresh && snapshot.sourceHealth.mandates === "ok" && snapshot.sourceHealth.guidance === "ok"
+                ? row.authority : "unknown",
+            capability: fresh ? row.capability : "unknown",
+            lastDecisionLabel: row.lastDecision === "done" ? "Agent reports finished" : row.lastDecision,
+        };
+    });
+    const counts = hostAvailable ? { working: 0, idle: 0, shell: 0, unknown: 0 } : null;
+    if (counts)
+        for (const row of sessions)
+            counts[row.activity] += 1;
+    return {
+        schemaVersion: 1,
+        agentName: snapshot.agentName,
+        freshness: current,
+        health: snapshot.sourceErrors.length || Object.values(snapshot.sourceHealth).some(value => value !== "ok") ? "degraded" : "ok",
+        sourceHealth: { ...snapshot.sourceHealth },
+        counts,
+        sessions: { ...snapshot.sessions, items: sessions },
+        timeline: { ...snapshot.timeline, items: snapshot.timeline.items.map(event => ({
+                ...event, summary: event.kind === "judgment" && event.summary === "done" ? "Agent reports finished" : event.summary,
+            })) },
+        custody: { ...snapshot.custody, claims: { ...snapshot.custody.claims, items: snapshot.custody.claims.items.map(claim => ({ ...claim })) } },
+        sourceErrors: snapshot.sourceErrors.map(error => ({ ...error })),
+    };
+}
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const exact = (value, keys) => Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const text = (value) => typeof value === "string" && value.length > 0 && value.length <= 2000 && !/[\x00-\x1f\x7f-\x9f\u2028\u2029]/.test(value);
+const nullableText = (value) => value === null || text(value);
+const date = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+const oneOf = (value, values) => typeof value === "string" && values.includes(value);
+const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function validPage(value, validItem) {
+    return object(value) && exact(value, ["totalCount", "truncated", "items"])
+        && (value.totalCount === null || count(value.totalCount)) && typeof value.truncated === "boolean"
+        && Array.isArray(value.items) && value.items.length <= exports.SHEPHERD_SUPERVISION_LIMIT && value.items.every(validItem)
+        && (value.totalCount === null ? value.truncated : value.totalCount >= value.items.length
+            && value.truncated === (value.totalCount > value.items.length));
+}
+function validSession(value) {
+    return object(value) && exact(value, ["host", "session", "instance", "label", "harness", "project", "activity",
+        "observedAt", "lastDecision", "lastAction", "lastReason", "lastActionAt", "withheldReason", "authority", "capability"])
+        && text(value.host) && text(value.session) && nullableText(value.instance) && text(value.label)
+        && nullableText(value.harness) && nullableText(value.project) && nullableText(value.lastDecision) && nullableText(value.withheldReason)
+        && (value.lastAction === null || oneOf(value.lastAction, ["respond", "let_through"])) && nullableText(value.lastReason)
+        && (value.lastActionAt === null || date(value.lastActionAt))
+        && (value.observedAt === null || date(value.observedAt)) && oneOf(value.activity, ["working", "idle", "shell", "unknown"])
+        && oneOf(value.authority, ["active", "absent", "paused", "ambiguous", "unknown"])
+        && oneOf(value.capability, ["supported", "unsupported", "unknown"]);
+}
+function validEvent(value) {
+    return object(value) && exact(value, ["id", "host", "session", "instance", "at", "kind", "summary"])
+        && text(value.id) && text(value.host) && text(value.session) && nullableText(value.instance) && date(value.at) && text(value.summary)
+        && oneOf(value.kind, ["observation", "judgment", "input_admitted", "legacy_input_reported", "input_unknown", "notification_queued",
+            "notification_delivered", "notification_unknown", "recovery"]);
+}
+function validClaim(value) {
+    return object(value) && exact(value, ["id", "host", "session", "instance", "state", "claimedAt", "reason", "retired"])
+        && typeof value.id === "string" && /^[a-f0-9]{64}$/.test(value.id)
+        && text(value.host) && text(value.session) && nullableText(value.instance) && date(value.claimedAt)
+        && nullableText(value.reason) && typeof value.retired === "boolean" && oneOf(value.state, ["claimed", "sent", "not_sent", "unknown"]);
+}
+function isShepherdSupervisionSnapshot(value) {
+    if (!object(value) || !exact(value, ["schemaVersion", "agentName", "observedAt", "sourceHealth", "sessions", "timeline", "custody", "sourceErrors"])
+        || value.schemaVersion !== 1 || typeof value.agentName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(value.agentName)
+        || !date(value.observedAt) || !object(value.sourceHealth)
+        || !exact(value.sourceHealth, [...exports.SHEPHERD_SUPERVISION_SOURCES])
+        || !Object.values(value.sourceHealth).every(health => oneOf(health, ["ok", "missing", "error"]))
+        || !validPage(value.sessions, validSession) || !validPage(value.timeline, validEvent)
+        || !object(value.custody) || !exact(value.custody, ["revision", "bytes", "capacity", "claims"])
+        || !(value.custody.revision === null || count(value.custody.revision))
+        || !(value.custody.bytes === null || count(value.custody.bytes))
+        || !oneOf(value.custody.capacity, ["normal", "warning", "refused", "unknown"])
+        || !validPage(value.custody.claims, validClaim)
+        || !Array.isArray(value.sourceErrors) || value.sourceErrors.length > 50
+        || !value.sourceErrors.every(error => object(error) && exact(error, ["source", "code", "detail"])
+            && oneOf(error.source, [...exports.SHEPHERD_SUPERVISION_SOURCES, "replica"]) && text(error.code) && text(error.detail)))
+        return false;
+    const sessions = value.sessions;
+    const timeline = value.timeline;
+    const observedAt = value.observedAt;
+    return new Set(sessions.items.map(row => JSON.stringify([row.host, row.session]))).size === sessions.items.length
+        && new Set(timeline.items.map(event => event.id)).size === timeline.items.length
+        && new Set(value.custody.claims.items.map(claim => claim.id)).size === value.custody.claims.items.length
+        && sessions.items.every(row => row.observedAt === null || Date.parse(row.observedAt) <= Date.parse(observedAt));
+}

package/dist/heart/shepherd/types.js

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