@ouro.bot/cli 0.1.0-alpha.920 → 0.1.0-alpha.922

package/changelog.json

@@ -1,6 +1,19 @@
 {
   "_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.922",
+      "changes": [
+        "Make Shepherd overview read fresh bounded screens for every terminal, separate historical returns, and report individual read failures."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.921",
+      "changes": [
+        "Make Teams chat tools share Shepherd’s machine attachment and identify cmux agents by foreground process, folder, workspace and tab title.",
+        "Initialize foreground process execution only when attached terminals need it, keeping unrelated prompt and daemon consumers free of lookup startup side effects."
+      ]
+    },
     {
       "version": "0.1.0-alpha.920",
       "changes": [

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

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.920",
+  "runtimeVersion": "0.1.0-alpha.922",
   "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.920</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.922</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

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

@@ -429,11 +429,11 @@ function managedSenseEntry(sense) {
         return "senses/shepherd-entry.js";
     return "senses/mail-entry.js";
 }
-function runtimeCredentialBootstrapFor(agent, sense) {
+function runtimeCredentialBootstrapFor(agent) {
     const runtime = (0, runtime_credentials_1.readRuntimeCredentialConfig)(agent);
-    const usesMachineConfig = sense === "bluebubbles" || sense === "voice" || sense === "a2a" || sense === "telegram" || sense === "shepherd";
-    const machineId = usesMachineConfig ? currentMachineId() : undefined;
-    const machine = usesMachineConfig ? (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agent) : null;
+    // Every sense can run chat-turn tools against this machine's attachments.
+    const machineId = currentMachineId();
+    const machine = (0, runtime_credentials_1.readMachineRuntimeCredentialConfig)(agent);
     const providerPool = (0, provider_credentials_1.readProviderCredentialPool)(agent);
     const providerCredentialRecords = providerPool.ok
         ? Object.values(providerPool.pool.providers).filter((record) => !!record)
@@ -441,7 +441,7 @@ function runtimeCredentialBootstrapFor(agent, sense) {
     const bootstrap = {
         agentName: agent,
         runtimeConfig: runtime.ok ? runtime.config : undefined,
-        machineRuntimeConfig: machine?.ok ? machine.config : undefined,
+        machineRuntimeConfig: machine.ok ? machine.config : undefined,
         machineId,
         providerCredentialRecords: providerCredentialRecords.length > 0 ? providerCredentialRecords : undefined,
     };
@@ -611,7 +611,7 @@ class DaemonSenseManager {
                 channel: sense,
                 autoStart: true,
                 ...(sense === "a2a" ? { args: managedA2AArgs(agent), getArgs: () => managedA2AArgs(agent) } : {}),
-                getRuntimeCredentialBootstrap: () => runtimeCredentialBootstrapFor(agent, sense),
+                getRuntimeCredentialBootstrap: () => runtimeCredentialBootstrapFor(agent),
             }));
         });
         this.processManager = options.processManager ?? new process_manager_1.DaemonProcessManager({

package/dist/repertoire/tools-shepherd.js

@@ -45,13 +45,16 @@ const redact_1 = require("../senses/shepherd/redact");
 const returns_1 = require("../senses/shepherd/returns");
 const tools_base_1 = require("./tools-base");
 /**
- * Shepherd's tools: every coding-agent session on this machine's terminal host with what Shepherd
- * last decided about it (`shepherd_overview`), what a session shows (`shepherd_read`), a status
+ * 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
  * line or notification for the human (`shepherd_signal`), and a line or key typed for the human
  * who asked for it (`shepherd_send`).
  */
 const STATUS_MAX_CHARS = 120;
 const READ_MAX_CHARS = 16_000;
+const OVERVIEW_READ_LINES = 80;
+const OVERVIEW_SCREEN_MAX_CHARS = 4_000;
+const OVERVIEW_TOTAL_SCREEN_MAX_CHARS = 64_000;
 exports.SEND_TEXT_MAX_CHARS = 2_000;
 exports.SEND_KEYS = ["enter", "escape", "up", "down", "tab", "ctrl-c", "1", "2", "3", "4", "5", "6", "7", "8", "9", "y", "n"];
 /** Keys that can approve or choose something on a prompt: pressed only on the screen the caller last read. */
@@ -91,12 +94,27 @@ async function withHost(tool, ctx, run) {
         return JSON.stringify({ error: error.message });
     }
 }
+async function currentScreen(host, session, maxChars) {
+    try {
+        const raw = await host.read(session, OVERVIEW_READ_LINES);
+        // Frame glyphs and padded empty rows otherwise crowd actual work out of a multi-terminal snapshot.
+        const content = (0, redact_1.redactSecrets)(raw).split("\n")
+            .map(line => line.replace(/[\u2500-\u259f]/g, "").trimEnd())
+            .filter(line => line.trim().length > 0).join("\n");
+        return { at: new Date().toISOString(), text: content.slice(Math.max(0, content.length - maxChars)), truncated: content.length > maxChars };
+    }
+    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_overview_read_error", message: "could not read one terminal in the live Shepherd overview", meta: { session, error: message } });
+        return { at: new Date().toISOString(), error: message };
+    }
+}
 exports.shepherdOverviewToolDefinition = {
     tool: {
         type: "function",
         function: {
             name: "shepherd_overview",
-            description: "Every terminal session on this machine's terminal host (cmux), with the coding agent there when known, and the last time Shepherd judged a return of control in it: when, what kind (premature, gate, done, unclear, loop_guard, error), whether it answered, and why. Read-only.",
+            description: "A live, read-only snapshot of every terminal on this machine's host (cmux): agent, folder, workspace and tab, plus a freshly read, redacted, bounded currentScreen with its observation time. Use currentScreen to answer what agents are doing now in one reply; lastReturn is historical and must not be presented as current status. A currentScreen.error explicitly identifies a terminal that could not be read; explain it inline with the other sessions, not by asking for another turn. For deeper details use shepherd_read. terminalCount is authoritative; derive any category counts from the actual listed sessions. Historical lastReturn includes the prior judgment time, kind, action and reason.",
             parameters: { type: "object", properties: {}, additionalProperties: false },
         },
     },
@@ -104,12 +122,15 @@ exports.shepherdOverviewToolDefinition = {
         const last = new Map();
         for (const record of (0, returns_1.readReturns)(ctx.agentRoot))
             last.set(record.session, record);
+        const sessions = await host.list();
+        const screenLimit = Math.min(OVERVIEW_SCREEN_MAX_CHARS, Math.floor(OVERVIEW_TOTAL_SCREEN_MAX_CHARS / Math.max(1, sessions.length)));
         return {
             host: host.name,
-            sessions: (await host.list()).map((session) => {
+            terminalCount: sessions.length,
+            sessions: await Promise.all(sessions.map(async (session) => {
                 const record = last.get(session.id);
-                return { ...session, ...(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: { at: record.at, kind: record.kind, action: record.action, reason: record.reason, reply: record.reply, task: record.task } } : {}) };
+            })),
         };
     }),
     summaryKeys: [],

package/dist/senses/shepherd/cmux.js

@@ -42,6 +42,7 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const runtime_1 = require("../../nerves/runtime");
+const terminal_process_1 = require("./terminal-process");
 /**
  * The cmux host (0.64.22 or later). A return is cmux's own "agent stopped" signal: an
  * `agent.hook.Stop` event, which cmux publishes for every agent its hooks cover (Claude Code,
@@ -128,17 +129,25 @@ function createCmuxHost(client, options = {}) {
     };
     async function surfaces() {
         const tree = await client.call("system.tree", { all_windows: true });
-        return list(tree.windows).flatMap((window) => list(window.workspaces).map((workspace) => ({ window, workspace }))).flatMap(({ window, workspace }) => list(workspace.panes).flatMap((pane) => list(pane.surfaces)).map((surface) => ({
+        const entries = list(tree.windows).flatMap((window) => list(window.workspaces).map((workspace) => ({ window, workspace }))).flatMap(({ window, workspace }) => list(workspace.panes).flatMap((pane) => list(pane.surfaces)).map((surface) => ({
             id: str(surface.id) ?? "",
             ref: str(surface.ref) ?? "",
             workspace: str(workspace.ref),
+            workspaceTitle: str(workspace.title),
             workspaceId: str(workspace.id) ?? "",
             title: str(surface.title) ?? "",
+            tty: str(surface.tty),
             type: str(surface.type) ?? "",
             agent: hooked.get(str(surface.id) ?? "")?.agent ?? null,
+            cwd: hooked.get(str(surface.id) ?? "")?.cwd ?? null,
             // The human's terminal: the focused surface of the selected workspace in a visible window.
             focused: surface.focused === true && workspace.selected === true && window.visible !== false,
         })));
+        const identities = await (options.identifyTerminals ?? terminal_process_1.identifyTerminalProcesses)(entries.filter((entry) => entry.type === "terminal" && entry.tty).map((entry) => entry.tty));
+        return entries.map((entry) => {
+            const identity = entry.tty ? identities.get(entry.tty) : undefined;
+            return { ...entry, agent: identity?.agent ?? entry.agent, cwd: identity?.cwd ?? entry.cwd };
+        });
     }
     async function locate(sessionId) {
         const surface = (await surfaces()).find((entry) => entry.id === sessionId || entry.ref === sessionId);
@@ -153,7 +162,7 @@ function createCmuxHost(client, options = {}) {
     return {
         name: "cmux",
         async list() {
-            return (await surfaces()).filter((surface) => surface.type === "terminal").map(({ id, ref, workspace, title, agent, focused }) => ({ id, ref, workspace, title, agent, focused }));
+            return (await surfaces()).filter((surface) => surface.type === "terminal").map(({ workspaceId: _workspaceId, type: _type, ...session }) => session);
         },
         read,
         async prompt(sessionId, line) {
@@ -316,8 +325,7 @@ function createCmuxHost(client, options = {}) {
                         }
                         else if (last.active && at - last.changedAt >= Math.max(quietMs.get(surface.id) ?? exports.QUIET_MS, hooked.has(surface.id) ? exports.HOOKED_QUIET_MS : 0)) {
                             last.active = false;
-                            const hook = hooked.get(surface.id);
-                            handlers.returned({ sessionId: surface.id, transitionId: `cmux:quiet:${surface.id}:${last.changedAt}`, agent: hook?.agent ?? null, cwd: hook?.cwd ?? null, lastBody: null, backgroundWork: null });
+                            handlers.returned({ sessionId: surface.id, transitionId: `cmux:quiet:${surface.id}:${last.changedAt}`, agent: surface.agent, cwd: surface.cwd ?? null, title: surface.title, workspaceTitle: surface.workspaceTitle, lastBody: null, backgroundWork: null });
                         }
                     }
                 }

package/dist/senses/shepherd/owner-notice.js

@@ -78,15 +78,21 @@ function plain(value, max) {
         .trim();
     return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
 }
-function who(record, ref) {
-    const agent = record.agent ? plain(record.agent, NAME_MAX) : "";
-    const folder = record.cwd ? plain(path.basename(record.cwd), NAME_MAX) : "";
-    const where = plain(ref ?? record.session.slice(0, 8), NAME_MAX);
+function who(record, location) {
+    const session = typeof location === "object" ? location : undefined;
+    const agentName = record.agent ?? session?.agent;
+    const cwd = record.cwd ?? session?.cwd;
+    const agent = agentName ? plain(agentName, NAME_MAX) : "";
+    const folder = cwd ? plain(path.basename(cwd), NAME_MAX) : "";
+    const ref = typeof location === "string" ? location : session?.ref;
+    const handle = plain(ref ?? record.session.slice(0, 8), NAME_MAX);
+    const labels = [record.workspaceTitle ?? session?.workspaceTitle, record.title ?? session?.title].filter((label) => !!label).map((label) => plain(label, NAME_MAX));
+    const where = labels.length ? `${labels.join(" / ")}; ${handle}` : handle;
     return `${agent || "A coding agent"}${folder ? ` in ${folder}` : ""}${where ? ` (${where})` : ""}`;
 }
 /** One return as one sentence pair: who returned, what Shepherd did, and why. */
-function noticeLine(record, ref) {
-    const subject = who(record, ref);
+function noticeLine(record, location) {
+    const subject = who(record, location);
     const why = `Why: ${plain(record.reason, REASON_MAX) || "no reason given"}`;
     switch (record.kind) {
         case "premature":
@@ -198,7 +204,7 @@ function createOwnerNotifier(options) {
             const refs = new Map();
             try {
                 for (const session of await options.listSessions())
-                    refs.set(session.id, session.ref);
+                    refs.set(session.id, session);
             }
             catch {
                 // Without the host's handles, each notice names a short session id instead.

package/dist/senses/shepherd/sense.js

@@ -204,6 +204,7 @@ async function startShepherdSenseApp(options) {
         const record = {
             at: new Date(now()).toISOString(), host: host.name, session: event.sessionId, transition: event.transitionId,
             agent: event.agent, cwd: event.cwd, task: null, kind: "unclear", action: "let_through", reason: "", reply: null, latencyMs: null, inputTokens: null,
+            ...(event.title !== undefined ? { title: event.title, workspaceTitle: event.workspaceTitle } : {}),
         };
         const state = guardFor(event.sessionId);
         /** False for a return nothing new was decided about: the loop guard still holds, or the same background wait. */

package/dist/senses/shepherd/terminal-process.js

@@ -0,0 +1,99 @@
+"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.identifyTerminalProcesses = identifyTerminalProcesses;
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const runtime_1 = require("../../nerves/runtime");
+async function runCommand(command, args) {
+    const { execFile } = await Promise.resolve().then(() => __importStar(require("node:child_process")));
+    const exec = (0, node_util_1.promisify)(execFile);
+    const { stdout } = await exec(command, args, { timeout: 3_000, maxBuffer: 4 * 1024 * 1024 });
+    return stdout;
+}
+/** One process snapshot and one cwd lookup for all terminals, not a subprocess per polling surface. */
+async function identifyTerminalProcesses(ttys, run = runCommand) {
+    const result = new Map();
+    if (ttys.length === 0)
+        return result;
+    const wanted = new Set(ttys.map((tty) => tty.replace(/^\/dev\//, "")));
+    const agents = new Map();
+    try {
+        for (const line of (await run("ps", ["-axo", "pid=,ppid=,pgid=,tpgid=,tty=,comm="])).split("\n")) {
+            const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(-?\d+)\s+(\S+)\s+(.+)$/);
+            if (!match)
+                continue;
+            const [, pid, parent, group, foreground, tty, command] = match;
+            if (!wanted.has(tty) || group !== foreground)
+                continue;
+            const executable = path.basename(command);
+            const agent = executable === "claude" ? "Claude Code" : executable === "copilot" ? "Copilot" : executable === "codex" ? "Codex" : null;
+            if (!agent)
+                continue;
+            const candidates = agents.get(tty) ?? [];
+            candidates.push({ pid: Number(pid), parent: Number(parent), agent });
+            agents.set(tty, candidates);
+        }
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_process_lookup_error", message: "could not identify terminal foreground agents", meta: { error: String(error) } });
+        return result;
+    }
+    const selected = new Map();
+    for (const [tty, candidates] of agents) {
+        const outer = candidates.find((candidate) => !candidates.some((parent) => parent.pid === candidate.parent));
+        selected.set(tty, outer);
+        result.set(tty, { agent: outer.agent, cwd: null });
+    }
+    if (selected.size === 0)
+        return result;
+    try {
+        const cwdByPid = new Map();
+        let pid = 0;
+        const output = await run("lsof", ["-a", "-p", [...selected.values()].map((agent) => agent.pid).join(","), "-d", "cwd", "-Fn"]);
+        for (const line of output.split("\n")) {
+            if (line.startsWith("p"))
+                pid = Number(line.slice(1));
+            else if (line.startsWith("n") && pid)
+                cwdByPid.set(pid, line.slice(1));
+        }
+        for (const [tty, agent] of selected)
+            result.set(tty, { agent: agent.agent, cwd: cwdByPid.get(agent.pid) ?? null });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cwd_lookup_error", message: "could not read foreground agent folders", meta: { error: String(error) } });
+    }
+    return result;
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.920",
+  "version": "0.1.0-alpha.922",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.920",
+      "version": "0.1.0-alpha.922",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.920",
+  "version": "0.1.0-alpha.922",
   "engines": {
     "node": ">=22"
   },