@ouro.bot/cli 0.1.0-alpha.9 → 0.1.0-alpha.900

package/dist/repertoire/relationship-authorization.js

@@ -0,0 +1,322 @@
+"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.routineActionRequester = routineActionRequester;
+exports.authorizeRestartApprovalRequester = authorizeRestartApprovalRequester;
+exports.authorizeRoutineActionRequester = authorizeRoutineActionRequester;
+exports.renderRelationshipPreferences = renderRelationshipPreferences;
+exports.withRelationshipPreference = withRelationshipPreference;
+exports.loadRelationshipCapabilityRegistry = loadRelationshipCapabilityRegistry;
+exports.relationshipSubjectFromFriend = relationshipSubjectFromFriend;
+exports.createRelationshipAuthorizationEvaluator = createRelationshipAuthorizationEvaluator;
+exports.resolveProfileScopedRelationshipAuthorization = resolveProfileScopedRelationshipAuthorization;
+exports.authorizeRelationshipAccess = authorizeRelationshipAccess;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_util_1 = require("node:util");
+const router_1 = require("../heart/external-events/router");
+const runtime_1 = require("../nerves/runtime");
+function routineActionRequester(ctx, eventTarget) {
+    const relationship = ctx?.relationshipAuthorization;
+    if (!relationship)
+        return null;
+    if (ctx?.currentExternalEvent) {
+        if (!eventTarget || relationship.profileId !== "sanctuary-event")
+            return null;
+        const events = [ctx.currentExternalEvent, ...(ctx.currentExternalEvent.relatedEvents ?? [])].filter((event) => event.schemaVersion === 1 && event.source === "sanctuary-health" && event.eventId === `container:${eventTarget.target.id}:availability`);
+        if (events.length !== 1)
+            return null;
+        const event = events[0];
+        return {
+            kind: "owner_event", friendId: eventTarget.friendId, profileId: relationship.profileId,
+            event: { schemaVersion: 1, recordPath: event.recordPath, agent: event.agent, source: event.source, eventId: event.eventId, generation: event.generation, observationRevision: event.observationRevision, claimOwner: event.claimOwner },
+            target: { ...eventTarget.target },
+        };
+    }
+    const actor = relationship.actor;
+    const session = ctx?.currentSession;
+    if (!actor || !session || session.channel !== "telegram" || session.friendId !== actor.friendId
+        || [actor.friendId, actor.sessionEventId, relationship.requestId, session.key].some((value) => typeof value !== "string" || !value.trim()))
+        return null;
+    const kind = actor.trustLevel === "family" && relationship.profileId === "sanctuary-owner" ? "owner"
+        : actor.trustLevel === "friend" && relationship.profileId === "sanctuary-household" ? "household_request" : null;
+    if (!kind)
+        return null;
+    return { kind, friendId: actor.friendId, profileId: relationship.profileId, requestId: relationship.requestId, sessionEventId: actor.sessionEventId, origin: { friendId: session.friendId, channel: session.channel, key: session.key } };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function authorizeRestartApprovalRequester(ctx, args, binding) {
+    return authorizeRoutineActionRequester(ctx, args, {
+        requester: {
+            kind: "owner", friendId: binding.friendId, profileId: "sanctuary-owner", requestId: binding.requestId,
+            sessionEventId: binding.sessionEventId, origin: { friendId: binding.friendId, channel: "telegram", key: binding.sessionKey },
+        },
+        profileVersion: binding.profileVersion,
+    });
+}
+async function authorizeRoutineActionRequester(ctx, args, expected) {
+    if (!isRecord(args) || Object.keys(args).length !== 1 || typeof args.container !== "string"
+        || !args.container || args.container !== args.container.trim() || Buffer.byteLength(args.container) > 128 || args.container.includes("\uFFFD")
+        || !ctx?.agentRoot || !ctx.relationshipAuthorization)
+        return { allowed: false, reason: "routine action requires one exact target and current relationship" };
+    const target = args.container;
+    const agentRoot = ctx.agentRoot;
+    const relationship = ctx.relationshipAuthorization;
+    const sanctuary = ctx.sanctuary;
+    const initialRequester = routineActionRequester(ctx);
+    const event = ctx.currentExternalEvent && structuredClone(ctx.currentExternalEvent);
+    if (!initialRequester && (!event || event.source !== "sanctuary-health" || relationship.profileId !== "sanctuary-event"))
+        return { allowed: false, reason: "routine action requires a current human request or health event" };
+    const unchanged = () => ctx.agentRoot === agentRoot && ctx.relationshipAuthorization === relationship && ctx.sanctuary === sanctuary
+        && args.container === target && Object.keys(args).length === 1
+        && (0, node_util_1.isDeepStrictEqual)(initialRequester, routineActionRequester(ctx)) && (0, node_util_1.isDeepStrictEqual)(event, ctx.currentExternalEvent);
+    let authorization;
+    try {
+        authorization = await relationship.authorizeTool("unraid_restart_container", { container: target });
+    }
+    catch {
+        return { allowed: false, reason: "routine relationship authorization is unavailable" };
+    }
+    if (!authorization?.allowed)
+        return { allowed: false, reason: authorization?.allowed === false ? authorization.reason : "routine relationship authorization is unavailable" };
+    if (typeof authorization.profileVersion !== "number" || !Number.isSafeInteger(authorization.profileVersion) || authorization.profileVersion < 1
+        || typeof authorization.receiptId !== "string" || !authorization.receiptId.trim())
+        return { allowed: false, reason: "routine relationship authorization is not versioned" };
+    if (expected && authorization.profileVersion !== expected.profileVersion)
+        return { allowed: false, reason: "routine relationship profile version changed" };
+    if (!unchanged() || (authorization.profileId !== undefined && authorization.profileId !== relationship.profileId))
+        return { allowed: false, reason: "routine request binding changed during authorization" };
+    if (!event) {
+        if (!initialRequester || initialRequester.kind === "owner_event"
+            || (authorization.friendId !== undefined && authorization.friendId !== initialRequester.friendId)
+            || (authorization.requestId !== undefined && authorization.requestId !== initialRequester.requestId)
+            || (expected && !(0, node_util_1.isDeepStrictEqual)(expected.requester, initialRequester)))
+            return { allowed: false, reason: "routine request binding does not match live authorization" };
+        return { allowed: true, requester: initialRequester, receiptId: authorization.receiptId, profileVersion: authorization.profileVersion };
+    }
+    if (!sanctuary || authorization.profileId !== "sanctuary-event" || typeof authorization.friendId !== "string" || !authorization.friendId.trim())
+        return { allowed: false, reason: "current health event authorization is unavailable" };
+    let eventTarget;
+    if (expected) {
+        if (expected.requester.kind !== "owner_event" || expected.requester.target.name !== target)
+            return { allowed: false, reason: "current health event target binding changed" };
+        eventTarget = expected.requester.target;
+    }
+    else {
+        let listed;
+        try {
+            listed = await sanctuary.listContainers();
+        }
+        catch {
+            return { allowed: false, reason: "current health event container status is unavailable" };
+        }
+        if (!isRecord(listed) || listed.ok !== true || !isRecord(listed.data) || listed.data.truncated !== false || !Array.isArray(listed.data.containers))
+            return { allowed: false, reason: "current health event container status is invalid" };
+        const matches = listed.data.containers.filter((value) => isRecord(value) && value.name === target);
+        const container = matches[0];
+        if (matches.length !== 1 || !container || typeof container.id !== "string" || !container.id.trim()
+            || container.state !== "exited" || container.degraded !== false)
+            return { allowed: false, reason: "current health event target is not exactly stopped" };
+        eventTarget = { id: container.id, name: target };
+    }
+    const requester = routineActionRequester(ctx, { friendId: authorization.friendId, target: eventTarget });
+    if (!requester || requester.kind !== "owner_event" || !unchanged() || (expected && !(0, node_util_1.isDeepStrictEqual)(expected.requester, requester)))
+        return { allowed: false, reason: "current health event target or request binding changed" };
+    let current;
+    try {
+        current = (0, router_1.readExternalEventRecord)(requester.event.recordPath);
+    }
+    catch {
+        return { allowed: false, reason: "current health event record is unavailable" };
+    }
+    const lease = requester.event;
+    if (current.agent !== lease.agent || current.source !== lease.source || current.eventId !== lease.eventId || current.eventType !== "health.observed"
+        || current.generation !== lease.generation || current.observationRevision !== lease.observationRevision || current.claimOwner !== lease.claimOwner
+        || current.executionState !== "running" || !(Date.parse(current.claimExpiresAt ?? "") > Date.now())
+        || current.transition === "recovered" || current.pendingObservation !== null)
+        return { allowed: false, reason: "current health event claim or observation changed" };
+    return { allowed: true, requester, receiptId: authorization.receiptId, profileVersion: authorization.profileVersion };
+}
+function renderRelationshipPreferences(friend) {
+    const now = Date.now();
+    return Object.entries(friend.relationshipPolicy?.preferences ?? {})
+        .filter(([, preference]) => !preference.expiresAt || Date.parse(preference.expiresAt) > now)
+        .slice(0, 20)
+        .map(([category, preference]) => `- source=${preference.source}; provenance=${preference.provenance}; category=${category}; value=${String(preference.value).replace(/\s+/gu, " ").trim().slice(0, 500)}; version=${preference.version}; precedence=current${preference.expiresAt ? `; expires=${preference.expiresAt}` : ""}`);
+}
+function withRelationshipPreference(friend, input) {
+    const current = friend.relationshipPolicy ?? { schemaVersion: 1, version: 0, preferences: {} };
+    const previous = current.preferences[input.category];
+    return {
+        ...friend,
+        relationshipPolicy: {
+            schemaVersion: 1,
+            version: current.version + 1,
+            preferences: { ...current.preferences, [input.category]: { value: input.value, provenance: input.provenance, source: input.source, version: (previous?.version ?? 0) + 1 } },
+        },
+        updatedAt: new Date().toISOString(),
+    };
+}
+const deny = (reason) => ({ allowed: false, reason });
+function authorizationReceipt(value) {
+    return `relationship-${(0, node_crypto_1.createHash)("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function stringList(value, label) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || !entry.trim()))
+        throw new Error(`${label} must be a string array`);
+    return [...new Set(value)];
+}
+function loadRelationshipCapabilityRegistry(agentRoot) {
+    const filePath = path.join(agentRoot, "tool-profiles.json");
+    const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (raw.version !== 2 || !raw.profiles || typeof raw.profiles !== "object" || Array.isArray(raw.profiles))
+        throw new Error("relationship capability registry version 2 is required");
+    const profiles = {};
+    for (const [id, value] of Object.entries(raw.profiles)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`relationship capability profile ${id} is invalid`);
+        const candidate = value;
+        if (!Number.isInteger(candidate.version) || Number(candidate.version) < 1)
+            throw new Error(`relationship capability profile ${id} version is invalid`);
+        profiles[id] = {
+            id,
+            version: Number(candidate.version),
+            contextScopes: stringList(candidate.contextScopes, `${id}.contextScopes`),
+            toolNames: stringList(candidate.toolNames, `${id}.toolNames`),
+            effectScopes: stringList(candidate.effectScopes, `${id}.effectScopes`),
+        };
+    }
+    return { version: 2, profiles };
+}
+function relationshipSubjectFromFriend(friend) {
+    return {
+        friendId: friend.id,
+        trustLevel: friend.trustLevel ?? "stranger",
+        admissionState: friend.admissionState ?? "unverified",
+        initiativePolicy: friend.initiativePolicy ?? "none",
+        ...(friend.capabilityProfileId ? { capabilityProfileId: friend.capabilityProfileId } : {}),
+    };
+}
+function createRelationshipAuthorizationEvaluator(input) {
+    const subject = relationshipSubjectFromFriend(input.friend);
+    const relationshipProfile = subject.capabilityProfileId ? input.registry.profiles[subject.capabilityProfileId] : undefined;
+    const turnProfile = input.profileId ? input.registry.profiles[input.profileId] : relationshipProfile;
+    const profile = relationshipProfile && turnProfile
+        ? {
+            id: turnProfile.id,
+            version: turnProfile.version,
+            contextScopes: turnProfile.contextScopes.filter((scope) => relationshipProfile.contextScopes.includes(scope)),
+            toolNames: turnProfile.toolNames.filter((name) => relationshipProfile.toolNames.includes(name)),
+            effectScopes: turnProfile.effectScopes.filter((scope) => relationshipProfile.effectScopes.includes(scope)),
+        }
+        : undefined;
+    const effectiveSubject = { ...subject, ...(profile ? { capabilityProfileId: profile.id } : {}) };
+    const profiles = profile ? [profile] : [];
+    const evaluate = (request) => authorizeRelationshipAccess({
+        relationship: effectiveSubject,
+        profiles,
+        request,
+        activeRequestId: input.requestId,
+        requestPhase: input.requestPhase,
+    });
+    const advertisedToolNames = profile?.toolNames.filter((name) => evaluate({ kind: "tool", name, ...(input.requestId ? { requestId: input.requestId, returnTargetFriendId: subject.friendId } : {}) }).allowed) ?? [];
+    const authorizedContextScopes = profile?.contextScopes.filter((scope) => evaluate({ kind: "context", scope }).allowed) ?? [];
+    return {
+        subject,
+        ...(profile ? { profileId: profile.id } : {}),
+        authorizedContextScopes,
+        advertisedToolNames,
+        ...(input.sessionEventId ? { actor: { friendId: subject.friendId, trustLevel: subject.trustLevel, sessionEventId: input.sessionEventId } } : {}),
+        authorizeContext: (scope) => evaluate({ kind: "context", scope }),
+        authorizeTool: (name) => evaluate({ kind: "tool", name, ...(input.requestId ? { requestId: input.requestId, returnTargetFriendId: subject.friendId } : {}) }),
+        authorizeEffect: (scope) => evaluate({ kind: "effect", scope, ...(input.requestId ? { requestId: input.requestId, returnTargetFriendId: subject.friendId } : {}) }),
+    };
+}
+async function resolveProfileScopedRelationshipAuthorization(input) {
+    const friends = await input.store.listAll?.() ?? [];
+    const matches = friends.filter((friend) => friend.capabilityProfileId === input.relationshipProfileId);
+    if (matches.length !== 1)
+        throw new Error(`relationship profile ${input.relationshipProfileId} must resolve to exactly one Friend`);
+    return createRelationshipAuthorizationEvaluator({
+        friend: matches[0],
+        registry: input.registry,
+        ...(input.profileId ? { profileId: input.profileId } : {}),
+        ...(input.requestId ? { requestId: input.requestId } : {}),
+        ...(input.requestPhase ? { requestPhase: input.requestPhase } : {}),
+        ...(input.sessionEventId ? { sessionEventId: input.sessionEventId } : {}),
+    });
+}
+function authorizeRelationshipAccess(input) {
+    if (input.request.kind === "admission_gate") {
+        const pending = input.pendingAdmission;
+        const now = Date.parse(input.now ?? new Date().toISOString());
+        if (!pending || pending.admissionId !== input.request.admissionId || pending.botId !== input.request.botId || pending.userId !== input.request.userId || pending.chatId !== input.request.chatId || pending.expiresAt !== input.request.expiresAt || now >= Date.parse(input.request.expiresAt) || input.request.idempotencyKey !== `ack:${input.request.admissionId}`) {
+            return deny("admission gate authorization does not match a current pending admission");
+        }
+        (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.relationship_authorized", message: "authorized fixed admission gate acknowledgement", meta: { authorizationKind: "admission_gate", admissionId: input.request.admissionId } });
+        return { allowed: true, authorizationKind: "admission_gate", receiptId: authorizationReceipt(input.request), admissionId: input.request.admissionId, idempotencyKey: input.request.idempotencyKey, expiresAt: input.request.expiresAt };
+    }
+    const relationship = input.relationship;
+    if (!relationship || relationship.admissionState !== "active")
+        return deny("relationship admission is not active");
+    if (relationship.trustLevel !== "friend" && relationship.trustLevel !== "family")
+        return deny("relationship trust is insufficient");
+    const profile = input.profiles.find((candidate) => candidate.id === relationship.capabilityProfileId);
+    if (!profile || !Number.isInteger(profile.version) || profile.version < 1)
+        return deny("relationship capability profile is missing or stale");
+    if (input.request.kind === "context" && !profile.contextScopes.includes(input.request.scope))
+        return deny("context scope is not authorized by the relationship profile");
+    if (input.request.kind === "tool" && !profile.toolNames.includes(input.request.name))
+        return deny("tool is not authorized by the relationship profile");
+    if (input.request.kind === "effect" && !profile.effectScopes.includes(input.request.scope))
+        return deny("effect is not authorized by the relationship profile");
+    const requestId = input.request.kind === "context" ? undefined : input.request.requestId;
+    const returnTarget = input.request.kind === "context" ? undefined : input.request.returnTargetFriendId;
+    if (relationship.initiativePolicy === "none")
+        return deny("initiative policy denies contact");
+    if (relationship.initiativePolicy === "reactive_only" && input.request.kind !== "context") {
+        if (input.requestPhase !== "inbound" || !requestId || requestId !== input.activeRequestId || returnTarget !== relationship.friendId)
+            return deny("initiative policy is reactive only");
+    }
+    if (relationship.initiativePolicy === "request_follow_up_only" && input.request.kind !== "context") {
+        if (!requestId || requestId !== input.activeRequestId || returnTarget !== relationship.friendId)
+            return deny("initiative policy requires the matching active request and return target");
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.relationship_authorized", message: "authorized relationship access", meta: { authorizationKind: "relationship", friendId: relationship.friendId, profileId: profile.id, profileVersion: profile.version, requestKind: input.request.kind } });
+    return { allowed: true, authorizationKind: "relationship", receiptId: authorizationReceipt({ relationship, request: input.request, activeRequestId: input.activeRequestId, requestPhase: input.requestPhase, profile }), friendId: relationship.friendId, profileId: profile.id, profileVersion: profile.version, requestId: requestId ?? null };
+}

package/dist/repertoire/sanctuary-container-policy.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOPPED_ON_PURPOSE_NOTE = exports.SERVICE_CONTAINERS = void 0;
+exports.desiredContainerState = desiredContainerState;
+exports.annotateContainers = annotateContainers;
+const runtime_1 = require("../nerves/runtime");
+/** House service name to the one container that is that service. */
+exports.SERVICE_CONTAINERS = { Books: "calibre-web" };
+const WANTED_ON = new Set(["on", "always_on", "expected_on"]);
+const WANTED_OFF = /^(?:off|disabled|paused|intentionally_off|intentionally_paused)$/u;
+exports.STOPPED_ON_PURPOSE_NOTE = "stopped on purpose by the steward policy; not needed by any running service; do not offer to start";
+/** The policy's current desired state for a container, or null when the policy says nothing (or the entry expired). */
+function desiredContainerState(policy, name, nowMs) {
+    const entry = policy?.desiredStates[`container:${name}`];
+    if (!entry)
+        return null;
+    const expires = entry.expiresAt ? Date.parse(entry.expiresAt) : Number.NaN;
+    if (Number.isFinite(expires) && expires <= nowMs)
+        return null;
+    const value = entry.value.trim().toLowerCase();
+    if (WANTED_ON.has(value))
+        return "running";
+    if (WANTED_OFF.test(value))
+        return "stopped";
+    return null;
+}
+/** Adds `desired`, `note` and `serves` to each container of an ok container-list result; any other result is returned unchanged. */
+function annotateContainers(result, policy, nowMs) {
+    const value = result;
+    if (!value || value.ok !== true || !Array.isArray(value.data?.containers))
+        return result;
+    (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.sanctuary_container_policy_annotated", message: "annotated the container list with steward-policy desired state", meta: { containers: value.data.containers.length, policyRead: policy !== null } });
+    const services = Object.entries(exports.SERVICE_CONTAINERS);
+    const containers = value.data.containers.map((entry) => {
+        const item = entry;
+        const name = typeof item.name === "string" ? item.name : "";
+        const desired = desiredContainerState(policy, name, nowMs);
+        const service = services.find(([, container]) => container === name)?.[0];
+        const running = item.state === "running";
+        const note = desired === "stopped"
+            ? (running ? "the steward policy wants this stopped but it is running; tell the owner, do not stop it yourself" : exports.STOPPED_ON_PURPOSE_NOTE)
+            : desired === "running" && !running ? "the steward policy wants this running but it is not" : undefined;
+        return { ...entry, ...(desired ? { desired } : {}), ...(note ? { note } : {}), ...(service ? { serves: service } : {}) };
+    });
+    return { ...result, data: { ...value.data, containers } };
+}

package/dist/repertoire/shell-sessions.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnBackgroundShell = spawnBackgroundShell;
+exports.getShellSession = getShellSession;
+exports.listShellSessions = listShellSessions;
+exports.tailShellSession = tailShellSession;
+exports.resetShellSessions = resetShellSessions;
+exports.detectDestructivePatterns = detectDestructivePatterns;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const runtime_1 = require("../nerves/runtime");
+const sessions = new Map();
+const MAX_OUTPUT_LINES = 200;
+function spawnBackgroundShell(command, owner) {
+    const id = (0, crypto_1.randomUUID)();
+    const proc = (0, child_process_1.spawn)("sh", ["-c", command], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const session = {
+        owner: Object.freeze({ ...owner }),
+        process: proc,
+        info: {
+            id,
+            command,
+            status: "running",
+            exitCode: null,
+            pid: proc.pid,
+            startedAt: Date.now(),
+            output: [],
+        },
+    };
+    const appendOutput = (data) => {
+        const lines = data.toString().split("\n");
+        for (const line of lines) {
+            if (line.length > 0 || session.info.output.length > 0) {
+                session.info.output.push(line);
+            }
+        }
+        // Keep only the last MAX_OUTPUT_LINES
+        if (session.info.output.length > MAX_OUTPUT_LINES) {
+            session.info.output = session.info.output.slice(-MAX_OUTPUT_LINES);
+        }
+    };
+    proc.stdout?.on("data", appendOutput);
+    proc.stderr?.on("data", appendOutput);
+    proc.on("close", (code) => {
+        session.info.status = "exited";
+        session.info.exitCode = code;
+        (0, runtime_1.emitNervesEvent)({
+            component: "repertoire",
+            event: "repertoire.shell.process_exit",
+            message: "background shell process exited",
+            meta: { id, command, exitCode: code, pid: proc.pid },
+        });
+    });
+    sessions.set(id, session);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.shell.spawn",
+        message: "spawned background shell session",
+        meta: { id, command, pid: proc.pid },
+    });
+    return { ...session.info };
+}
+function getShellSession(id, owner) {
+    const session = sessions.get(id);
+    if (!session || session.owner.agentName !== owner.agentName || session.owner.agentRoot !== owner.agentRoot)
+        return undefined;
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.shell.status_check",
+        message: "checked shell session status",
+        meta: { id, status: session.info.status, exitCode: session.info.exitCode },
+    });
+    return { ...session.info };
+}
+function listShellSessions(owner) {
+    return Array.from(sessions.values()).filter((session) => session.owner.agentName === owner.agentName && session.owner.agentRoot === owner.agentRoot).map((s) => ({
+        id: s.info.id,
+        command: s.info.command,
+        status: s.info.status,
+        exitCode: s.info.exitCode,
+        pid: s.info.pid,
+        startedAt: s.info.startedAt,
+        output: [], // Don't include full output in listing
+    }));
+}
+function tailShellSession(id, owner, lines = 50) {
+    const session = sessions.get(id);
+    if (!session || session.owner.agentName !== owner.agentName || session.owner.agentRoot !== owner.agentRoot)
+        return undefined;
+    const tail = session.info.output.slice(-lines);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.shell.tail",
+        message: "tailed shell session output",
+        meta: { id, requestedLines: lines, returnedLines: tail.length },
+    });
+    return tail.join("\n");
+}
+/** Reset all sessions (for testing) */
+function resetShellSessions() {
+    for (const session of sessions.values()) {
+        if (session.info.status === "running") {
+            session.process.kill();
+        }
+    }
+    sessions.clear();
+}
+const DESTRUCTIVE_PATTERNS = [
+    { name: "rm -rf root/home", regex: /rm\s+-rf\s+[/~]/ },
+    { name: "git push --force", regex: /git\s+push\s+--force/ },
+    { name: "git reset --hard", regex: /git\s+reset\s+--hard/ },
+    { name: "git clean -f", regex: /git\s+clean\s+-f/ },
+    { name: "git branch -D", regex: /git\s+branch\s+-D/ },
+    { name: "fork bomb", regex: /:\(\)\s*\{/ },
+    { name: "write to raw device", regex: />\s*\/dev\/sd/ },
+    { name: "git checkout .", regex: /git\s+checkout\s+\./ },
+    { name: "git stash drop", regex: /git\s+stash\s+drop/ },
+];
+/**
+ * Detect destructive patterns in a shell command.
+ * Returns list of matched pattern names. Empty array = safe.
+ * This is a friction layer, not a hard block.
+ */
+function detectDestructivePatterns(command) {
+    const matched = [];
+    for (const pattern of DESTRUCTIVE_PATTERNS) {
+        if (pattern.regex.test(command)) {
+            matched.push(pattern.name);
+        }
+    }
+    return matched;
+}

package/dist/repertoire/skills.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSkillsDir = getSkillsDir;
+exports.getHarnessSkillsDir = getHarnessSkillsDir;
 exports.listSkills = listSkills;
 exports.loadSkill = loadSkill;
 exports.getLoadedSkills = getLoadedSkills;
@@ -42,6 +43,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
+const plugins_1 = require("./plugins");
 // Skills live in {agentRoot}/skills/ directory
 function getSkillsDir() {
     return path.join((0, identity_1.getAgentRoot)(), "skills");
@@ -50,9 +52,9 @@ function getSkillsDir() {
 function getProtocolMirrorDir() {
     return path.join(getSkillsDir(), "protocols");
 }
-// Canonical protocol source lives in {repoRoot}/subagents/.
-function getCanonicalProtocolsDir() {
-    return path.join((0, identity_1.getRepoRoot)(), "subagents");
+// Harness-level skills live in {repoRoot}/skills/ directory.
+function getHarnessSkillsDir() {
+    return path.join((0, identity_1.getRepoRoot)(), "skills");
 }
 function listMarkdownBasenames(dir) {
     if (!fs.existsSync(dir))
@@ -63,7 +65,7 @@ function listMarkdownBasenames(dir) {
         .map((f) => path.basename(f, ".md"))
         .sort();
 }
-// in-memory store for loaded skills
+// process-local store for loaded skills
 const loadedSkills = [];
 function listSkills() {
     (0, runtime_1.emitNervesEvent)({
@@ -74,8 +76,14 @@ function listSkills() {
     });
     const baseSkills = listMarkdownBasenames(getSkillsDir());
     const protocolMirrors = listMarkdownBasenames(getProtocolMirrorDir());
-    const canonicalProtocols = listMarkdownBasenames(getCanonicalProtocolsDir());
-    const skills = [...new Set([...baseSkills, ...protocolMirrors, ...canonicalProtocols])].sort();
+    const harnessSkills = listMarkdownBasenames(getHarnessSkillsDir());
+    const pluginSkills = (0, plugins_1.listPluginSkills)((0, plugins_1.listEnabledPlugins)());
+    // Agent skills (base + protocol) come first; harness skills are fallback;
+    // plugin skills surface after harness skills. Set deduplicates by name —
+    // agent overrides harness overrides plugins.
+    const skills = [
+        ...new Set([...baseSkills, ...protocolMirrors, ...harnessSkills, ...pluginSkills]),
+    ].sort();
     (0, runtime_1.emitNervesEvent)({
         event: "repertoire.load_end",
         component: "repertoire",
@@ -93,7 +101,7 @@ function loadSkill(skillName) {
     });
     const directSkillPath = path.join(getSkillsDir(), `${skillName}.md`);
     const protocolMirrorPath = path.join(getProtocolMirrorDir(), `${skillName}.md`);
-    const canonicalProtocolPath = path.join(getCanonicalProtocolsDir(), `${skillName}.md`);
+    const harnessSkillPath = path.join(getHarnessSkillsDir(), `${skillName}.md`);
     let resolvedPath = null;
     // 1) Direct agent skill.
     if (fs.existsSync(directSkillPath)) {
@@ -103,21 +111,34 @@ function loadSkill(skillName) {
     else if (fs.existsSync(protocolMirrorPath)) {
         resolvedPath = protocolMirrorPath;
     }
-    // 3) Canonical protocol fallback.
-    else if (fs.existsSync(canonicalProtocolPath)) {
-        (0, runtime_1.emitNervesEvent)({
-            level: "warn",
-            event: "repertoire.error",
-            component: "repertoire",
-            message: "protocol mirror missing; using canonical fallback",
-            meta: {
-                operation: "loadSkill",
-                skill: skillName,
-                mirrorPath: protocolMirrorPath,
-                canonicalPath: canonicalProtocolPath,
-            },
-        });
-        resolvedPath = canonicalProtocolPath;
+    // 3) Harness-level skill (ships with npm package).
+    else if (fs.existsSync(harnessSkillPath)) {
+        resolvedPath = harnessSkillPath;
+    }
+    // 4) Plugin skill fallback. Iterate enabled plugins; first match wins.
+    if (!resolvedPath) {
+        for (const plugin of (0, plugins_1.listEnabledPlugins)()) {
+            try {
+                const content = (0, plugins_1.loadPluginSkill)(plugin.id, skillName);
+                if (!loadedSkills.includes(skillName)) {
+                    loadedSkills.push(skillName);
+                }
+                (0, runtime_1.emitNervesEvent)({
+                    event: "repertoire.load_end",
+                    component: "repertoire",
+                    message: "loaded skill",
+                    meta: {
+                        operation: "loadSkill",
+                        skill: skillName,
+                        path: `plugin:${plugin.id}`,
+                    },
+                });
+                return content;
+            }
+            catch {
+                // try next plugin
+            }
+        }
     }
     if (!resolvedPath) {
         (0, runtime_1.emitNervesEvent)({
@@ -128,13 +149,13 @@ function loadSkill(skillName) {
             meta: {
                 operation: "loadSkill",
                 skill: skillName,
-                checkedPaths: [directSkillPath, protocolMirrorPath, canonicalProtocolPath],
+                checkedPaths: [directSkillPath, protocolMirrorPath, harnessSkillPath],
             },
         });
         throw new Error(`skill '${skillName}' not found in:\n` +
             `- ${directSkillPath}\n` +
             `- ${protocolMirrorPath}\n` +
-            `- ${canonicalProtocolPath}`);
+            `- ${harnessSkillPath}`);
     }
     const content = fs.readFileSync(resolvedPath, "utf-8");
     if (!loadedSkills.includes(skillName)) {