@ouro.bot/cli 0.1.0-alpha.923 → 0.1.0-alpha.924

package/changelog.json

@@ -1,6 +1,20 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.924",
+      "changes": [
+        "Talk to Ouro about a fixed coding terminal through an independent Shepherd composer, even while its agent is busy.",
+        "Correct Shepherd after an intervention, inspect or change scoped learned guidance, and pause automatic replies without interrupting coding work.",
+        "Retain every eligible owner notice across restart, record Teams acceptance, and retry only definitely unsent deliveries.",
+        "Enforce the composer's fixed UUID and host at terminal and guidance execution boundaries; concurrent notice workers cannot replay an accepted or uncertain send.",
+        "Recognize current Node-hosted Copilot terminals by their foreground launcher entry point, so the independent composer remains available on Copilot 1.0.97.",
+        "Trace fixed-target composer submissions, authorized target discovery, committed guidance revisions, and bound-target refusals without logging private human feedback.",
+        "Answer notice-delivery questions from private recipient-specific accepted, pending or uncertain receipts, including archived acceptances, without replaying sends or hiding unavailable evidence.",
+        "Keep private error details in redacted human responses and record only structured failure codes in control/learning telemetry.",
+        "Use authoritative short return labels in human answers while retaining exact immutable identifiers for post-action corrections."
+      ]
+    },
     {
       "version": "0.1.0-alpha.923",
       "changes": [

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

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

package/deploy/unraid/sanctuary.xml

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

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

@@ -7897,6 +7897,29 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         await runMcpServeCliLifecycle(server, mcpInput);
         return "";
     }
+    if (command.kind === "shepherd.chat") {
+        const daemonResult = deps.ensureDaemonForFrontend
+            ? await deps.ensureDaemonForFrontend(command.agent)
+            : await ensureDaemonRunning({
+                ...deps,
+                startDaemonProcess: (socketPath) => deps.startDaemonForFrontend
+                    ? deps.startDaemonForFrontend(socketPath, command.agent)
+                    : deps.startDaemonProcess(socketPath),
+                reportDaemonStartupPhase: () => { },
+            });
+        if (!daemonResult.ok)
+            throw new Error(daemonResult.message);
+        const { frontendSocketPathForDaemon } = await Promise.resolve().then(() => __importStar(require("../frontend-socket")));
+        const socketPath = frontendSocketPathForDaemon(deps.socketPath);
+        if (deps.startShepherdChat) {
+            await deps.startShepherdChat({ agent: command.agent, ...(command.session ? { session: command.session } : {}), socketPath });
+        }
+        else {
+            const { runShepherdComposer } = await Promise.resolve().then(() => __importStar(require("../../senses/shepherd/composer")));
+            await runShepherdComposer({ agent: command.agent, ...(command.session ? { session: command.session } : {}), socketPath });
+        }
+        return "";
+    }
     if (command.kind === "acp-serve") {
         const createAcpServer = deps.createAcpServer ?? (await Promise.resolve().then(() => __importStar(require("../../senses/acp-server")))).createAcpServer;
         const resolveFriendId = deps.resolveFrontendFriendId ?? resolveFrontendFriendId;

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

@@ -118,6 +118,13 @@ exports.COMMAND_REGISTRY = {
         example: "ouro voice join --agent slugger --participants \"Ari and Sam\" --occasion \"podcast prep\"",
         subcommands: ["join", "leave", "status"],
     },
+    shepherd: {
+        category: "Agents",
+        description: "Open an independent Ouro composer for one coding terminal. Uses a named picker when ambiguous; /cancel cancels only Ouro's turn, /quit exits. Not an input hook in the coding agent.",
+        usage: "ouro shepherd chat --agent <name> [--session <UUID>]",
+        example: "ouro shepherd chat --agent ouroboros",
+        subcommands: ["chat"],
+    },
     config: {
         category: "Agents",
         description: "Legacy model compatibility helpers; prefer `ouro use` and `ouro check`",

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

@@ -52,6 +52,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const friends_1 = require("@ouro.bot/friends");
 const cli_help_1 = require("./cli-help");
+const surface_1 = require("../../senses/shepherd/surface");
 const local_audio_control_1 = require("../../senses/voice/local-audio-control");
 const cli_desk_1 = require("./cli-desk");
 const flight_recorder_1 = require("../../arc/flight-recorder");
@@ -3120,6 +3121,24 @@ function parseOuroCommand(args) {
         return parseConfigCommand(args.slice(1));
     if (head === "mcp")
         return parseMcpCommand(args.slice(1));
+    if (head === "shepherd") {
+        const usage = "Usage: ouro shepherd chat --agent <name> [--session <UUID>]";
+        if (args[1] !== "chat")
+            throw new Error(usage);
+        const values = new Map();
+        for (let i = 2; i < args.length; i += 2) {
+            const flag = args[i];
+            const value = args[i + 1];
+            if (!["--agent", "--session"].includes(flag) || values.has(flag) || !value || value.startsWith("--"))
+                throw new Error(usage);
+            values.set(flag, value);
+        }
+        const agent = values.get("--agent");
+        const session = values.get("--session");
+        if (!agent || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent) || (session !== undefined && !surface_1.SHEPHERD_UUID.test(session)))
+            throw new Error(usage);
+        return { kind: "shepherd.chat", agent, ...(session ? { session } : {}) };
+    }
     if (head === "voice")
         return parseVoiceCommand(args.slice(1));
     if (head === "whoami") {

package/dist/heart/frontend-session-service.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FrontendSessionService = exports.FrontendSessionConflictError = exports.FrontendTurnConflictError = void 0;
 const shared_turn_1 = require("../senses/shared-turn");
 const runtime_1 = require("../nerves/runtime");
+const surface_1 = require("../senses/shepherd/surface");
 class FrontendTurnConflictError extends Error {
     constructor(turnId) {
         super(`frontend turn already exists: ${turnId}`);
@@ -33,15 +34,52 @@ function required(value, field) {
 class FrontendSessionService {
     activeTurns = new Map();
     activeSessions = new Map();
+    turnRefs = new Map();
     listeners = new Set();
     runner;
     journal;
     authority;
     closed = false;
+    shepherdTargets;
     constructor(options = {}) {
         this.runner = options.runner ?? shared_turn_1.runSenseTurn;
         this.journal = options.journal ?? null;
         this.authority = options.authority ?? null;
+        this.shepherdTargets = options.shepherdTargets ?? surface_1.authorizedShepherdTargets;
+    }
+    listShepherdTargets(agent, friendId, composerTty) {
+        if (composerTty !== undefined && !/^\/dev\/[A-Za-z0-9/_-]{1,120}$/.test(composerTty))
+            throw new Error("composerTty must be a terminal device path");
+        return this.shepherdTargets(required(agent, "agent"), required(friendId, "friendId"), composerTty);
+    }
+    async resolveShepherdSession(agent, friendId, value, composerTty) {
+        const id = value && typeof value === "object" ? value.id : undefined;
+        if (typeof id !== "string")
+            throw new Error("shepherdSession requires a stable UUID");
+        const targets = await this.listShepherdTargets(agent, friendId, composerTty);
+        const target = targets.find(candidate => candidate.id.toLowerCase() === id.toLowerCase());
+        if (!target)
+            throw new Error(`selected Shepherd terminal is unavailable: ${id}`);
+        return Object.freeze({ ...target });
+    }
+    turnStatus(ref, turnId) {
+        const events = [];
+        if (this.journal) {
+            let afterSequence = 0;
+            for (;;) {
+                const replay = this.loadSession(ref, { afterSequence });
+                if (replay.degraded)
+                    throw new Error("frontend journal is degraded; turn status is unknown");
+                events.push(...replay.events.filter(event => event.turnId === turnId));
+                if (!replay.hasMore)
+                    break;
+                afterSequence = replay.events.at(-1).sequence;
+            }
+        }
+        const activeRef = this.turnRefs.get(turnId);
+        const active = activeRef && activeRef.agent === ref.agent && activeRef.friendId === ref.friendId && activeRef.sessionKey === ref.sessionKey;
+        const terminal = events.some(event => ["turn_completed", "turn_failed", "turn_cancelled"].includes(event.type));
+        return { state: terminal ? "completed" : active ? "active" : events.length ? "incomplete" : "unknown", events };
     }
     hasTurn(turnId) {
         return this.activeTurns.has(turnId);
@@ -102,15 +140,19 @@ class FrontendSessionService {
             agent: required(request.agent, "agent"),
             friendId: required(request.friendId, "friendId"),
             sessionKey: required(request.sessionKey, "sessionKey"),
-            message: required(request.message, "message"),
+            message: (required(request.message, "message"), request.message),
+            ...(request.shepherdSession ? { shepherdSession: Object.freeze({ ...request.shepherdSession }) } : {}),
         };
         if (this.activeTurns.has(turnId))
             throw new FrontendTurnConflictError(turnId);
+        if (this.journal && this.turnStatus(normalized, turnId).state !== "unknown")
+            throw new FrontendTurnConflictError(turnId);
         const sessionIdentity = [normalized.agent, normalized.friendId, normalized.channel, normalized.sessionKey].join("\0");
         if (this.activeSessions.has(sessionIdentity))
             throw new FrontendSessionConflictError(normalized.sessionKey);
         const controller = new AbortController();
         this.activeTurns.set(turnId, controller);
+        this.turnRefs.set(turnId, normalized);
         this.activeSessions.set(sessionIdentity, turnId);
         return { request: normalized, sessionIdentity, controller, started: false };
     }
@@ -143,6 +185,7 @@ class FrontendSessionService {
                 channel: normalized.channel,
                 sessionKey: normalized.sessionKey,
                 userMessage: normalized.message,
+                ...(normalized.shepherdSession ? { shepherdSession: normalized.shepherdSession } : {}),
                 signal: controller.signal,
                 latencyMode: "live",
                 frontendEventSink,
@@ -191,6 +234,7 @@ class FrontendSessionService {
         }
         finally {
             this.activeTurns.delete(turnId);
+            this.turnRefs.delete(turnId);
             this.activeSessions.delete(sessionIdentity);
         }
     }

package/dist/heart/frontend-socket.js

@@ -255,6 +255,20 @@ async function startFrontendSocketServer(options) {
         }
         const method = requiredString(request.method, "method");
         const params = record(request.params ?? {});
+        if (method === "shepherd.targets") {
+            const targets = await options.service.listShepherdTargets(requiredString(params.agent, "agent"), requiredString(params.friendId, "friendId"), params.composerTty === undefined ? undefined : requiredString(params.composerTty, "composerTty"));
+            client.writer.send(response(id, { targets }));
+            return;
+        }
+        if (method === "turn.status") {
+            const result = options.service.turnStatus({
+                agent: requiredString(params.agent, "agent"),
+                friendId: requiredString(params.friendId, "friendId"),
+                sessionKey: requiredString(params.sessionKey, "sessionKey"),
+            }, requiredString(params.turnId, "turnId"));
+            client.writer.send(response(id, result));
+            return;
+        }
         if (method === "session.load") {
             const result = options.service.loadSession({
                 agent: requiredString(params.agent, "agent"),
@@ -296,16 +310,25 @@ async function startFrontendSocketServer(options) {
                 throw new Error("turn.start.observe-only cannot include runtimeMcpServers");
             }
             const runtimeMcpServers = validatedRuntimeMcpServers(params.runtimeMcpServers);
+            const shepherdSession = params.shepherdSession === undefined ? undefined : await options.service.resolveShepherdSession(requiredString(params.agent, "agent"), requiredString(params.friendId, "friendId"), params.shepherdSession, params.composerTty === undefined ? undefined : requiredString(params.composerTty, "composerTty"));
+            if (shepherdSession && (observeOnly || params.channel !== "cli" || params.sessionKey !== `shepherd:${shepherdSession.id}`)) {
+                throw new Error("Shepherd routing requires a cli turn and the exact per-surface session key");
+            }
             const turnRequest = {
                 turnId: requiredString(params.turnId, "turnId"),
                 agent: requiredString(params.agent, "agent"),
                 friendId: requiredString(params.friendId, "friendId"),
                 channel: requiredString(params.channel, "channel"),
                 sessionKey: requiredString(params.sessionKey, "sessionKey"),
-                message: requiredString(params.message, "message"),
+                message: (requiredString(params.message, "message"), params.message),
+                ...(shepherdSession ? { shepherdSession } : {}),
                 ...(observeOnly ? { disableTools: true, ephemeral: true } : {}),
                 ...(runtimeMcpServers ? { runtimeMcpServers } : {}),
             };
+            // Validation may await the host while this connection exits. Ownership must
+            // never be acquired after cleanup has already drained this client's turns.
+            if (client.closed || client.socket.destroyed || stopped)
+                return;
             const prepared = options.service.prepareTurn(turnRequest);
             client.ownedTurnIds.add(turnRequest.turnId);
             client.writer.send(response(id, { accepted: true, turnId: turnRequest.turnId }));
@@ -323,6 +346,7 @@ async function startFrontendSocketServer(options) {
             writer: new FrontendFrameWriter(socket, maxQueuedFrames, ownedTurnIds.clear.bind(ownedTurnIds)),
             subscriptions: new Set(),
             ownedTurnIds,
+            closed: false,
         };
         clients.add(client);
         const lines = readline.createInterface({ input: socket, crlfDelay: Infinity });
@@ -332,6 +356,7 @@ async function startFrontendSocketServer(options) {
             if (cleanedUp)
                 return;
             cleanedUp = true;
+            client.closed = true;
             for (const turnId of client.ownedTurnIds)
                 options.service.cancelTurn(turnId);
             clients.delete(client);

package/dist/repertoire/tools-shepherd-guidance.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shepherdGuidanceToolDefinitions = void 0;
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const node_crypto_1 = require("node:crypto");
+const shepherd_config_1 = require("../heart/shepherd-config");
+const host_1 = require("../senses/shepherd/host");
+const guidance_1 = require("../senses/shepherd/guidance");
+const redact_1 = require("../senses/shepherd/redact");
+const returns_1 = require("../senses/shepherd/returns");
+const notice_outbox_1 = require("../senses/shepherd/notice-outbox");
+const target_binding_1 = require("../senses/shepherd/target-binding");
+const tools_base_1 = require("./tools-base");
+const runtime_1 = require("../nerves/runtime");
+const text = (value) => typeof value === "string" ? value.trim() : "";
+const json = (value) => JSON.stringify(value, (_key, item) => typeof item === "string" ? (0, redact_1.redactSecrets)(item) : item);
+const stringProperty = (description) => ({ type: "string", description });
+const targetProperties = {
+    host: stringProperty("Host name from history, when known. Never invent a host."),
+    session: stringProperty("Stable session ID from history, or a live session ID/ref from shepherd_overview."),
+};
+const requestProperty = { request_id: stringProperty("Unique request ID for this human instruction. Reuse it only to retry the identical request.") };
+function fingerprint(name, args) {
+    const body = JSON.stringify({ name, args }, (_key, value) => value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value);
+    return (0, node_crypto_1.createHash)("sha256").update(body).digest("hex");
+}
+/**
+ * Resolve history without a terminal connection, including vanished sessions. Only a session with no history needs
+ * the existing machine connection primitives. Resolving it never reads a screen, signals, presses a key or sends.
+ */
+async function targetFor(ctx, args) {
+    if (text(args.session))
+        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, text(args.session), text(args.host) || undefined);
+    const records = (0, returns_1.readReturns)(ctx.agentRoot);
+    const returnId = text(args.return_id);
+    if (returnId) {
+        const record = records.find(r => (0, guidance_1.shepherdReturnId)(r) === returnId);
+        if (!record)
+            throw new Error("Shepherd return ID not found");
+        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, record.session, record.host);
+        if ((text(args.host) && text(args.host) !== record.host) || (text(args.session) && text(args.session) !== record.session))
+            throw new Error("target does not match the recorded return");
+        return { target: { host: record.host, session: record.session, cwd: record.cwd, task: record.task }, live: [] };
+    }
+    const session = text(args.session);
+    if (!session)
+        throw new Error("name a session from Shepherd history or overview");
+    const hostName = text(args.host);
+    const matching = records.filter(r => r.session === session && (!hostName || r.host === hostName));
+    if (new Set(matching.map(r => r.host)).size > 1)
+        throw new Error("session is ambiguous across hosts; name its host");
+    const record = matching.at(-1);
+    if (record) {
+        (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, record.session, record.host);
+        return { target: { host: record.host, session, cwd: record.cwd, task: record.task }, live: [] };
+    }
+    const machine = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(ctx.agentName);
+    const resolved = (0, shepherd_config_1.resolveShepherdConnection)(ctx.agentName, machine.ok ? machine.config : {});
+    if (!resolved.ok)
+        throw new Error(resolved.error);
+    const host = (0, host_1.createShepherdHost)(resolved.connection, { agentName: ctx.agentName });
+    const sessions = await host.list();
+    const live = sessions.map(s => ({ host: host.name, session: s.id, cwd: s.cwd ?? null, task: null }));
+    const found = sessions.find(s => s.id === session || s.ref === session);
+    if (!found || (hostName && hostName !== host.name))
+        throw new Error("unknown session on the configured Shepherd host");
+    (0, target_binding_1.assertBoundShepherdTarget)(ctx.currentShepherdSurface, found.id, host.name);
+    return { target: live.find(t => t.session === found.id), live };
+}
+function definition(name, description, properties, required, run, mutates = false) {
+    return {
+        tool: { type: "function", function: { name, description, parameters: { type: "object", properties, required, additionalProperties: false } } },
+        handler: async (args, ctx) => {
+            // Same real-family gate as shepherd_send, including rejection of the private runtime's family self.
+            const friend = ctx?.context?.friend;
+            if (!friend || friend.trustLevel !== "family" || !friend.id || friend.id === tools_base_1.SELF_FRIEND_ID)
+                return json({ error: "Shepherd private guidance is only for a real family member in this conversation" });
+            if (!ctx?.agentRoot || !ctx.agentName)
+                return json({ error: "Shepherd guidance needs an agent runtime" });
+            try {
+                const request = { actorId: friend.id, requestId: text(args.request_id), requestFingerprint: fingerprint(name, args) };
+                if (mutates) {
+                    const prior = (0, guidance_1.readGuidance)(ctx.agentRoot).requests.find(r => r.actorId === request.actorId && r.requestId === request.requestId);
+                    if (prior) {
+                        if (prior.requestFingerprint !== request.requestFingerprint)
+                            throw new Error("request ID was already used with a different body");
+                        return json(prior.receipt);
+                    }
+                }
+                const result = await run(args, ctx, request);
+                (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.shepherd_guidance_tool", message: "executed a private Shepherd guidance tool", meta: { tool: name, mutates } });
+                return json(result);
+            }
+            catch (error) {
+                const message = (0, redact_1.redactSecrets)(error instanceof Error ? error.message : String(error));
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_guidance_tool_error", message: "private Shepherd guidance tool failed", meta: { tool: name, error: "private_guidance_operation_failed" } });
+                return json({ error: message });
+            }
+        },
+        summaryKeys: [],
+        riskProfile: mutates ? { mutates: "durable_state_write", risk: "high", reason: "changes private operator preferences or the automatic-reply pause" } : { mutates: "none", risk: "low" },
+    };
+}
+exports.shepherdGuidanceToolDefinitions = [
+    definition("shepherd_history", "Read private Shepherd return history with stable return IDs, actual judgment/reply/outcome and your own ownerNotice receipts when tracked. Historical, not current status; a vanished terminal remains readable. The session filter is a stable ID, not a short ref. Use to understand 'that was wrong because...' before correcting it, or to check whether a notice was sent. Use displayId as the human-facing return label; never invent a shortened ID suffix. Mutations require the exact full id, not displayId. ownerNotice.state sent means transport acceptance, not proof the human read it; pending awaits a safe retry; unknown may already have arrived and must not be blindly replayed. messageId is the activity ID returned by transport. ownerNotice null means no receipt recorded for this recipient, not proof of non-delivery. ownerNoticeError explicitly identifies unavailable receipt evidence. Never types into a terminal.", targetProperties, [], async (args, ctx, request) => {
+        const returns = (0, returns_1.readReturns)(ctx.agentRoot)
+            .filter(r => (!text(args.session) || r.session === text(args.session)) && (!text(args.host) || r.host === text(args.host)))
+            .map(record => {
+            const id = (0, guidance_1.shepherdReturnId)(record);
+            return { ...record, id, displayId: id.slice("return:".length, "return:".length + 8) };
+        });
+        try {
+            const notices = (0, notice_outbox_1.readNoticeOutbox)(ctx.agentRoot);
+            for (const record of returns) {
+                const notice = (0, notice_outbox_1.knownNotice)(ctx.agentRoot, (0, notice_outbox_1.noticeRecordId)(record), notices);
+                if (notice)
+                    record.ownerNotice = Object.hasOwn(notice.deliveries, request.actorId) ? notice.deliveries[request.actorId] : null;
+            }
+            return { returns };
+        }
+        catch (error) {
+            const message = (0, redact_1.redactSecrets)(error instanceof Error ? error.message : String(error));
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "repertoire", event: "repertoire.shepherd_notice_history_error", message: "owner notice receipt evidence is unavailable; return history remains readable", meta: { error: "notice_receipts_unavailable" } });
+            return { returns, ownerNoticeError: message };
+        }
+    }),
+    definition("shepherd_correct", "Record the human's post-action correction ('that was wrong because…') or prospective instruction. Optionally learn a principle for 'in future…'. A return_id must name a real history entry; omit it for a prospective instruction, never fabricate one. Session scope is the default; project is the exact recorded folder and optional task; global only when the human deliberately generalizes. Feedback <=2000 characters; principle <=1000; at most 20 active rules. This is not an approval gate and never sends anything. For requested immediate steering use existing shepherd_send.", {
+        ...targetProperties, ...requestProperty,
+        return_id: stringProperty("Real stable return ID from shepherd_history, if correcting an actual judgment."),
+        feedback: stringProperty("The human's explanation or prospective instruction, at most 2000 characters."),
+        principle: stringProperty("Optional scoped future preference, at most 1000 characters."),
+        scope: { type: "string", enum: ["session", "project", "global"], description: "Default session. Choose global only when the human expressed generalization." },
+    }, ["request_id", "feedback"], async (args, ctx, request) => {
+        const { target, live } = await targetFor(ctx, args);
+        return (0, guidance_1.recordShepherdCorrection)(ctx.agentRoot, {
+            ...request, target, feedback: typeof args.feedback === "string" ? args.feedback : "",
+            ...(args.return_id !== undefined ? { returnId: text(args.return_id) } : {}),
+            ...(args.principle !== undefined ? { principle: typeof args.principle === "string" ? args.principle : "" } : {}),
+            ...(args.scope !== undefined ? { scope: args.scope } : {}),
+        }, live);
+    }, true),
+    definition("shepherd_guidance", "Inspect what Shepherd learned ('what did you learn?'). With a session, returns revision, pause and applicable active principles with IDs, scopes and operator provenance. Omit session to inspect all active principles and pauses, including their exact targets. No send.", targetProperties, [], async (args, ctx) => {
+        if (args.session === undefined) {
+            const state = (0, guidance_1.readGuidance)(ctx.agentRoot);
+            return { revision: state.revision, principles: state.principles.filter(p => p.active), pauses: state.pauses.filter(p => p.paused) };
+        }
+        const { target } = await targetFor(ctx, args);
+        return (0, guidance_1.applicableGuidance)((0, guidance_1.readGuidance)(ctx.agentRoot), target);
+    }),
+    definition("shepherd_update_principle", "Change a learned preference ('change that') by its principle ID. Keeps its existing scope, never silently generalizes it. No send.", {
+        ...requestProperty, principle_id: stringProperty("Active principle ID from shepherd_guidance."), text: stringProperty("Replacement preference, nonempty and at most 1000 characters."),
+    }, ["request_id", "principle_id", "text"], async (args, ctx, request) => (0, guidance_1.updateShepherdPrinciple)(ctx.agentRoot, {
+        ...request, principleId: text(args.principle_id), text: typeof args.text === "string" ? args.text : "",
+    }), true),
+    definition("shepherd_forget_principle", "Forget a learned preference ('forget that') by its ID. Removes it from future judgments but retains the private operator trail. No send.", {
+        ...requestProperty, principle_id: stringProperty("Active principle ID from shepherd_guidance."),
+    }, ["request_id", "principle_id"], async (args, ctx, request) => (0, guidance_1.forgetShepherdPrinciple)(ctx.agentRoot, {
+        ...request, principleId: text(args.principle_id),
+    }), true),
+    ...["pause", "resume"].map(action => definition(`shepherd_${action}`, action === "pause" ? "Leave this one alone: pause automatic Shepherd replies for this session only, durably. Independent judgment/owner notices remain. Never interrupts or types into the terminal."
+        : "Resume automatic Shepherd replies for this paused session. All focus, screen, syntax and loop guards still apply; resume is not an immediate send.", { ...targetProperties, ...requestProperty }, ["session", "request_id"], async (args, ctx, request) => {
+        const { target, live } = await targetFor(ctx, args);
+        return (0, guidance_1.setShepherdSessionPause)(ctx.agentRoot, { ...request, target, paused: action === "pause" }, live);
+    }, true)),
+];

package/dist/repertoire/tools-shepherd.js

@@ -44,6 +44,9 @@ const host_1 = require("../senses/shepherd/host");
 const redact_1 = require("../senses/shepherd/redact");
 const returns_1 = require("../senses/shepherd/returns");
 const tools_base_1 = require("./tools-base");
+const tools_shepherd_guidance_1 = require("./tools-shepherd-guidance");
+const guidance_1 = require("../senses/shepherd/guidance");
+const target_binding_1 = require("../senses/shepherd/target-binding");
 /**
  * Shepherd's tools: every coding-agent session on this machine's terminal host with a current screen
  * and what Shepherd last decided about it (`shepherd_overview`), a deeper read (`shepherd_read`), a status
@@ -85,6 +88,12 @@ async function withHost(tool, ctx, run) {
     if (typeof host === "string")
         return JSON.stringify({ error: host });
     try {
+        if (ctx.currentShepherdSurface) {
+            const bound = ctx.currentShepherdSurface;
+            (0, target_binding_1.assertBoundShepherdTarget)(bound, bound.id, host.name);
+            if (!(await host.list()).some(session => session.id === bound.id))
+                throw new Error(`bound terminal ${bound.id} is gone; nothing was read or sent`);
+        }
         const result = await run(host);
         (0, runtime_1.emitNervesEvent)({ component: "repertoire", event: "repertoire.shepherd_tool", message: "ran a Shepherd tool", meta: { tool } });
         return JSON.stringify(result);
@@ -129,7 +138,7 @@ exports.shepherdOverviewToolDefinition = {
             terminalCount: sessions.length,
             sessions: await Promise.all(sessions.map(async (session) => {
                 const record = last.get(session.id);
-                return { ...session, currentScreen: await currentScreen(host, session.id, screenLimit), ...(record ? { lastReturn: { at: record.at, kind: record.kind, action: record.action, reason: record.reason, reply: record.reply, task: record.task } } : {}) };
+                return { ...session, currentScreen: await currentScreen(host, session.id, screenLimit), ...(record ? { lastReturn: { id: (0, guidance_1.shepherdReturnId)(record), at: record.at, kind: record.kind, action: record.action, reason: record.reason, reply: record.reply, task: record.task } } : {}) };
             })),
         };
     }),
@@ -162,6 +171,7 @@ exports.shepherdReadToolDefinition = {
         if (!session)
             return Promise.resolve(JSON.stringify({ error: "name a session id or ref from shepherd_overview" }));
         return withHost("shepherd_read", ctx, async (host) => {
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx?.currentShepherdSurface, session, host.name);
             const lines = boundedLines(args.lines);
             // A fingerprint needs enough lines to match the one shepherd_send takes, whatever the caller asked to see.
             const raw = await host.read(session, Math.max(lines, redact_1.FINGERPRINT_READ_LINES));
@@ -200,6 +210,7 @@ exports.shepherdSignalToolDefinition = {
         if (status.length > STATUS_MAX_CHARS || /[\r\n]/.test(status))
             return Promise.resolve(JSON.stringify({ error: `status must be one line of at most ${STATUS_MAX_CHARS} characters` }));
         return withHost("shepherd_signal", ctx, async (host) => {
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx?.currentShepherdSurface, session, host.name);
             await host.signal(session, status || null, title ? { title, body: text(args.notify_body) } : undefined);
             return { session, status: status ? "set" : "cleared", notified: !!title };
         });
@@ -254,6 +265,7 @@ exports.shepherdSendToolDefinition = {
         if (CHOOSING_KEYS.has(key) && !seen)
             return refuse(`${key} can approve or choose on a prompt, so pass screen from a shepherd_read made just before`);
         return withHost("shepherd_send", ctx, async (host) => {
+            (0, target_binding_1.assertBoundShepherdTarget)(ctx?.currentShepherdSurface, session, host.name);
             const target = (await host.list()).find((entry) => entry.id === session || entry.ref === session);
             if (!target)
                 return refused(`session ${session} is gone; check shepherd_overview`, meta);
@@ -280,4 +292,4 @@ exports.shepherdSendToolDefinition = {
     summaryKeys: ["session", "key"],
     riskProfile: { mutates: "external_side_effect", risk: "high", reason: "types into a coding agent's terminal for the human, which can answer or approve its prompts" },
 };
-exports.shepherdToolDefinitions = [exports.shepherdOverviewToolDefinition, exports.shepherdReadToolDefinition, exports.shepherdSignalToolDefinition, exports.shepherdSendToolDefinition];
+exports.shepherdToolDefinitions = [exports.shepherdOverviewToolDefinition, exports.shepherdReadToolDefinition, exports.shepherdSignalToolDefinition, exports.shepherdSendToolDefinition, ...tools_shepherd_guidance_1.shepherdGuidanceToolDefinitions];

package/dist/senses/shared-turn.js

@@ -347,6 +347,7 @@ function erroredTurnReply(errorMessage) {
         : "I couldn't finish that one: something went wrong before I had an answer. Ask me again and I'll retry.";
 }
 async function runSenseTurn(options) {
+    options = { ...options, ...(options.shepherdSession ? { shepherdSession: Object.freeze({ ...options.shepherdSession }) } : {}) };
     return (0, turn_execution_lease_1.withTurnExecutionLease)(async () => {
         const owner = Object.freeze({ agentName: options.agentName, agentRoot: (0, identity_1.getAgentRoot)(options.agentName) });
         (0, identity_1.setAgentName)(owner.agentName);
@@ -452,6 +453,15 @@ async function runSenseTurnExclusive(options, owner) {
                         role: "system",
                         content: (0, prompt_1.flattenSystemPrompt)(await (0, prompt_1.buildSystem)(channel, options.disableTools ? { tools: [], hardDisableTools: true } : {}, undefined)),
                     }];
+            if (options.shepherdSession) {
+                // Replace rather than accumulate context as the conversation reloads. It is bounded
+                // metadata, not a human instruction, and focus changes cannot alter its stable UUID.
+                const marker = "[Ouro Shepherd terminal context]";
+                const system = sessionMessages.find(message => message.role === "system");
+                if (system && typeof system.content === "string") {
+                    system.content = system.content.split(`\n${marker}`)[0] + `\n${marker}\n${JSON.stringify(options.shepherdSession)}\nUse this exact UUID for shepherd_read/shepherd_send. If gone, fail explicitly; never substitute a short ref. This locator grants no authority.`;
+                }
+            }
             if (precommittedIngressEvent) {
                 const projectedIngress = exactProjectedIngressMessage(existing, sessionMessages, precommittedIngressEvent.id, baseSession.value);
                 if (!projectedIngress || projectedIngress.role !== "user" || projectedIngress.content !== userMessage)
@@ -612,6 +622,7 @@ async function runSenseTurnExclusive(options, owner) {
                         agentName,
                         agentRoot,
                         currentUserMessage: userMessage,
+                        ...(options.shepherdSession ? { currentShepherdSurface: Object.freeze({ ...options.shepherdSession }) } : {}),
                     },
                 },
                 ...(options.prepareRunAgentOptions ? { prepareRunAgentOptions: options.prepareRunAgentOptions } : {}),