@scotthuang/agent-knock-knock 0.14.13 → 0.14.15

package/dist/src/herdr-operation-capabilities.js

@@ -0,0 +1,66 @@
+import { inspectHerdrInputSchema } from "./herdr-api-contract.js";
+import { TerminalControlInputNotSentError } from "./terminal-control-provider.js";
+export function declaredHerdrInputCapabilities(cli, server) {
+    const mismatched = cli.version !== server.version;
+    if (mismatched || cli.schemaState === "unavailable") {
+        const capability = server.baselineKnown
+            ? { state: "available", reason: "verified release input behavior; no matching CLI schema", evidence: "verified_release" }
+            : { state: "unknown", reason: "no matching CLI schema or verified input behavior", evidence: "none" };
+        return { textInput: capability, keyInput: capability, rawTextInput: capability };
+    }
+    const declaration = inspectHerdrInputSchema(cli.schema, server.protocol);
+    const capability = (support) => ({
+        ...support,
+        evidence: support.state === "unknown" ? "none" : "matching_cli_schema"
+    });
+    return {
+        textInput: capability(declaration.textInput),
+        keyInput: capability(declaration.keyInput),
+        rawTextInput: capability(declaration.rawTextInput)
+    };
+}
+export function herdrControlCapabilities(operations) {
+    const readable = [operations.visibleText, operations.detectionText]
+        .some((capability) => capability.state === "available");
+    // Public Send is a composite text+Enter operation. Keep detailed partial
+    // input support in diagnostics instead of advertising an unusable Send.
+    const sendable = operations.textInput.state === "available" &&
+        operations.keyInput.state === "available";
+    return [
+        ...(readable ? ["screen_status", "screen_completion"] : []),
+        "durable_completion",
+        ...(sendable ? ["send_keys", "terminal_approval", "terminal_cancel"] : [])
+    ];
+}
+export function assertOperationAvailable(capabilities, operation) {
+    const capability = capabilities[operation];
+    if (capability.state !== "available") {
+        throw new Error(`Herdr ${operation} is ${capability.state}: ${capability.reason}`);
+    }
+}
+export function assertInputEndpointCapability(terminal, providerCapabilities, providerCapability, operations) {
+    if (terminal.identity.providerKind !== "herdr") {
+        throw new TerminalControlInputNotSentError(`terminal control provider herdr cannot use ${terminal.identity.providerKind}`);
+    }
+    if (!terminal.capabilities.includes("send_keys")) {
+        const detail = operations ? ["textInput", "keyInput"]
+            .filter((operation) => operations[operation].state !== "available")
+            .map((operation) => `${operation} is ${operations[operation].state}: ${operations[operation].reason}`)
+            .join("; ") : "";
+        throw new TerminalControlInputNotSentError(`Herdr terminal does not permit send_keys${detail ? `; ${detail}` : ""}`);
+    }
+    if (!providerCapabilities.includes(providerCapability)) {
+        throw new TerminalControlInputNotSentError(`Herdr provider does not support ${providerCapability}`);
+    }
+}
+/** Prefer agent detection for plain status; visible text is a bounded fallback. */
+export function selectHerdrReadOperation(capabilities, viewportOnly, preserveEscapes) {
+    if (preserveEscapes)
+        return { source: "visible", format: "ansi", operation: "visibleAnsi" };
+    if (viewportOnly || (capabilities.detectionText.state !== "available" &&
+        capabilities.visibleText.state === "available")) {
+        return { source: "visible", format: "text", operation: "visibleText" };
+    }
+    return { source: "detection", format: "text", operation: "detectionText" };
+}
+//# sourceMappingURL=herdr-operation-capabilities.js.map

package/dist/src/herdr-operation-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-operation-capabilities.js","sourceRoot":"","sources":["../../src/herdr-operation-capabilities.ts"],"names":[],"mappings":"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"}

package/dist/src/herdr-terminal-control-provider.d.ts

@@ -1,10 +1,10 @@
+import { type HerdrOperationCapabilities, type HerdrServerObservation } from "./herdr-compatibility.js";
+export { HERDR_EXACT_PROTOCOL, HERDR_EXACT_VERSION } from "./herdr-compatibility.js";
 import { type CommandResult, type TerminalDiscoveryDiagnosticLog, type TerminalControlProvider, type TerminalViewport } from "./terminal-control-provider.js";
 import { type TerminalControlCapability, type TerminalControlRef, type TerminalEndpointRef, type TerminalProviderCapability } from "./terminal-control-ref.js";
 import type { TerminalProcessSnapshot } from "./terminal-agent-adapter.js";
 import { type HerdrRequestFunction, type HerdrSocketIdentity } from "./herdr-socket-transport.js";
 export { HerdrApiError, HerdrTransportError, readHerdrSocketIdentity, requestHerdrUnixSocket, type HerdrRequestFunction, type HerdrRequestOptions, type HerdrSocketIdentity, type HerdrWireRequest } from "./herdr-socket-transport.js";
-export declare const HERDR_EXACT_VERSION = "0.8.0";
-export declare const HERDR_EXACT_PROTOCOL = 19;
 export interface HerdrTtyDeviceIdentity {
     device: string;
     inode: string;
@@ -32,14 +32,17 @@ export interface HerdrSessionInfo {
 export interface HerdrTerminalControlDiagnostics {
     commands: string[];
     selectedCommand?: string;
-    expectedVersion: string;
-    expectedProtocol: number;
     sessions: HerdrSessionInfo[];
     attempts: Array<{
         session: string;
         socketPath: string;
         status: "ok" | "error";
         paneCount?: number;
+        server?: HerdrServerObservation;
+        capabilities?: Array<{
+            paneId: string;
+            operations: HerdrOperationCapabilities;
+        }>;
         skippedWithoutShellPid?: string[];
         error?: string;
     }>;
@@ -56,7 +59,7 @@ export declare class HerdrTerminalControlProvider implements TerminalControlProv
     private readonly statSocket;
     private readonly inspectTtyViewport;
     private readonly diagnosticLog?;
-    private readonly endpointSocketIdentities;
+    private readonly endpointObservations;
     private requestSequence;
     constructor(options?: {
         command?: string;
@@ -83,13 +86,15 @@ export declare class HerdrTerminalControlProvider implements TerminalControlProv
     scrollHistoryDown(terminal: TerminalEndpointRef): Promise<void>;
     private logDiagnostic;
     private discoverSessions;
+    private inspectCliSchema;
     private probeCommand;
     private inspectSession;
+    private probeReadCapability;
     private assertCompatibleServer;
     private invoke;
     private resolveForInput;
     private sendInput;
-    private requireEndpointSocketIdentity;
+    private requireEndpointObservation;
 }
 export declare function parseHerdrSessionList(output: string): HerdrSessionInfo[];
 /** Translate the tmux-oriented bridge key vocabulary to Herdr key combos. */

package/dist/src/herdr-terminal-control-provider.js

@@ -2,12 +2,13 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { isRecord } from "./value-guards.js";
+import { matchesHerdrCompatibilityProfile, observeHerdrServer } from "./herdr-compatibility.js";
+import { assertInputEndpointCapability, assertOperationAvailable, declaredHerdrInputCapabilities, herdrControlCapabilities, selectHerdrReadOperation } from "./herdr-operation-capabilities.js";
+export { HERDR_EXACT_PROTOCOL, HERDR_EXACT_VERSION } from "./herdr-compatibility.js";
 import { TERMINAL_HISTORY_SCROLL_DOWN_BYTES, TerminalControlInputNotSentError, TerminalControlUnavailableError } from "./terminal-control-provider.js";
 import { createTerminalEndpointRef, herdrTerminalRouteKey, sameTerminalControlIncarnation, sameTerminalEndpointIdentity, terminalControlWithCapabilities, terminalEndpointFromControlRef } from "./terminal-control-ref.js";
 import { HERDR_DEFAULT_TIMEOUT_MS, HerdrApiError, HerdrTransportError, readHerdrSocketIdentity, requestHerdrUnixSocket, sameHerdrSocketIdentity } from "./herdr-socket-transport.js";
 export { HerdrApiError, HerdrTransportError, readHerdrSocketIdentity, requestHerdrUnixSocket } from "./herdr-socket-transport.js";
-export const HERDR_EXACT_VERSION = "0.8.0";
-export const HERDR_EXACT_PROTOCOL = 19;
 const HERDR_MAX_READ_LINES = 1_000;
 const HERDR_MAX_TTY_PATH_BYTES = 1_024;
 const HERDR_MAX_TTY_VIEWPORT_DIMENSION = 65_535;
@@ -55,7 +56,7 @@ export class HerdrTerminalControlProvider {
     statSocket;
     inspectTtyViewport;
     diagnosticLog;
-    endpointSocketIdentities = new WeakMap();
+    endpointObservations = new WeakMap();
     requestSequence = 0;
     constructor(options = {}) {
         this.commands = options.command
@@ -76,15 +77,14 @@ export class HerdrTerminalControlProvider {
         const diagnostics = {
             commands: [...this.commands],
             selectedCommand: this.selectedCommand,
-            expectedVersion: HERDR_EXACT_VERSION,
-            expectedProtocol: HERDR_EXACT_PROTOCOL,
             sessions: [],
             attempts: [],
             terminalCount: 0
         };
         let sessions;
+        let cli;
         try {
-            sessions = this.discoverSessions();
+            ({ sessions, cli } = this.discoverSessions());
             diagnostics.selectedCommand = this.selectedCommand;
             diagnostics.sessions = sessions;
         }
@@ -100,13 +100,18 @@ export class HerdrTerminalControlProvider {
         }
         for (const session of sessions.filter((candidate) => candidate.running)) {
             try {
-                const inspection = await this.inspectSession(session);
+                const inspection = await this.inspectSession(session, cli);
                 diagnostics.terminalCount += inspection.endpoints.length;
                 diagnostics.attempts.push({
                     session: session.name,
                     socketPath: session.socketPath,
                     status: "ok",
                     paneCount: inspection.endpoints.length,
+                    server: inspection.server,
+                    capabilities: inspection.endpoints.map((endpoint) => ({
+                        paneId: herdrControlFromEndpoint(endpoint).paneId,
+                        operations: this.requireEndpointObservation(endpoint).capabilities
+                    })),
                     skippedWithoutShellPid: inspection.skippedWithoutShellPid
                 });
             }
@@ -128,8 +133,10 @@ export class HerdrTerminalControlProvider {
             selected_command: this.selectedCommand
         });
         let sessions;
+        let cli;
         try {
-            sessions = this.discoverSessions().filter((session) => session.running);
+            ({ sessions, cli } = this.discoverSessions());
+            sessions = sessions.filter((session) => session.running);
         }
         catch (error) {
             if (error instanceof HerdrProviderUnavailableError) {
@@ -163,12 +170,12 @@ export class HerdrTerminalControlProvider {
         });
         const inspections = await Promise.all(sessions.map(async (session) => {
             try {
-                return await this.inspectSession(session);
+                return await this.inspectSession(session, cli);
             }
             catch (error) {
-                // A session running an incompatible Herdr release is unavailable to
-                // this exact-gated provider, but must not break discovery by another
-                // provider in the registry. Other live API failures remain fail-closed.
+                // Malformed or changing server observations cannot authorize endpoints.
+                // Other providers in the registry may still discover their own terminals.
+                // Other live API failures remain fail-closed.
                 if (error instanceof HerdrCompatibilityError) {
                     this.logDiagnostic("herdr_terminal_discovery", {
                         stage: "session_inspection",
@@ -222,10 +229,9 @@ export class HerdrTerminalControlProvider {
     toControlRef(terminal, capabilities = terminal.capabilities) {
         const control = herdrControlFromEndpoint(terminal);
         const next = terminalControlWithCapabilities(control, intersectCapabilities(intersectCapabilities(capabilities, terminal.capabilities), this.supportedCapabilities));
-        const socketIdentity = this.endpointSocketIdentities.get(terminal);
-        if (socketIdentity) {
-            this.endpointSocketIdentities.set(this.endpoint(next), socketIdentity);
-        }
+        const observation = this.endpointObservations.get(terminal);
+        if (observation)
+            this.endpointObservations.set(this.endpoint(next), observation);
         return next;
     }
     async resolve(terminal) {
@@ -238,18 +244,18 @@ export class HerdrTerminalControlProvider {
         if (matches.length !== 1) {
             throw new Error(`Herdr terminal resource ${terminal.route.label} is ambiguous`);
         }
-        const expectedSocketIdentity = this.endpointSocketIdentities.get(terminal);
-        const candidateSocketIdentity = this.endpointSocketIdentities.get(matches[0]);
+        const expectedSocketIdentity = this.endpointObservations.get(terminal)?.socketIdentity;
+        const candidateSocketIdentity = this.endpointObservations.get(matches[0])?.socketIdentity;
         if (expectedSocketIdentity &&
             (!candidateSocketIdentity || !sameHerdrSocketIdentity(expectedSocketIdentity, candidateSocketIdentity))) {
             throw new Error(`Herdr server socket changed while resolving ${terminal.route.label}`);
         }
-        const resolved = endpointWithCapabilities(matches[0], intersectCapabilities(terminal.capabilities, this.supportedCapabilities));
+        const resolved = endpointWithCapabilities(matches[0], intersectCapabilities(terminal.capabilities, matches[0].capabilities));
         const socketIdentity = candidateSocketIdentity;
         if (!socketIdentity) {
             throw new Error(`Herdr terminal resource ${terminal.route.label} is missing socket-incarnation evidence`);
         }
-        this.endpointSocketIdentities.set(resolved, socketIdentity);
+        this.endpointObservations.set(resolved, this.requireEndpointObservation(matches[0]));
         return resolved;
     }
     containsProcess(terminal, process, processes) {
@@ -285,15 +291,14 @@ export class HerdrTerminalControlProvider {
             throw new Error("Herdr terminal stable resource or process anchor changed before viewport inspection");
         }
         const control = herdrControlFromEndpoint(resolved);
-        const socketIdentity = this.requireEndpointSocketIdentity(resolved);
+        const socketIdentity = this.requireEndpointObservation(resolved).socketIdentity;
         const result = await this.invoke(control.socketPath, "session.snapshot", {}, { expectedSocketIdentity: socketIdentity });
         if (result.type !== "session_snapshot" || !isRecord(result.snapshot)) {
             throw new Error(`Herdr session ${control.session} returned an unexpected viewport snapshot`);
         }
-        if (result.snapshot.version !== HERDR_EXACT_VERSION ||
-            result.snapshot.protocol !== HERDR_EXACT_PROTOCOL) {
-            throw new HerdrCompatibilityError(`Herdr session ${control.session} viewport snapshot is not exact ` +
-                `${HERDR_EXACT_VERSION}/protocol ${HERDR_EXACT_PROTOCOL}`);
+        const server = this.requireEndpointObservation(resolved).server;
+        if (!matchesHerdrCompatibilityProfile(result.snapshot, server)) {
+            throw new HerdrCompatibilityError(`Herdr session ${control.session} viewport snapshot changed server compatibility`);
         }
         if (!Array.isArray(result.snapshot.panes)) {
             throw new Error(`Herdr session ${control.session} viewport snapshot panes are invalid`);
@@ -419,7 +424,7 @@ export class HerdrTerminalControlProvider {
             throw new Error("Herdr terminal stable resource or process anchor changed before capture");
         }
         const control = herdrControlFromEndpoint(resolved);
-        const socketIdentity = this.requireEndpointSocketIdentity(resolved);
+        const socketIdentity = this.requireEndpointObservation(resolved).socketIdentity;
         const requestedLines = Number.isFinite(options.scrollbackLines)
             ? Math.max(0, Math.floor(options.scrollbackLines ?? 200))
             : 200;
@@ -432,8 +437,10 @@ export class HerdrTerminalControlProvider {
         // means zero returned lines; an unbounded visible-source read instead
         // returns the viewport alone, still within the transport response limit.
         const viewportOnly = requestedLines === 0;
-        const source = options.preserveEscapes || viewportOnly ? "visible" : "detection";
-        const format = options.preserveEscapes ? "ansi" : "text";
+        const observation = this.requireEndpointObservation(resolved);
+        const { source, format, operation } = selectHerdrReadOperation(observation.capabilities, viewportOnly, options.preserveEscapes === true);
+        assertEndpointCapability(resolved, "screen_status");
+        assertOperationAvailable(observation.capabilities, operation);
         const result = await this.invoke(control.socketPath, "pane.read", {
             pane_id: control.paneId,
             // Herdr's recent scrollback may be empty for a live Claude alternate
@@ -457,7 +464,7 @@ export class HerdrTerminalControlProvider {
         return result.read.text;
     }
     async sendText(terminal, text) {
-        assertInputEndpointCapability(terminal, this.providerCapabilities, "text_delivery");
+        assertInputEndpointCapability(terminal, this.providerCapabilities, "text_delivery", this.endpointObservations.get(terminal)?.capabilities);
         if (text.length === 0) {
             return;
         }
@@ -465,7 +472,7 @@ export class HerdrTerminalControlProvider {
         await this.sendInput(resolved, { text });
     }
     async sendKeys(terminal, keys) {
-        assertInputEndpointCapability(terminal, this.providerCapabilities, "key_delivery");
+        assertInputEndpointCapability(terminal, this.providerCapabilities, "key_delivery", this.endpointObservations.get(terminal)?.capabilities);
         let translated;
         try {
             translated = keys.map(translateHerdrKey);
@@ -484,7 +491,7 @@ export class HerdrTerminalControlProvider {
         await this.sendInput(resolved, navigation ? { navigation } : { keys: translated });
     }
     async scrollHistoryDown(terminal) {
-        assertInputEndpointCapability(terminal, this.providerCapabilities, "key_delivery");
+        assertInputEndpointCapability(terminal, this.providerCapabilities, "key_delivery", this.endpointObservations.get(terminal)?.capabilities);
         const resolved = await this.resolveForInput(terminal);
         await this.sendInput(resolved, { navigation: "history-down" });
     }
@@ -503,16 +510,19 @@ export class HerdrTerminalControlProvider {
                 throw new HerdrProviderUnavailableError(version.stderr || version.error?.message ||
                     `failed to run ${command} --version`);
             }
-            const reportedVersion = version.stdout.trim();
-            if (reportedVersion !== `herdr ${HERDR_EXACT_VERSION}`) {
-                throw new HerdrProviderUnavailableError(`Herdr provider requires exact CLI ${HERDR_EXACT_VERSION}; ` +
-                    `found ${reportedVersion || "unknown"}`);
-            }
             const result = this.runCommand(command, ["session", "list", "--json"]);
             if (result.status !== 0) {
                 throw new HerdrProviderUnavailableError(result.stderr || result.error?.message || "herdr session list failed");
             }
-            return parseHerdrSessionList(result.stdout);
+            const sessions = parseHerdrSessionList(result.stdout);
+            const cli = {
+                version: /^herdr\s+(\S+)$/u.exec(version.stdout.trim())?.[1],
+                schemaState: "unavailable"
+            };
+            if (sessions.some((session) => session.running)) {
+                this.inspectCliSchema(command, cli);
+            }
+            return { sessions, cli };
         }
         catch (error) {
             if (error instanceof HerdrProviderUnavailableError) {
@@ -521,6 +531,28 @@ export class HerdrTerminalControlProvider {
             throw new HerdrProviderUnavailableError(`Herdr provider is unavailable: ${describeError(error)}`, { cause: error });
         }
     }
+    inspectCliSchema(command, cli) {
+        let result;
+        try {
+            result = this.runCommand(command, ["api", "schema", "--json"]);
+        }
+        catch {
+            return;
+        }
+        if (result.status !== 0)
+            return;
+        // Successful but unreadable declarations must not be masked by a baseline.
+        cli.schemaState = "malformed";
+        if (Buffer.byteLength(result.stdout) > 10 * 1024 * 1024)
+            return;
+        try {
+            cli.schema = JSON.parse(result.stdout);
+            cli.schemaState = "available";
+        }
+        catch {
+            // Keep discovery and independently probed reads available.
+        }
+    }
     probeCommand() {
         if (this.selectedCommand) {
             return {
@@ -536,14 +568,14 @@ export class HerdrTerminalControlProvider {
                 lastError = result.error;
                 continue;
             }
-            // Once a candidate starts, pin it. A version mismatch or any later
+            // Once a candidate starts, pin it. Any later
             // failure must not silently switch to a different installation.
             this.selectedCommand = command;
             return { command, version: result };
         }
         throw new HerdrProviderUnavailableError(lastError?.message || "no Herdr executable candidate could be started", { cause: lastError });
     }
-    async inspectSession(session) {
+    async inspectSession(session, cli) {
         let socketIdentity;
         try {
             socketIdentity = this.statSocket(session.socketPath);
@@ -568,13 +600,16 @@ export class HerdrTerminalControlProvider {
             });
             throw error;
         }
+        let profile;
         try {
-            await this.assertCompatibleServer(session, socketIdentity);
+            profile = await this.assertCompatibleServer(session, socketIdentity);
             this.logDiagnostic("herdr_session_observation", {
                 session: session.name,
                 socket_path: session.socketPath,
                 stage: "ping",
-                status: "available"
+                status: "available",
+                version: profile.version,
+                protocol: profile.protocol
             });
         }
         catch (error) {
@@ -606,10 +641,9 @@ export class HerdrTerminalControlProvider {
         if (result.type !== "session_snapshot" || !isRecord(result.snapshot)) {
             throw new Error(`Herdr session ${session.name} returned an unexpected session.snapshot result`);
         }
-        if (result.snapshot.version !== HERDR_EXACT_VERSION ||
-            result.snapshot.protocol !== HERDR_EXACT_PROTOCOL) {
+        if (!matchesHerdrCompatibilityProfile(result.snapshot, profile)) {
             throw new HerdrCompatibilityError(`Herdr session ${session.name} snapshot is not exact ` +
-                `${HERDR_EXACT_VERSION}/protocol ${HERDR_EXACT_PROTOCOL}`);
+                `${profile.version}/protocol ${profile.protocol}`);
         }
         if (!Array.isArray(result.snapshot.panes)) {
             throw new Error(`Herdr session ${session.name} snapshot panes are invalid`);
@@ -678,6 +712,17 @@ export class HerdrTerminalControlProvider {
                 throw error;
             }
         }));
+        const inputCapabilities = declaredHerdrInputCapabilities(cli, profile);
+        const operations = await Promise.all(panes.map(async (pane, index) => {
+            if (!positiveInteger(processInfos[index]?.shellPid))
+                return undefined;
+            const [visibleText, visibleAnsi, detectionText] = await Promise.all([
+                this.probeReadCapability(session, pane, socketIdentity, "visible", "text"),
+                this.probeReadCapability(session, pane, socketIdentity, "visible", "ansi"),
+                this.probeReadCapability(session, pane, socketIdentity, "detection", "text")
+            ]);
+            return { visibleText, visibleAnsi, detectionText, ...inputCapabilities };
+        }));
         // A server restart can reuse a public pane route while representing a new
         // PTY. Re-read the authoritative snapshot after process inspection and
         // only join process data to a pane whose stable terminal identity and
@@ -699,8 +744,7 @@ export class HerdrTerminalControlProvider {
         }
         if (verifiedSnapshotResult.type !== "session_snapshot" ||
             !isRecord(verifiedSnapshotResult.snapshot) ||
-            verifiedSnapshotResult.snapshot.version !== HERDR_EXACT_VERSION ||
-            verifiedSnapshotResult.snapshot.protocol !== HERDR_EXACT_PROTOCOL ||
+            !matchesHerdrCompatibilityProfile(verifiedSnapshotResult.snapshot, profile) ||
             !Array.isArray(verifiedSnapshotResult.snapshot.panes)) {
             throw new Error(`Herdr session ${session.name} changed during terminal discovery`);
         }
@@ -756,8 +800,10 @@ export class HerdrTerminalControlProvider {
                 });
                 continue;
             }
-            const endpoint = endpointFromPane(session, verifiedPane, processInfo, this.supportedCapabilities);
-            this.endpointSocketIdentities.set(endpoint, socketIdentity);
+            const endpoint = endpointFromPane(session, verifiedPane, processInfo, herdrControlCapabilities(operations[index]));
+            this.endpointObservations.set(endpoint, {
+                socketIdentity, server: profile, capabilities: operations[index]
+            });
             endpoints.push(endpoint);
             this.logDiagnostic("herdr_pane_endpoint_observation", {
                 session: session.name,
@@ -779,7 +825,40 @@ export class HerdrTerminalControlProvider {
             endpoint_count: endpoints.length,
             skipped_without_shell_pid: skippedWithoutShellPid
         });
-        return { session, endpoints, skippedWithoutShellPid };
+        return { session, server: profile, endpoints, skippedWithoutShellPid };
+    }
+    async probeReadCapability(session, pane, socketIdentity, source, format) {
+        try {
+            const result = await this.invoke(session.socketPath, "pane.read", {
+                pane_id: pane.paneId, source, format, lines: 0
+            }, { expectedSocketIdentity: socketIdentity });
+            const read = result.read;
+            if (result.type !== "pane_read" || !isRecord(read) ||
+                read.pane_id !== pane.paneId || read.workspace_id !== pane.workspaceId ||
+                read.tab_id !== pane.tabId || read.source !== source || read.format !== format ||
+                read.text !== "" || !Number.isSafeInteger(read.revision) ||
+                read.revision < 0 || typeof read.truncated !== "boolean") {
+                return { state: "unknown", reason: "zero-line read returned invalid pane data", evidence: "none" };
+            }
+            return {
+                state: "available",
+                reason: `pane.read accepted zero-line ${source}/${format} response`,
+                evidence: "runtime_probe"
+            };
+        }
+        catch (error) {
+            const unsupported = error instanceof HerdrApiError && [
+                "invalid_request", "unknown_method", "method_not_found", "unsupported_method",
+                "unsupported_source", "unsupported_format"
+            ].includes(error.code);
+            return {
+                state: unsupported ? "unsupported" : "unknown",
+                reason: error instanceof HerdrApiError
+                    ? `pane.read rejected ${source}/${format}: ${error.code}`
+                    : `pane.read ${source}/${format} probe failed`,
+                evidence: unsupported ? "runtime_probe" : "none"
+            };
+        }
     }
     async assertCompatibleServer(session, socketIdentity) {
         let result;
@@ -788,18 +867,15 @@ export class HerdrTerminalControlProvider {
         }
         catch (error) {
             if (error instanceof HerdrApiError && error.code === "protocol_mismatch") {
-                throw new HerdrCompatibilityError(`Herdr session ${session.name} rejected protocol ${HERDR_EXACT_PROTOCOL}`);
+                throw new HerdrCompatibilityError(`Herdr session ${session.name} rejected the API protocol`);
             }
             throw error;
         }
-        if (result.type !== "pong" ||
-            result.version !== HERDR_EXACT_VERSION ||
-            result.protocol !== HERDR_EXACT_PROTOCOL) {
-            throw new HerdrCompatibilityError(`Herdr session ${session.name} requires exact server ` +
-                `${HERDR_EXACT_VERSION}/protocol ${HERDR_EXACT_PROTOCOL}; found ` +
-                `${String(result.version ?? "unknown")}/protocol ` +
-                `${String(result.protocol ?? "unknown")}`);
+        const profile = observeHerdrServer(result);
+        if (result.type !== "pong" || !profile) {
+            throw new HerdrCompatibilityError(`Herdr session ${session.name} returned malformed server version/protocol metadata`);
         }
+        return profile;
     }
     async invoke(socketPath, method, params, options = {}) {
         const request = {
@@ -831,9 +907,13 @@ export class HerdrTerminalControlProvider {
             if (!sameTerminalControlIncarnation(terminal, resolved)) {
                 throw new Error("Herdr terminal stable resource or process anchor changed before input");
             }
+            const observation = this.requireEndpointObservation(resolved);
+            assertOperationAvailable(observation.capabilities, "textInput");
+            assertOperationAvailable(observation.capabilities, "keyInput");
+            assertEndpointCapability(resolved, "send_keys");
             return {
                 control: herdrControlFromEndpoint(resolved),
-                socketIdentity: this.requireEndpointSocketIdentity(resolved)
+                observation
             };
         }
         catch (error) {
@@ -843,10 +923,18 @@ export class HerdrTerminalControlProvider {
         }
     }
     async sendInput(resolved, params) {
-        const { control, socketIdentity } = resolved;
+        const { control, observation } = resolved;
+        const { socketIdentity } = observation;
         // pane.send_input.text is bracketed paste. Only closed fixed navigation
         // uses pane.send_text's direct PTY bytes; callers cannot supply raw data.
         const method = "navigation" in params ? "pane.send_text" : "pane.send_input";
+        try {
+            assertOperationAvailable(observation.capabilities, "navigation" in params ? "rawTextInput" :
+                "text" in params ? "textInput" : "keyInput");
+        }
+        catch (error) {
+            throw new TerminalControlInputNotSentError(describeError(error));
+        }
         const input = "navigation" in params
             ? { text: HERDR_NAVIGATION_KEY_BYTES[params.navigation] } : params;
         try {
@@ -861,21 +949,21 @@ export class HerdrTerminalControlProvider {
             }
         }
         catch (error) {
-            if (inputDefinitelyNotSent(error)) {
+            if (inputDefinitelyNotSent(error, observation.server.baselineKnown)) {
                 throw new TerminalControlInputNotSentError(`Herdr input was not sent: ${describeError(error)}`);
             }
-            // Request ids are correlation only. Herdr 0.8.0 has no idempotency key,
-            // so a post-connect timeout, EOF, malformed response, or lost ACK must
+            // Request ids provide correlation, not replay authority. A post-connect
+            // timeout, EOF, malformed response, or lost ACK must
             // remain uncertain and must never be retried here.
             throw error;
         }
     }
-    requireEndpointSocketIdentity(terminal) {
-        const identity = this.endpointSocketIdentities.get(terminal);
-        if (!identity) {
+    requireEndpointObservation(terminal) {
+        const observation = this.endpointObservations.get(terminal);
+        if (!observation) {
             throw new Error(`Herdr terminal resource ${terminal.route.label} is missing socket-incarnation evidence`);
         }
-        return identity;
+        return observation;
     }
 }
 export function parseHerdrSessionList(output) {
@@ -1119,27 +1207,18 @@ function assertEndpointCapability(terminal, capability) {
         throw new Error(`Herdr terminal does not permit ${capability}`);
     }
 }
-function assertInputEndpointCapability(terminal, providerCapabilities, providerCapability) {
-    try {
-        assertEndpointCapability(terminal, "send_keys");
-    }
-    catch (error) {
-        throw new TerminalControlInputNotSentError(describeError(error));
-    }
-    if (!providerCapabilities.includes(providerCapability)) {
-        throw new TerminalControlInputNotSentError(`Herdr provider does not support ${providerCapability}`);
-    }
-}
 function assertProviderCapability(capabilities, capability) {
     if (!capabilities.includes(capability)) {
         throw new Error(`Herdr provider does not support ${capability}`);
     }
 }
-function inputDefinitelyNotSent(error) {
+function inputDefinitelyNotSent(error, baselineKnown) {
     if (error instanceof HerdrTransportError) {
         return error.definitelyNotSent;
     }
-    return error instanceof HerdrApiError && new Set([
+    // Unknown releases may reuse an error code after an input effect. A schema
+    // declaration does not establish the server's failure/queue semantics.
+    return baselineKnown && error instanceof HerdrApiError && new Set([
         "invalid_request",
         "invalid_key",
         "pane_not_found",