@ouro.bot/cli 0.1.0-alpha.934 → 0.1.0-alpha.936

package/dist/senses/shepherd/checkin-store.js

@@ -36,7 +36,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.refuseCustody = refuseCustody;
+exports.validCustodyInputReceipt = validCustodyInputReceipt;
+exports.copyCustodyInputReceipt = copyCustodyInputReceipt;
+exports.parseCustodyDispatch = parseCustodyDispatch;
+exports.validateCustodyDirectory = validateCustodyDirectory;
 exports.checkInStorePath = checkInStorePath;
+exports.assertNoCustodyMaintenance = assertNoCustodyMaintenance;
+exports.custodyCapacity = custodyCapacity;
+exports.custodyRevision = custodyRevision;
+exports.advanceCustodyRevision = advanceCustodyRevision;
+exports.hasRetiredCustodyInstance = hasRetiredCustodyInstance;
+exports.retiredCustodyKey = retiredCustodyKey;
+exports.readRetiredCustodyRecord = readRetiredCustodyRecord;
+exports.openCustodyDatabase = openCustodyDatabase;
 exports.openCheckInStore = openCheckInStore;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
@@ -45,17 +58,20 @@ const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const runtime_1 = require("../../nerves/runtime");
 const returns_1 = require("./returns");
 const MAX_ROW = 4096;
+const COMPLETION_HEADROOM = 2300;
 const MAX_DB = 64 * 1024 * 1024;
 const WARN_DB = 48 * 1024 * 1024;
+const warnedDatabases = new WeakSet();
 const bytes = (value) => Buffer.byteLength(JSON.stringify(value));
 const text = (value) => typeof value === "string" && value.length > 0;
 const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 const timestamp = (value) => text(value) && Number.isFinite(Date.parse(value));
-function refuse(reason) {
+function refuseCustody(reason) {
     (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_checkin_store_refused",
         message: "check-in custody operation refused", meta: { reason } });
     throw new Error(`Shepherd check-in custody: ${reason}`);
 }
+const refuse = refuseCustody;
 function bounded(value, limit, field) {
     if (!text(value) || bytes(value) > limit)
         refuse(`${field} byte limit or type`);
@@ -72,9 +88,24 @@ function dispatchId(input) {
 function validClaim(value) {
     return object(value) && validInput(value) && text(value.owner) && bytes(value.owner) <= 256 &&
         ["claimed", "sent", "not_sent", "unknown"].includes(String(value.state)) &&
-        (value.reason === undefined || text(value.reason) && bytes(value.reason) <= 1024);
+        (value.reason === undefined || text(value.reason) && bytes(value.reason) <= 1024)
+        && (value.receipt === undefined || validCustodyInputReceipt(value.receipt)
+            && value.receipt.requestId === value.id && value.receipt.surfaceId === value.session && value.receipt.processInstance === value.instance
+            && receiptMatchesOutcome(value.state, value.receipt));
 }
-function parseDispatch(row) {
+function validCustodyInputReceipt(value) {
+    return object(value) && ["requestId", "surfaceId", "workspaceId", "processInstance"].every(key => text(value[key]) && bytes(value[key]) <= 256)
+        && typeof value.pasteAdmitted === "boolean" && typeof value.submitAdmitted === "boolean"
+        && (!value.submitAdmitted || value.pasteAdmitted);
+}
+function copyCustodyInputReceipt(receipt) {
+    const { requestId, surfaceId, workspaceId, processInstance, pasteAdmitted, submitAdmitted } = receipt;
+    return { requestId, surfaceId, workspaceId, processInstance, pasteAdmitted, submitAdmitted };
+}
+function receiptMatchesOutcome(state, receipt) {
+    return state === "sent" ? receipt.pasteAdmitted && receipt.submitAdmitted : state !== "not_sent" || !receipt.pasteAdmitted && !receipt.submitAdmitted;
+}
+function parseCustodyDispatch(row) {
     if (Buffer.byteLength(row.data) > MAX_ROW)
         refuse("record byte limit");
     const value = JSON.parse(row.data);
@@ -83,71 +114,196 @@ function parseDispatch(row) {
         refuse("invalid dispatch schema");
     return value;
 }
-function privateDirectory(directory) {
-    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+const parseDispatch = parseCustodyDispatch;
+function validateCustodyDirectory(directory, create) {
+    const uid = process.getuid();
+    for (let candidate = directory; candidate !== path.dirname(candidate); candidate = path.dirname(candidate)) {
+        const stat = fs.lstatSync(candidate, { throwIfNoEntry: false });
+        if (stat?.isSymbolicLink())
+            refuse("private directory ancestor is a link");
+        if (stat && (!stat.isDirectory() || stat.uid !== 0 && stat.uid !== uid
+            || (stat.mode & 0o022) !== 0 && !(stat.uid === 0 && (stat.mode & 0o1000) !== 0)))
+            refuse("private directory ancestor ownership or mode");
+    }
+    if (create)
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (!fs.lstatSync(directory, { throwIfNoEntry: false }))
+        return false;
     const stat = fs.lstatSync(directory);
-    if (!stat.isDirectory() || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid())
-        refuse("private directory ownership or mode");
+    if (!stat.isDirectory() || (stat.mode & 0o7777) !== 0o700 || stat.uid !== uid)
+        refuse("private directory ownership or mode; require 0700");
+    return true;
 }
 function privateFile(file) {
     const stat = fs.lstatSync(file);
-    if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid())
+    if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o7777) !== 0o600 || stat.uid !== process.getuid())
         refuse("private file ownership or mode");
 }
 function checkInStorePath(agentRoot) {
     return path.join((0, returns_1.shepherdStateDir)(agentRoot), "checkins", "custody.sqlite");
 }
-function openCheckInStore(file) {
+function assertNoCustodyMaintenance(file) {
+    if (fs.lstatSync(`${file}.maintenance.json`, { throwIfNoEntry: false }))
+        refuse("interrupted or active maintenance; resume the exact owner maintenance request");
+}
+function custodyCapacity(database, writing = false) {
+    const size = Number(database.pragma("page_count", { simple: true })) * Number(database.pragma("page_size", { simple: true }));
+    if (size > MAX_DB || writing && size + 65536 > MAX_DB)
+        refuse("database capacity; no input authorized");
+    if (!warnedDatabases.has(database) && size >= WARN_DB) {
+        warnedDatabases.add(database);
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_checkin_capacity_warning",
+            message: "check-in custody is approaching capacity", meta: { bytes: size, limit: MAX_DB } });
+    }
+    return { bytes: size, capacity: size + 65536 > MAX_DB ? "refused" : size >= WARN_DB ? "warning" : "normal" };
+}
+function custodyRevision(database) {
+    const row = database.prepare("SELECT revision FROM custody_meta WHERE singleton=1").get();
+    if (!row || typeof row.revision !== "number" || !Number.isSafeInteger(row.revision) || row.revision < 0)
+        refuse("invalid custody revision schema");
+    return row.revision;
+}
+function advanceCustodyRevision(database) {
+    const revision = custodyRevision(database) + 1;
+    if (!Number.isSafeInteger(revision))
+        refuse("custody revision capacity");
+    database.prepare("UPDATE custody_meta SET revision=? WHERE singleton=1").run(revision);
+    return revision;
+}
+function hasRetiredCustodyInstance(database, input) {
+    const row = database.prepare(`SELECT key,host,session,instance,data FROM retired_instances WHERE host=? AND session=?
+    AND (instance IS NULL OR ? IS NULL OR instance=?) LIMIT 1`).get(input.host, input.session, input.instance, input.instance);
+    if (!row)
+        return false;
+    validateRetiredRow(row);
+    return true;
+}
+function retiredCustodyKey(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([input.host, input.session, input.instance])).digest("hex");
+}
+function readRetiredCustodyRecord(database, input) {
+    const row = database.prepare("SELECT key,host,session,instance,data FROM retired_instances WHERE key=?").get(retiredCustodyKey(input));
+    return row ? validateRetiredRow(row) : null;
+}
+function validateRetiredRow(row) {
+    if (Buffer.byteLength(row.data) > MAX_ROW)
+        refuse("retired instance index capacity");
+    const data = JSON.parse(row.data);
+    const expectedKey = retiredCustodyKey(row);
+    if (!object(data) || !object(data.proof) || row.key !== expectedKey || data.proof.kind !== "host_process_inventory"
+        || data.proof.host !== row.host || data.proof.session !== row.session || data.proof.instance !== row.instance
+        || data.proof.gone !== true || !timestamp(data.proof.checkedAt) || typeof data.proof.wholeSessionRetired !== "boolean"
+        || row.instance === null && !data.proof.wholeSessionRetired)
+        refuse("invalid retired instance schema");
+    if (data.archive !== undefined && (!object(data.archive) || typeof data.archive.path !== "string" || !path.isAbsolute(data.archive.path)
+        || typeof data.archive.digest !== "string" || !/^[a-f0-9]{64}$/.test(data.archive.digest)))
+        refuse("invalid retired archive reference schema");
+    return data;
+}
+function openCustodyDatabase(file, mode) {
+    const readonly = mode === "read" || mode === "maintenance-read";
     if (!path.isAbsolute(file) || path.normalize(file) !== file)
         refuse("database path");
-    privateDirectory(path.dirname(file));
-    try {
-        const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
-        fs.closeSync(fd);
-    }
-    catch (error) {
-        if (error.code !== "EEXIST")
-            throw error;
+    if (mode !== "maintenance" && mode !== "maintenance-read")
+        assertNoCustodyMaintenance(file);
+    if (!validateCustodyDirectory(path.dirname(file), !readonly))
+        return null;
+    if (readonly) {
+        if (!fs.lstatSync(file, { throwIfNoEntry: false }))
+            return null;
     }
-    privateFile(file);
-    const database = new better_sqlite3_1.default(file, { fileMustExist: true });
-    let warned = false;
-    function capacity(writing = false) {
-        const size = Number(database.pragma("page_count", { simple: true })) * Number(database.pragma("page_size", { simple: true }));
-        if (size > MAX_DB || writing && size + 65536 > MAX_DB)
-            refuse("database capacity; no input authorized");
-        if (!warned && size >= WARN_DB) {
-            warned = true;
-            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_checkin_capacity_warning",
-                message: "check-in custody is approaching capacity", meta: { bytes: size, limit: MAX_DB } });
+    else {
+        try {
+            const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            fs.closeSync(fd);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
         }
     }
+    privateFile(file);
+    for (const suffix of ["-journal", "-wal", "-shm"])
+        if (fs.lstatSync(`${file}${suffix}`, { throwIfNoEntry: false }))
+            privateFile(`${file}${suffix}`);
+    const database = new better_sqlite3_1.default(file, { fileMustExist: true, readonly });
     try {
         const version = database.pragma("user_version", { simple: true });
-        if (version !== 0 && version !== 1)
+        if (![0, 1, 2].includes(Number(version)) || version === 0 && readonly)
             refuse("unsupported database schema");
-        capacity();
-        database.pragma("journal_mode = DELETE");
+        custodyCapacity(database);
         database.pragma("busy_timeout = 1000");
+        if (version !== 0) {
+            database.prepare("SELECT id,host,session,instance,data FROM dispatches LIMIT 0").all();
+            database.prepare("SELECT signature,data FROM notices LIMIT 0").all();
+        }
+        if (readonly) {
+            if (version === 2)
+                validateCustodyV2(database);
+            return database;
+        }
+        database.pragma("journal_mode = DELETE");
+        database.pragma("synchronous = FULL");
         database.pragma(`max_page_count = ${Math.floor(MAX_DB / Number(database.pragma("page_size", { simple: true })))}`);
-        database.exec(`CREATE TABLE IF NOT EXISTS dispatches (
-      id TEXT PRIMARY KEY NOT NULL, host TEXT NOT NULL, session TEXT NOT NULL, instance TEXT, data TEXT NOT NULL
-    );
-    CREATE INDEX IF NOT EXISTS dispatch_barriers ON dispatches(host,session,instance);
-    CREATE TABLE IF NOT EXISTS notices (signature TEXT PRIMARY KEY NOT NULL, data TEXT NOT NULL);`);
-        database.pragma("user_version = 1");
+        if (version !== 2)
+            database.transaction(() => {
+                if (database.pragma("user_version", { simple: true }) === 2)
+                    return;
+                database.exec(`CREATE TABLE IF NOT EXISTS dispatches (
+        id TEXT PRIMARY KEY NOT NULL, host TEXT NOT NULL, session TEXT NOT NULL, instance TEXT, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS dispatch_barriers ON dispatches(host,session,instance);
+      CREATE TABLE IF NOT EXISTS notices (signature TEXT PRIMARY KEY NOT NULL, data TEXT NOT NULL);
+      CREATE TABLE custody_meta (singleton INTEGER PRIMARY KEY CHECK(singleton=1), revision INTEGER NOT NULL);
+      INSERT INTO custody_meta VALUES(1,0);
+      CREATE TABLE custody_requests (actor_id TEXT NOT NULL,request_id TEXT NOT NULL,hash TEXT NOT NULL,receipt TEXT NOT NULL,PRIMARY KEY(actor_id,request_id));
+      CREATE TABLE reconciliations (id TEXT PRIMARY KEY,dispatch_id TEXT NOT NULL,data TEXT NOT NULL);
+      CREATE INDEX reconciliation_dispatch ON reconciliations(dispatch_id);
+      CREATE TABLE retired_instances (key TEXT PRIMARY KEY,host TEXT NOT NULL,session TEXT NOT NULL,instance TEXT,data TEXT NOT NULL);
+      CREATE INDEX retired_scope ON retired_instances(host,session,instance);
+      CREATE TABLE custody_migrations (version INTEGER PRIMARY KEY,data TEXT NOT NULL);`);
+                for (const row of database.prepare("SELECT id,host,session,instance,data FROM dispatches").iterate())
+                    parseDispatch(row);
+                const counts = database.prepare("SELECT COUNT(*) AS count FROM dispatches").get();
+                database.prepare("INSERT INTO custody_migrations VALUES(2,?)").run(JSON.stringify({ fromVersion: version, at: new Date().toISOString(), preservedDispatches: counts.count }));
+                database.pragma("user_version = 2");
+            }).immediate();
+        validateCustodyV2(database);
+        for (const row of database.prepare("SELECT id,host,session,instance,data FROM dispatches").iterate())
+            parseDispatch(row);
     }
     catch (error) {
         database.close();
         throw error;
     }
-    const transact = (work) => database.transaction(() => { capacity(true); return work(); }).immediate();
+    return database;
+}
+function validateCustodyV2(database) {
+    custodyRevision(database);
+    for (const query of [
+        "SELECT actor_id,request_id,hash,receipt FROM custody_requests LIMIT 0",
+        "SELECT id,dispatch_id,data FROM reconciliations LIMIT 0",
+        "SELECT key,host,session,instance,data FROM retired_instances LIMIT 0",
+        "SELECT version,data FROM custody_migrations LIMIT 0",
+    ])
+        database.prepare(query).all();
+    for (const row of database.prepare("SELECT key,host,session,instance,data FROM retired_instances").iterate())
+        validateRetiredRow(row);
+}
+function openCheckInStore(file) {
+    const database = openCustodyDatabase(file, "write");
+    const transact = (work) => database.transaction(() => {
+        assertNoCustodyMaintenance(file);
+        custodyCapacity(database, true);
+        return work();
+    }).immediate();
     function write(record) {
         const data = JSON.stringify(record);
         if (Buffer.byteLength(data) > MAX_ROW)
             refuse("record byte limit");
         database.prepare(`INSERT INTO dispatches(id,host,session,instance,data) VALUES(?,?,?,?,?)
       ON CONFLICT(id) DO UPDATE SET data=excluded.data`).run(record.id, record.host, record.session, record.instance, data);
+        advanceCustodyRevision(database);
     }
     function notice(signature) {
         bounded(signature, MAX_ROW - 128, "signature");
@@ -169,9 +325,11 @@ function openCheckInStore(file) {
                 refuse("invalid dispatch input schema");
             bounded(owner, 256, "owner");
             const record = { ...input, id: dispatchId(input), owner, state: "claimed" };
-            if (bytes(record) + 1050 > MAX_ROW)
+            if (bytes(record) + COMPLETION_HEADROOM > MAX_ROW)
                 refuse("reserved record byte limit");
             return transact(() => {
+                if (hasRetiredCustodyInstance(database, input))
+                    return null;
                 const rows = database.prepare(`SELECT id,host,session,instance,data FROM dispatches
           WHERE id=? OR (host=? AND session=? AND (instance IS NULL OR ? IS NULL OR instance=?))`)
                     .all(record.id, input.host, input.session, input.instance, input.instance);
@@ -190,6 +348,10 @@ function openCheckInStore(file) {
                 refuse("invalid completion state");
             if (result.reason !== undefined)
                 bounded(result.reason, 1024, "reason");
+            if (result.receipt !== undefined && !validCustodyInputReceipt(result.receipt))
+                refuse("invalid host receipt schema");
+            if (result.receipt && !receiptMatchesOutcome(result.state, result.receipt))
+                refuse("host receipt contradicts completion outcome");
             transact(() => {
                 const row = database.prepare("SELECT id,host,session,instance,data FROM dispatches WHERE id=?").get(id);
                 if (!row)
@@ -197,7 +359,11 @@ function openCheckInStore(file) {
                 const prior = parseDispatch(row);
                 if (prior.owner !== owner || prior.state !== "claimed")
                     refuse("dispatch owner or phase mismatch");
-                write({ ...prior, state: result.state, ...(result.reason === undefined ? {} : { reason: result.reason }) });
+                if (result.receipt && (result.receipt.requestId !== id || result.receipt.surfaceId !== prior.session
+                    || result.receipt.processInstance !== prior.instance))
+                    refuse("host receipt identity mismatch");
+                write({ ...prior, state: result.state, ...(result.reason === undefined ? {} : { reason: result.reason }),
+                    ...(result.receipt === undefined ? {} : { receipt: copyCustodyInputReceipt(result.receipt) }) });
             });
         },
         shouldNotify(signature) { return notice(signature) === null; },
@@ -209,8 +375,10 @@ function openCheckInStore(file) {
             if (Buffer.byteLength(data) > MAX_ROW)
                 refuse("notice byte limit");
             transact(() => {
-                if (!notice(signature))
+                if (!notice(signature)) {
                     database.prepare("INSERT INTO notices(signature,data) VALUES(?,?)").run(signature, data);
+                    advanceCustodyRevision(database);
+                }
             });
         },
         close() { database.close(); },

package/dist/senses/shepherd/cmux.js

@@ -132,31 +132,46 @@ function createCmuxHost(client, options = {}) {
             (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_status_error", message: "could not clear a Shepherd status", meta: { error: error.message } });
         });
     };
-    async function surfaceEntries() {
+    async function surfaceEntries(strict = false) {
         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) => ({
-            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,
-            ...(surface.focused === true && workspace.selected === true && window.visible !== false && window.key === true
-                ? { selected: true } : {}),
-        })));
+        const records = (value) => {
+            if (strict && (!Array.isArray(value) || !value.every(isRecord)))
+                throw new Error("invalid cmux terminal inventory");
+            return list(value);
+        };
+        const seen = new Set();
+        return records(tree.windows).flatMap((window) => records(window.workspaces).map((workspace) => ({ window, workspace }))).flatMap(({ window, workspace }) => records(workspace.panes).flatMap((pane) => records(pane.surfaces)).map((surface) => {
+            if (strict && (typeof surface.id !== "string" || !surface.id.trim() || typeof surface.type !== "string"
+                || !["terminal", "browser"].includes(surface.type) || seen.has(surface.id)))
+                throw new Error("invalid cmux terminal inventory identity");
+            seen.add(str(surface.id) ?? "");
+            return {
+                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,
+                ...(surface.focused === true && workspace.selected === true && window.visible !== false && window.key === true
+                    ? { selected: true } : {}),
+            };
+        }));
+    }
+    async function retirementInventory() {
+        return (await surfaceEntries(true)).filter(surface => surface.type === "terminal").map(surface => surface.id);
     }
-    async function surfaces(freshFocus = false) {
-        const entries = await surfaceEntries();
+    async function surfaces(freshFocus = false, strictInventory = false) {
+        const entries = await surfaceEntries(strictInventory);
         const identities = await (options.identifyTerminals ?? terminal_process_1.identifyTerminalProcesses)(entries.filter((entry) => entry.type === "terminal" && entry.tty).map((entry) => entry.tty));
         // Process lookup is awaited. On inspection paths, do not return focus from
         // the tree sampled before that await. A moved/rebound TTY loses authority.
-        const current = freshFocus ? await surfaceEntries() : entries;
+        const current = freshFocus ? await surfaceEntries(strictInventory) : entries;
         return current.map((entry) => {
             const bound = entries.some(before => before.id === entry.id && before.tty === entry.tty && before.workspaceId === entry.workspaceId && before.type === entry.type);
             const identity = entry.tty && bound ? identities.get(entry.tty.replace(/^\/dev\//, "")) : undefined;
@@ -216,6 +231,7 @@ function createCmuxHost(client, options = {}) {
         async list() {
             return (await surfaces()).filter((surface) => surface.type === "terminal").map(({ workspaceId: _workspaceId, type: _type, ...session }) => session);
         },
+        retirementInventory,
         read,
         inspect,
         async promptIfUnchanged(sessionId, line, expected, canSend) {
@@ -390,16 +406,40 @@ function createCmuxHost(client, options = {}) {
                     },
                 });
             };
-            /** Terminals whose agent is not idle: output that changed and then held still for the quiet window is a return. */
+            let lastObserved = [];
+            /** Inventory reads stay outside the judge queue; idle-hook terminals are observed but never rejudged here. */
             const poll = async () => {
                 try {
-                    const terminals = (await surfaces()).filter((surface) => surface.type === "terminal" && hooked.get(surface.id)?.idle !== true);
+                    const terminals = (await surfaces(false, !!handlers.observed)).filter((surface) => surface.type === "terminal");
+                    if (closed)
+                        return;
                     const seen = new Set(terminals.map((surface) => surface.id));
                     for (const id of screens.keys())
                         if (!seen.has(id))
                             screens.delete(id);
+                    const rows = [];
                     for (const surface of terminals) {
-                        const hash = (0, node_crypto_1.createHash)("sha256").update(await read(surface.id, POLL_LINES)).digest("hex");
+                        const idle = hooked.get(surface.id)?.idle === true;
+                        if (idle)
+                            screens.delete(surface.id);
+                        if (idle && !handlers.observed)
+                            continue;
+                        let text;
+                        try {
+                            text = await read(surface.id, POLL_LINES);
+                        }
+                        catch (error) {
+                            rows.push({ session: surface, activity: "unknown", observedAt: null, error: "read_failed" });
+                            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_poll_error",
+                                message: "could not read one cmux terminal; other terminals remain observable", meta: { error: (0, redact_1.redactSecrets)(String(error)) } });
+                            continue;
+                        }
+                        if (closed)
+                            return;
+                        rows.push({ session: surface, activity: surface.agent ? (0, prompt_state_1.inspectCodingPrompt)(surface.agent, text).activity : "unknown", observedAt: now() });
+                        if (idle)
+                            continue;
+                        const hash = (0, node_crypto_1.createHash)("sha256").update(text).digest("hex");
                         const last = screens.get(surface.id);
                         const at = now();
                         if (!last)
@@ -413,9 +453,15 @@ function createCmuxHost(client, options = {}) {
                             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 });
                         }
                     }
+                    if (closed)
+                        return;
+                    lastObserved = rows;
+                    handlers.observed?.({ at: now(), sessions: rows });
                 }
                 catch (error) {
                     (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_cmux_poll_error", message: "could not poll cmux terminals; the next poll retries", meta: { error: error.message } });
+                    if (!closed)
+                        handlers.observed?.({ at: now(), sessions: lastObserved, error: "host_unavailable" });
                 }
                 if (!closed)
                     cancelPoll = schedule(() => void poll(), exports.POLL_MS);

package/dist/senses/shepherd/guidance.js

@@ -145,8 +145,8 @@ function bounded(value, name, max) {
 function knownTarget(root, target, live, record) {
     if (!validTarget(target))
         throw new Error("invalid Shepherd session target");
-    const known = record ?? [...(0, returns_1.readReturns)(root).filter(validReturn)].reverse().find(r => r.host === target.host && r.session === target.session)
-        ?? live.find(t => t.host === target.host && t.session === target.session);
+    const known = record ?? live.find(t => t.host === target.host && t.session === target.session)
+        ?? [...(0, returns_1.readReturns)(root).filter(validReturn)].reverse().find(r => r.host === target.host && r.session === target.session);
     if (!known)
         throw new Error("unknown session; no recorded or verified live Shepherd target");
     if (known.host !== target.host || known.session !== target.session || known.cwd !== target.cwd || known.task !== target.task)
@@ -191,6 +191,9 @@ async function mutate(root, op, input, apply) {
                 throw new Error("request ID was already used with a different body");
             return prior.receipt;
         }
+        if (input.expectedRevision !== undefined && (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0 || input.expectedRevision !== state.revision)) {
+            throw new Error("Shepherd guidance revision conflict");
+        }
         const clean = { actorId: input.actorId, requestId: input.requestId, at: new Date().toISOString(), kind: "operator instruction", returnId: null };
         const result = apply(state, clean);
         state.revision++;