@termwright/mcp 0.2.0 → 0.3.0

package/dist/{chunk-IPNUAUAN.js → chunk-ROMJP5D3.js}

@@ -45,7 +45,9 @@ var crashSchema = z.object({
 function boundLines(lines) {
   const kept = lines.slice(-CRASH_LIMITS.maxScreenTailLines);
   return {
-    lines: kept.map((line) => line.length > CRASH_LIMITS.maxLineChars ? `${line.slice(0, CRASH_LIMITS.maxLineChars)}\u2026` : line),
+    lines: kept.map(
+      (line) => line.length > CRASH_LIMITS.maxLineChars ? `${line.slice(0, CRASH_LIMITS.maxLineChars)}\u2026` : line
+    ),
     truncated: kept.length < lines.length
   };
 }
@@ -104,7 +106,11 @@ var CrashContextError = class extends Error {
 };
 
 // src/errors.ts
-var MCP_ERROR_KINDS = ["usage", "no-session", "internal"];
+var MCP_ERROR_KINDS = [
+  "usage",
+  "no-session",
+  "internal"
+];
 var EXIT_CODES = Object.freeze({
   ok: 0,
   assertion: 1,
@@ -124,6 +130,7 @@ function exitCodeFor(kind) {
       return EXIT_CODES.usage;
     case "protocol-violation":
       return EXIT_CODES.ipc;
+    case "pty-backend-failed":
     case "internal":
       return EXIT_CODES.internal;
     default:
@@ -182,8 +189,10 @@ function renderErrorPayload(payload) {
   if (payload.suggestion !== void 0) parts.push(`suggestion: ${payload.suggestion}`);
   if (payload.semanticTree !== void 0) parts.push(`semanticTree: ${payload.semanticTree}`);
   if (payload.candidates !== void 0) {
-    parts.push(`candidates:
-${payload.candidates.map((candidate) => `  - ${candidate}`).join("\n")}`);
+    parts.push(
+      `candidates:
+${payload.candidates.map((candidate) => `  - ${candidate}`).join("\n")}`
+    );
   }
   if (payload.screenExcerpt !== void 0) parts.push(`screen:
 ${payload.screenExcerpt}`);
@@ -392,7 +401,14 @@ var LogBuffer = class {
   append(event) {
     this.#counter += 1;
     this.#entries.push(toEntry(event, this.#counter));
-    if (this.#entries.length > this.#capacity) this.#entries.splice(0, this.#entries.length - this.#capacity);
+    if (this.#entries.length > this.#capacity)
+      this.#entries.splice(0, this.#entries.length - this.#capacity);
+  }
+  /** Advances the cursor for source events that were explicitly reported lost. */
+  omit(count) {
+    if (!Number.isSafeInteger(count) || count <= 0)
+      throw new TypeError("omitted log count must be a positive safe integer");
+    this.#counter += count;
   }
   /**
    * Everything after `cursor`, newest-biased and bounded.
@@ -456,7 +472,10 @@ var TerminalStore = class {
   #counter = 0;
   constructor(options) {
     this.sessionKey = options.sessionKey;
-    this.#directory = join(options.storageDir ?? join(tmpdir(), "termwright-mcp"), options.sessionKey);
+    this.#directory = join(
+      options.storageDir ?? join(tmpdir(), "termwright-mcp"),
+      options.sessionKey
+    );
     this.#maxTerminals = options.maxTerminals ?? MCP_LIMITS.maxTerminals;
     this.#now = options.now ?? Date.now;
   }
@@ -490,10 +509,14 @@ var TerminalStore = class {
       ...request.semanticNegotiationMs === void 0 ? {} : { semanticNegotiationMs: request.semanticNegotiationMs },
       ...request.timeouts === void 0 ? {} : { timeouts: definedOnly(request.timeouts) },
       ...request.logs === void 0 ? {} : {
-        logs: request.logs.flatMap((source) => source.path === void 0 ? [] : [{
-          path: source.path,
-          ...source.label === void 0 ? {} : { label: source.label }
-        }])
+        logs: request.logs.flatMap(
+          (source) => source.path === void 0 ? [] : [
+            {
+              path: source.path,
+              ...source.label === void 0 ? {} : { label: source.label }
+            }
+          ]
+        )
       }
     };
     const harness = await launchTerminal(options);
@@ -509,15 +532,21 @@ var TerminalStore = class {
       history: [],
       logs: new LogBuffer()
     };
-    harness.events.on("app-log", (event) => {
-      entry.logs.append(event);
-    });
+    harness.events.subscribe(
+      {
+        fromSequence: 1,
+        onGap: (gap) => entry.logs.omit(Math.max(1, gap.lostEvents))
+      },
+      (recorded) => {
+        if (recorded.type === "app-log") entry.logs.append(recorded.payload);
+      }
+    );
     void harness.exit.then(
       (status) => {
         entry.exit = status;
       },
-      () => {
-        entry.exit = { code: null, signal: null };
+      (error) => {
+        entry.exitFailure = error;
       }
     );
     this.#terminals.set(id, entry);
@@ -545,18 +574,20 @@ var TerminalStore = class {
    */
   record(entry) {
     const screen = entry.harness.screen();
+    const existing = entry.history.find((item) => item.revision === screen.revision);
+    if (existing !== void 0) return existing;
     const semantic = entry.harness.semanticTree();
     const record = {
       revision: screen.revision,
       semanticRevision: semantic?.revision ?? null,
       rows: screen.text().split("\n"),
       semantic,
-      logSeq: entry.logs.sequence,
+      // The first cursor covers startup too. Logs can arrive while launch waits
+      // for capability negotiation, before an MCP caller can obtain a cursor.
+      logSeq: entry.history.length === 0 ? 0 : entry.logs.sequence,
       capturedAt: this.#now()
     };
-    entry.history = [...entry.history.filter((item) => item.revision !== record.revision), record].slice(
-      -MCP_LIMITS.maxHistory
-    );
+    entry.history = [...entry.history, record].slice(-MCP_LIMITS.maxHistory);
     return record;
   }
   /** The recorded baseline for a cursor, or a `history-truncated` failure. */
@@ -588,16 +619,20 @@ var TerminalStore = class {
   /** Closes every terminal; failures are swallowed so shutdown always completes. */
   async closeAll() {
     const entries = [...this.#terminals.values()];
-    this.#terminals.clear();
+    const failures = [];
     await Promise.all(
       entries.map(async (entry) => {
         try {
           await entry.harness.close();
-        } catch {
+          entry.closed = true;
+          this.#terminals.delete(entry.id);
+        } catch (error) {
+          failures.push(error);
         }
-        entry.closed = true;
       })
     );
+    if (failures.length > 0)
+      throw new AggregateError(failures, "one or more MCP terminals failed to close");
   }
 };
 function createSessionStores(options) {
@@ -610,7 +645,11 @@ function createSessionStores(options) {
   };
 }
 async function closeSessionStores(stores) {
-  await Promise.all([stores.terminals.closeAll(), stores.traces.closeAll()]);
+  const results = await Promise.allSettled([stores.terminals.closeAll(), stores.traces.closeAll()]);
+  const failures = results.flatMap(
+    (result) => result.status === "rejected" ? [result.reason] : []
+  );
+  if (failures.length > 0) throw new AggregateError(failures, "MCP session stores failed to close");
 }
 var SessionRegistry = class {
   #sessions = /* @__PURE__ */ new Map();
@@ -620,14 +659,18 @@ var SessionRegistry = class {
   #now;
   #disposeAttachment;
   #onExpired;
+  #onBackgroundError;
   #sweeper;
+  #sweepTask;
+  #sweeperStopped = true;
   constructor(options = {}) {
     this.#maxSessions = options.maxSessions ?? MCP_LIMITS.maxSessions;
     this.#storageDir = options.storageDir;
     this.#idleTtlMs = options.idleTtlMs ?? 0;
-    this.#now = options.now ?? Date.now;
+    this.#now = options.now ?? (() => performance.now());
     this.#disposeAttachment = options.disposeAttachment;
     this.#onExpired = options.onExpired;
+    this.#onBackgroundError = options.onBackgroundError;
   }
   /** The configured idle ceiling; `0` when expiry is disabled. */
   get idleTtlMs() {
@@ -666,16 +709,29 @@ var SessionRegistry = class {
    */
   startIdleSweeper(intervalMs = Math.min(Math.max(this.#idleTtlMs / 4, 1e3), 6e4)) {
     if (this.#idleTtlMs <= 0) return () => void 0;
-    this.#sweeper = setInterval(() => {
-      void this.sweepIdle();
-    }, intervalMs);
-    this.#sweeper.unref?.();
+    if (!this.#sweeperStopped) return () => this.stopIdleSweeper();
+    this.#sweeperStopped = false;
+    const schedule = () => {
+      if (this.#sweeperStopped) return;
+      this.#sweeper = setTimeout(() => {
+        this.#sweeper = void 0;
+        const task = this.sweepIdle();
+        this.#sweepTask = task;
+        void task.catch((error) => this.#onBackgroundError?.(error)).finally(() => {
+          if (this.#sweepTask === task) this.#sweepTask = void 0;
+          schedule();
+        });
+      }, intervalMs);
+      this.#sweeper.unref?.();
+    };
+    schedule();
     return () => this.stopIdleSweeper();
   }
   /** Stops the sweeper started by {@link startIdleSweeper}. Idempotent. */
   stopIdleSweeper() {
+    this.#sweeperStopped = true;
     if (this.#sweeper === void 0) return;
-    clearInterval(this.#sweeper);
+    clearTimeout(this.#sweeper);
     this.#sweeper = void 0;
   }
   get size() {
@@ -709,21 +765,35 @@ var SessionRegistry = class {
     return this.#sessions.get(key);
   }
   /** Removes a session and closes everything it owned. */
-  async delete(key) {
+  delete(key) {
     const session = this.#sessions.get(key);
-    if (session === void 0) return;
-    this.#sessions.delete(key);
-    await closeSessionStores(session.stores);
-    try {
-      await this.#disposeAttachment?.(session.attachment);
-    } catch {
-    }
+    if (session === void 0) return Promise.resolve();
+    if (session.closing !== void 0) return session.closing;
+    session.closing = (async () => {
+      const results = await Promise.allSettled([
+        closeSessionStores(session.stores),
+        Promise.resolve().then(() => this.#disposeAttachment?.(session.attachment))
+      ]);
+      const failures = results.flatMap(
+        (result) => result.status === "rejected" ? [result.reason] : []
+      );
+      if (failures.length > 0)
+        throw new AggregateError(failures, `MCP session ${key} failed to close`);
+      this.#sessions.delete(key);
+    })();
+    return session.closing;
   }
   /** Closes every session and stops the sweeper. */
   async closeAll() {
     this.stopIdleSweeper();
+    await this.#sweepTask?.catch(() => void 0);
     const keys = [...this.#sessions.keys()];
-    await Promise.all(keys.map(async (key) => this.delete(key)));
+    const results = await Promise.allSettled(keys.map(async (key) => this.delete(key)));
+    const failures = results.flatMap(
+      (result) => result.status === "rejected" ? [result.reason] : []
+    );
+    if (failures.length > 0)
+      throw new AggregateError(failures, "one or more MCP sessions failed to close");
   }
 };
 
@@ -771,7 +841,7 @@ function renderScreenshot(frame2, request = {}) {
     });
   } catch (error) {
     throw new McpError(
-      "unsupported-action",
+      "capability-unavailable",
       `the screenshot renderer failed: ${error instanceof Error ? error.message : String(error)}`,
       "omit screenshot \u2014 the tool still returns the screen as text and the compact tree"
     );
@@ -795,13 +865,14 @@ function renderScreenshot(frame2, request = {}) {
 
 // src/format.ts
 function formatRef(nodeId, revision) {
-  return `${nodeId}@${revision}`;
+  return `semantic:${nodeId}@${revision}`;
 }
 function parseRef(ref) {
-  const at = ref.lastIndexOf("@");
-  if (at <= 0) return null;
-  const nodeId = ref.slice(0, at);
-  const revision = Number(ref.slice(at + 1));
+  const match = /^semantic:([^@\s]+)@(\d+)$/u.exec(ref);
+  if (match === null) return null;
+  const nodeId = match[1];
+  const revision = Number(match[2]);
+  if (nodeId === void 0) return null;
   if (!Number.isInteger(revision) || revision < 0) return null;
   return { nodeId, revision };
 }
@@ -822,6 +893,8 @@ function stateFlags(state) {
 function formatNodeLine(entry) {
   const parts = [`${entry.role} ${JSON.stringify(entry.name)}`, `ref=${entry.ref}`];
   if (entry.bounds !== void 0) parts.push(`bounds=${formatBounds(entry.bounds)}`);
+  if (entry.applicationScroll !== void 0) parts.push(`app-scroll=${entry.applicationScroll}`);
+  if (entry.paintedRegion !== void 0) parts.push(`painted=${entry.paintedRegion}`);
   return [...parts, ...entry.flags].join(" ");
 }
 function walkSnapshot(snapshot2) {
@@ -851,18 +924,27 @@ function walkSnapshot(snapshot2) {
   return out;
 }
 function refEntries(snapshot2) {
-  return walkSnapshot(snapshot2).map(({ node, depth }) => toRefEntry(node, snapshot2.revision, depth));
+  return walkSnapshot(snapshot2).map(
+    ({ node, depth }) => toRefEntry(node, snapshot2.revision, depth)
+  );
 }
 function toRefEntry(node, revision, depth = 0) {
+  const visibleRect = node.geometry.visibleRect;
   return {
     ref: formatRef(node.id, revision),
     role: node.role,
     name: node.name,
     depth,
-    ...node.bounds === void 0 ? {} : { bounds: node.bounds },
+    ...visibleRect.status === "known" ? { bounds: visibleRect.value } : {},
     flags: stateFlags(node.state),
     ...node.testId === void 0 ? {} : { testId: node.testId },
-    ...node.value === void 0 ? {} : { value: node.value }
+    ...node.value?.status === "known" && node.value.sensitivity === "public" ? { value: node.value.value } : {},
+    ...node.scroll?.status === "known" ? {
+      applicationScroll: `${node.scroll.value.axis}:${node.scroll.value.offset}+${node.scroll.value.viewport}/${node.scroll.value.extent}`
+    } : {},
+    ...node.paintedRegion?.status === "known" ? {
+      paintedRegion: `${formatBounds(node.paintedRegion.value.regionBounds)}:${node.paintedRegion.value.spans.length}-spans`
+    } : {}
   };
 }
 var DEFAULT_MAX_NODES = 500;
@@ -903,7 +985,7 @@ function diffRows(before, after) {
   return changes;
 }
 function nodeChanged(before, after) {
-  return before.role !== after.role || before.name !== after.name || before.value !== after.value || before.testId !== after.testId || before.description !== after.description || before.parentId !== after.parentId || JSON.stringify(before.bounds ?? null) !== JSON.stringify(after.bounds ?? null) || JSON.stringify(before.state ?? null) !== JSON.stringify(after.state ?? null);
+  return before.role !== after.role || before.name !== after.name || before.value !== after.value || before.testId !== after.testId || before.description !== after.description || before.parentId !== after.parentId || JSON.stringify(before.geometry) !== JSON.stringify(after.geometry) || JSON.stringify(before.state ?? null) !== JSON.stringify(after.state ?? null) || JSON.stringify(before.scroll ?? null) !== JSON.stringify(after.scroll ?? null) || JSON.stringify(before.paintedRegion ?? null) !== JSON.stringify(after.paintedRegion ?? null);
 }
 function indexById(snapshot2) {
   const index = /* @__PURE__ */ new Map();
@@ -975,6 +1057,7 @@ function diffSemantic(before, after) {
 }
 
 // src/targets.ts
+import { parseRef as parseRef2 } from "@termwright/driver/experimental";
 var REGEX_LITERAL = /^\/(.*)\/([gimsuy]*)$/su;
 function textOrRegExp(value) {
   const match = REGEX_LITERAL.exec(value);
@@ -989,11 +1072,17 @@ function textOrRegExp(value) {
   }
 }
 function hasTarget(input) {
-  return input.ref !== void 0 || input.selector !== void 0 || input.role !== void 0 || input.testId !== void 0 || input.text !== void 0 || input.label !== void 0;
+  return input.ref !== void 0 || input.selector !== void 0 || input.role !== void 0 || input.testId !== void 0 || input.text !== void 0 || input.screenText !== void 0 || input.label !== void 0;
 }
 function buildLocator(harness, input) {
   let locator;
   if (input.ref !== void 0) {
+    if (parseRef2(input.ref) === null) {
+      throw usageError(
+        "ref must include an explicit locator domain",
+        "use semantic:<node>@<revision> or screen:<row>,<column>,<width>,<height>@<revision>"
+      );
+    }
     locator = harness.locatorForRef(input.ref);
   } else if (input.selector !== void 0) {
     locator = harness.locator(input.selector);
@@ -1012,10 +1101,15 @@ function buildLocator(harness, input) {
     locator = harness.getByLabel(textOrRegExp(input.label), definedOnly({ exact: input.exact }));
   } else if (input.text !== void 0) {
     locator = harness.getByText(textOrRegExp(input.text), definedOnly({ exact: input.exact }));
+  } else if (input.screenText !== void 0) {
+    locator = harness.getByScreenText(
+      textOrRegExp(input.screenText),
+      definedOnly({ exact: input.exact })
+    );
   } else {
     throw usageError(
       "no target given",
-      "pass one of ref, selector, testId, role (+name), label or text"
+      "pass one of ref, selector, testId, role (+name), label, text or screenText"
     );
   }
   return input.nth === void 0 ? locator : locator.nth(input.nth);
@@ -1023,6 +1117,7 @@ function buildLocator(harness, input) {
 
 // src/tools.ts
 import { z as z5 } from "zod";
+import { CONDITION_KINDS } from "@termwright/protocol";
 
 // src/screenshot-schema.ts
 import { z as z3 } from "zod";
@@ -1064,19 +1159,24 @@ var cellPosition = z4.object({
 });
 var targetShape = {
   ref: z4.string().optional().describe(
-    'ref from a previous snapshot: "n8@42" (semantic node) or "grid:1,2,9,1@7" (grid match); stable semantic identities may survive later revisions; frame-local and grid refs may not'
+    'ref from a previous snapshot: "semantic:n8@42" (semantic node) or "screen:1,2,9,1@7" (grid match); stable semantic identities may survive later revisions; frame-local and grid refs may not'
+  ),
+  selector: z4.string().optional().describe(
+    'Termwright semantic selector: "dialog button#approve:focused" (role, #testId, .class, :state)'
   ),
-  selector: z4.string().optional().describe('CSS dialect: "dialog button#approve:focused" (role, #testId, .class, :state)'),
   role: z4.enum(SEMANTIC_ROLES).optional().describe("semantic role; requires a semantic tree"),
   name: z4.string().optional().describe('accessible name; "/pattern/flags" is read as a regular expression'),
   testId: z4.string().optional().describe("author-supplied test id"),
   label: z4.string().optional().describe("label text (labelledBy, else name)"),
-  text: z4.string().optional().describe("visible text; matches the grid when there is no semantic tree"),
+  text: z4.string().optional().describe("semantic node text; requires a semantic tree"),
+  screenText: z4.string().optional().describe("text rendered in the physical terminal grid"),
   exact: z4.boolean().optional().describe("exact rather than substring text matching"),
   state: stateFilter.optional(),
   nth: z4.number().int().min(0).optional().describe("zero-based pick among matches; omit for strict mode (>1 match fails)")
 };
-var targetShapeWithoutText = (({ text: _text, ...rest }) => rest)(targetShape);
+var targetShapeWithoutText = (({ text: _text, screenText: _screenText, ...rest }) => rest)(
+  targetShape
+);
 var targetObject = z4.object(targetShape);
 var refEntrySchema = z4.object({
   ref: z4.string(),
@@ -1094,6 +1194,20 @@ var refEntrySchema = z4.object({
   value: z4.string().optional()
 });
 var semanticTreeState = z4.enum(["available", "unavailable"]);
+var evidenceProvenanceSchema = z4.object({
+  source: z4.enum(["framework", "application", "terminal", "recognizer", "driver"]),
+  method: z4.enum([
+    "native",
+    "instrumented",
+    "declared",
+    "correlated",
+    "measured",
+    "derived",
+    "heuristic"
+  ]),
+  strength: z4.enum(["authoritative", "diagnostic"]),
+  providerId: z4.string().min(1)
+});
 var cursorSchema = z4.object({
   row: z4.number().int(),
   column: z4.number().int(),
@@ -1130,6 +1244,7 @@ var roleEnum = z4.enum(SEMANTIC_ROLES);
 var STATE_NAMES = FILTERABLE_STATES;
 
 // src/tools.ts
+var mouseModifiersSchema = z5.array(z5.enum(["shift", "alt", "control"])).max(3).optional();
 var semanticFields = {
   terminal: z5.string(),
   revision: z5.number().int().describe("screen revision; pass it to terminal.capture_since as cursor"),
@@ -1143,15 +1258,14 @@ function optionalTimeout(timeout) {
   return timeout === void 0 ? {} : { timeout };
 }
 async function settleSemantics(entry) {
-  if (!entry.harness.capabilities().semanticTree) return;
-  const budget = entry.harness.semanticTree() === null ? FIRST_TREE_SETTLE_MS : PAIRING_SETTLE_MS;
-  try {
-    await entry.harness.waitForStable({ timeout: budget });
-  } catch {
-  }
+  const deadline = performance.now() + FIRST_TREE_SETTLE_MS;
+  const contract = await entry.harness.settled({ timeout: FIRST_TREE_SETTLE_MS });
+  if (contract.capabilities["semantic-tree"].status !== "supported") return;
+  await entry.harness.waitForCommittedObservation({
+    timeout: Math.max(0, deadline - performance.now())
+  });
 }
 var FIRST_TREE_SETTLE_MS = 2e3;
-var PAIRING_SETTLE_MS = 250;
 function capture(context, entry) {
   const record = context.terminals.record(entry);
   return {
@@ -1176,6 +1290,16 @@ function compactFor(entry, rows, options = {}) {
 function locatorFor(entry, args) {
   return buildLocator(entry.harness, args);
 }
+function semanticLocatorFor(entry, args) {
+  const locator = locatorFor(entry, args);
+  if (locator.domain !== "semantic") {
+    throw usageError(
+      "this action requires a semantic target; a screen locator was provided",
+      "use role, selector, testId, label or semantic text"
+    );
+  }
+  return locator;
+}
 function crashOf(entry) {
   const report = entry.harness.crashReport();
   return report === null ? void 0 : describeCrash(report);
@@ -1185,6 +1309,54 @@ var receiptFields = {
   terminal: z5.string(),
   revision: z5.number().int()
 };
+var plannedActionSchema = z5.object({
+  actionId: z5.string(),
+  kind: z5.string(),
+  strategy: z5.string(),
+  contractId: z5.string(),
+  beforeSequence: z5.number().int(),
+  afterSequence: z5.number().int(),
+  operations: z5.array(
+    z5.object({
+      device: z5.enum(["keyboard", "mouse"]),
+      kind: z5.string(),
+      modifiers: z5.array(z5.enum(["shift", "alt", "control"])).optional()
+    })
+  ),
+  requirements: z5.array(
+    z5.object({
+      kind: z5.enum(CONDITION_KINDS),
+      target: z5.string().optional(),
+      verdict: z5.enum(["satisfied", "unsatisfied", "inconclusive"]),
+      observation: z5.enum(["known", "absent", "unknown", "unsupported"]),
+      evidence: evidenceProvenanceSchema.optional()
+    })
+  ),
+  physicalEvidence: evidenceProvenanceSchema.optional()
+});
+function plannedAction(value) {
+  return {
+    actionId: value.plan.actionId,
+    kind: value.intent.kind,
+    strategy: value.plan.strategy,
+    contractId: value.plan.contractId,
+    beforeSequence: value.before.sequence,
+    afterSequence: value.after.sequence,
+    operations: value.executed.map((operation) => ({
+      device: operation.device,
+      kind: operation.kind,
+      ...operation.device === "mouse" && operation.modifiers !== void 0 ? { modifiers: [...operation.modifiers] } : {}
+    })),
+    requirements: value.plan.requirements.map((requirement) => ({
+      kind: requirement.condition.kind,
+      ..."target" in requirement.condition ? { target: requirement.condition.target } : {},
+      verdict: requirement.verdict,
+      observation: requirement.observation.status,
+      ..."evidence" in requirement.observation ? { evidence: requirement.observation.evidence } : {}
+    })),
+    ...value.plan.physicalRegion === void 0 ? {} : { physicalEvidence: value.plan.physicalRegion.evidence }
+  };
+}
 function receipt(entry) {
   return { ok: true, terminal: entry.id, revision: entry.harness.screen().revision };
 }
@@ -1233,7 +1405,7 @@ var launch = defineTool({
   handler: async (context, args) => {
     const entry = await context.terminals.launch(args);
     await settleSemantics(entry);
-    const capabilities2 = entry.harness.capabilities();
+    const contract = await entry.harness.settled();
     const screen = entry.harness.screen();
     const state = capture(context, entry);
     const compact = compactFor(entry, state.rows);
@@ -1244,12 +1416,17 @@ var launch = defineTool({
         sessionId: entry.harness.sessionId,
         revision: state.revision,
         semanticRevision: state.semanticRevision,
-        semanticTree: treeState(capabilities2.semanticTree),
+        semanticTree: treeState(contract.capabilities["semantic-tree"].status === "supported"),
         columns: screen.columns,
         rows: screen.rows,
-        ...capabilities2.adapter === void 0 ? {} : { adapter: capabilities2.adapter },
-        capabilities: [...capabilities2.capabilities],
-        platform: capabilities2.platform,
+        ...contract.framework === null ? {} : {
+          adapter: {
+            name: contract.framework.name,
+            version: contract.framework.adapterVersion
+          }
+        },
+        capabilities: Object.entries(contract.capabilities).filter(([, value]) => value.status === "supported").map(([key]) => key),
+        platform: contract.terminal.platform,
         compact
       }
     };
@@ -1273,27 +1450,34 @@ var capabilities = defineTool({
   handler: async (context, args) => {
     const entry = context.terminals.get(args.terminal);
     await settleSemantics(entry);
-    const caps = entry.harness.capabilities();
+    const contract = await entry.harness.settled();
+    const semanticTree = contract.capabilities["semantic-tree"].status === "supported";
+    const supported = Object.entries(contract.capabilities).filter(([, value]) => value.status === "supported").map(([key]) => key);
     const crash = crashOf(entry);
     const screen = entry.harness.screen();
     const semantic = entry.harness.semanticTree();
     return {
       text: `Terminal ${entry.id} ${screen.columns}x${screen.rows} revision ${screen.revision}
-semanticTree: ${caps.semanticTree ? "available" : "unavailable"}
-adapter: ${caps.adapter === void 0 ? "none" : `${caps.adapter.name} ${caps.adapter.version}`}
-capabilities: ${caps.capabilities.join(", ") || "none"}
-platform: ${caps.platform}` + (crash === void 0 ? "" : `
+semanticTree: ${semanticTree ? "available" : "unavailable"}
+adapter: ${contract.framework === null ? "none" : `${contract.framework.name} ${contract.framework.adapterVersion}`}
+capabilities: ${supported.join(", ") || "none"}
+platform: ${contract.terminal.platform}` + (crash === void 0 ? "" : `
 ${renderCrash(crash)}`),
       data: {
         terminal: entry.id,
         revision: screen.revision,
         semanticRevision: semantic?.revision ?? null,
-        semanticTree: treeState(caps.semanticTree),
+        semanticTree: treeState(semanticTree),
         columns: screen.columns,
         rows: screen.rows,
-        ...caps.adapter === void 0 ? {} : { adapter: caps.adapter },
-        capabilities: [...caps.capabilities],
-        platform: caps.platform,
+        ...contract.framework === null ? {} : {
+          adapter: {
+            name: contract.framework.name,
+            version: contract.framework.adapterVersion
+          }
+        },
+        capabilities: supported,
+        platform: contract.terminal.platform,
         ...crash === void 0 ? {} : { crash }
       }
     };
@@ -1408,13 +1592,15 @@ ${trailer.join("\n")}`,
 var captureSince = defineTool({
   name: "terminal.capture_since",
   title: "What changed since a revision",
-  description: "Incremental view: the screen rows that differ and the semantic subtrees that were added, removed or updated since the given cursor. The cursor must be a revision this server handed out earlier (snapshot or capture_since); older cursors fail with history-truncated.",
+  description: "Incremental view: the screen rows that differ and the semantic subtrees that were added, removed or updated in the latest committed semantic tree since the given cursor. A screen change alone does not imply a future semantic commit; wait for an explicit semantic state when the caller requires one. The cursor must be a revision this server handed out earlier (snapshot or capture_since); older cursors fail with history-truncated.",
   inputSchema: {
     terminal: terminalId,
     cursor: z5.number().int().min(0).describe("revision returned by an earlier snapshot"),
     maxRows: z5.number().int().min(1).max(1e4).optional(),
     maxSubtrees: z5.number().int().min(1).max(1e3).optional(),
-    maxLogs: z5.number().int().min(0).max(500).optional().describe(`application log entries to return; default ${LOG_LIMITS.maxPerResponse}, 0 to skip`)
+    maxLogs: z5.number().int().min(0).max(500).optional().describe(
+      `application log entries to return; default ${LOG_LIMITS.maxPerResponse}, 0 to skip`
+    )
   },
   outputSchema: {
     ...semanticFields,
@@ -1530,32 +1716,34 @@ var query = defineTool({
 });
 function pointerTool(name) {
   const double = name === "terminal.double_click";
+  const hover = name === "terminal.hover";
   return defineTool({
     name,
-    title: double ? "Double-click a target" : "Click a target",
-    description: `Sends a real ${double ? "double " : ""}mouse report through the pseudo-terminal. Fails with unsupported-action when the program never enabled mouse tracking. Where the platform hides the mode (modes.mouseTracking "unknown", e.g. Windows ConPTY) the click is sent anyway, encoded as SGR.`,
+    title: hover ? "Hover a target" : double ? "Double-click a target" : "Click a target",
+    description: `Sends a real ${hover ? "motion" : double ? "double-click" : "click"} mouse report through the pseudo-terminal. Fails closed with input-mode-disabled when the required tracking mode or encoding is disabled or unobservable.`,
     inputSchema: {
       terminal: terminalId,
       ...targetShape,
       button: buttonSchema.optional(),
+      modifiers: mouseModifiersSchema,
       position: z5.object({ rowOffset: z5.number().int(), columnOffset: z5.number().int() }).optional().describe("offset inside the target rectangle"),
       timeout: timeoutMs.optional()
     },
-    outputSchema: { ...receiptFields, ref: z5.string() },
+    outputSchema: { ...receiptFields, ref: z5.string(), action: plannedActionSchema },
     handler: async (context, args) => {
       const entry = context.terminals.get(args.terminal);
-      const locator = locatorFor(entry, args);
+      const locator = semanticLocatorFor(entry, args);
       const target = await locator.resolve(optionalTimeout(args.timeout));
       const options = {
         ...optionalTimeout(args.timeout),
         ...args.button === void 0 ? {} : { button: args.button },
+        ...args.modifiers === void 0 ? {} : { modifiers: args.modifiers },
         ...args.position === void 0 ? {} : { position: args.position }
       };
-      if (double) await locator.doubleClick(options);
-      else await locator.click(options);
+      const action = hover ? await locator.hover(options) : double ? await locator.doubleClick(options) : await locator.click(options);
       return {
-        text: `${double ? "double-clicked" : "clicked"} ref=${target.ref}`,
-        data: { ...receipt(entry), ref: target.ref }
+        text: `${hover ? "hovered" : double ? "double-clicked" : "clicked"} ref=${target.ref}`,
+        data: { ...receipt(entry), ref: target.ref, action: plannedAction(action) }
       };
     }
   });
@@ -1563,7 +1751,7 @@ function pointerTool(name) {
 var press = defineTool({
   name: "terminal.press",
   title: "Press keys",
-  description: 'Sends key chords as real bytes, honouring the modes the program enabled (application cursor keys, keypad). Examples: "Enter", "Escape", "Control+K Control+U". With a target, the node is focused first.',
+  description: 'Sends key chords as real bytes, honouring the modes the program enabled (application cursor keys, keypad). Examples: "Enter", "Escape", "Control+K Control+U". With a target, the node must already be focused.',
   inputSchema: {
     terminal: terminalId,
     keys: z5.string().min(1).describe('space-separated chords, e.g. "Control+A Home"'),
@@ -1574,10 +1762,13 @@ var press = defineTool({
   handler: async (context, args) => {
     const entry = context.terminals.get(args.terminal);
     if (hasTarget(args)) {
-      const locator = locatorFor(entry, args);
+      const locator = semanticLocatorFor(entry, args);
       const target = await locator.resolve(optionalTimeout(args.timeout));
       await locator.press(args.keys, optionalTimeout(args.timeout));
-      return { text: `pressed ${args.keys} on ref=${target.ref}`, data: { ...receipt(entry), ref: target.ref } };
+      return {
+        text: `pressed ${args.keys} on ref=${target.ref}`,
+        data: { ...receipt(entry), ref: target.ref }
+      };
     }
     await entry.harness.press(args.keys);
     return { text: `pressed ${args.keys}`, data: receipt(entry) };
@@ -1586,7 +1777,7 @@ var press = defineTool({
 var type = defineTool({
   name: "terminal.type",
   title: "Type text",
-  description: "Types text as individual keystrokes (not a paste). With a target, the node is focused first.",
+  description: "Types text as individual keystrokes (not a paste). With a target, the node must already be focused; use terminal.fill for focus + replacement.",
   inputSchema: {
     terminal: terminalId,
     text: z5.string(),
@@ -1597,7 +1788,7 @@ var type = defineTool({
   handler: async (context, args) => {
     const entry = context.terminals.get(args.terminal);
     if (hasTarget(args)) {
-      const locator = locatorFor(entry, args);
+      const locator = semanticLocatorFor(entry, args);
       const target = await locator.resolve(optionalTimeout(args.timeout));
       await locator.type(args.text, optionalTimeout(args.timeout));
       return { text: `typed into ref=${target.ref}`, data: { ...receipt(entry), ref: target.ref } };
@@ -1606,6 +1797,149 @@ var type = defineTool({
     return { text: `typed ${args.text.length} characters`, data: receipt(entry) };
   }
 });
+var fill = defineTool({
+  name: "terminal.fill",
+  title: "Fill a semantic control",
+  description: "Ensures the semantic control receives focus through the real input path, selects its current value, and types the replacement.",
+  inputSchema: {
+    terminal: terminalId,
+    text: z5.string(),
+    ...targetShapeWithoutText,
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: { ...receiptFields, ref: z5.string(), action: plannedActionSchema },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const locator = semanticLocatorFor(entry, args);
+    const target = await locator.resolve(optionalTimeout(args.timeout));
+    const action = await locator.fill(args.text, optionalTimeout(args.timeout));
+    return {
+      text: `filled ref=${target.ref}`,
+      data: { ...receipt(entry), ref: target.ref, action: plannedAction(action) }
+    };
+  }
+});
+function checkedTool(kind) {
+  return defineTool({
+    name: `terminal.${kind}`,
+    title: kind === "check" ? "Check a semantic control" : "Uncheck a semantic control",
+    description: `Uses the central action planner and real terminal input to ${kind} a checkbox or radio, then verifies semantic state.`,
+    inputSchema: { terminal: terminalId, ...targetShapeWithoutText, timeout: timeoutMs.optional() },
+    outputSchema: { ...receiptFields, ref: z5.string(), action: plannedActionSchema },
+    handler: async (context, args) => {
+      const entry = context.terminals.get(args.terminal);
+      const locator = semanticLocatorFor(entry, args);
+      const target = await locator.resolve(optionalTimeout(args.timeout));
+      const action = kind === "check" ? await locator.check(optionalTimeout(args.timeout)) : await locator.uncheck(optionalTimeout(args.timeout));
+      return {
+        text: `${kind === "check" ? "checked" : "unchecked"} ref=${target.ref}`,
+        data: { ...receipt(entry), ref: target.ref, action: plannedAction(action) }
+      };
+    }
+  });
+}
+var actionability = defineTool({
+  name: "terminal.actionability",
+  title: "Explain a semantic action",
+  description: "Runs the same ActionPlanner used by execution, but sends no input. Reports every authoritative requirement and the chosen strategy or typed rejection.",
+  inputSchema: {
+    terminal: terminalId,
+    ...targetShapeWithoutText,
+    action: z5.enum([
+      "click",
+      "double-click",
+      "hover",
+      "focus",
+      "activate",
+      "press",
+      "type",
+      "fill",
+      "check",
+      "uncheck"
+    ]),
+    value: z5.string().optional(),
+    timeout: timeoutMs.optional()
+  },
+  outputSchema: {
+    terminal: z5.string(),
+    ref: z5.string(),
+    actionable: z5.boolean(),
+    strategy: z5.string().optional(),
+    reason: z5.object({ code: z5.string(), message: z5.string(), targetRef: z5.string().optional() }).optional(),
+    requirements: z5.array(
+      z5.object({
+        kind: z5.enum(CONDITION_KINDS),
+        target: z5.string().optional(),
+        verdict: z5.enum(["satisfied", "unsatisfied", "inconclusive"]),
+        observation: z5.enum(["known", "absent", "unknown", "unsupported"]),
+        evidence: evidenceProvenanceSchema.optional()
+      })
+    ),
+    contractId: z5.string(),
+    sequence: z5.number().int()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const locator = locatorFor(entry, args);
+    const target = await locator.resolve(optionalTimeout(args.timeout));
+    const pointerAction = args.action === "click" || args.action === "double-click" || args.action === "hover";
+    if (locator.domain === "screen" && !pointerAction) {
+      throw usageError(
+        `${args.action} requires a semantic locator; screen locators only support physical pointer actions`
+      );
+    }
+    const explanation = locator.domain === "screen" ? await locator.actionability(
+      args.action,
+      optionalTimeout(args.timeout)
+    ) : await locator.actionability(args.action, {
+      ...optionalTimeout(args.timeout),
+      ...args.value === void 0 ? {} : { value: args.value }
+    });
+    const requirements = explanation.requirements.map((requirement) => ({
+      kind: requirement.condition.kind,
+      ..."target" in requirement.condition ? { target: requirement.condition.target } : {},
+      verdict: requirement.verdict,
+      observation: requirement.observation.status,
+      ..."evidence" in requirement.observation ? { evidence: requirement.observation.evidence } : {}
+    }));
+    return {
+      text: explanation.actionable ? `${args.action} is actionable via ${explanation.strategy ?? "planned input"}` : `${args.action} is not actionable: ${explanation.reason?.message ?? "inconclusive requirements"}`,
+      data: {
+        terminal: entry.id,
+        ref: target.ref,
+        actionable: explanation.actionable,
+        ...explanation.strategy === void 0 ? {} : { strategy: explanation.strategy },
+        ...explanation.reason === void 0 ? {} : { reason: explanation.reason },
+        requirements,
+        contractId: explanation.checkpoint.contractId,
+        sequence: explanation.checkpoint.sequence
+      }
+    };
+  }
+});
+var checkpoint = defineTool({
+  name: "terminal.checkpoint",
+  title: "Capture an observation checkpoint",
+  description: "Returns the atomic session/contract/screen/semantic identity used by revision-safe actions and waits.",
+  inputSchema: { terminal: terminalId },
+  outputSchema: {
+    terminal: z5.string(),
+    sessionId: z5.string(),
+    contractId: z5.string(),
+    epoch: z5.number().int(),
+    sequence: z5.number().int(),
+    screenRevision: z5.number().int(),
+    semanticRevision: z5.number().int().nullable(),
+    pairedScreenRevision: z5.number().int().nullable()
+  },
+  annotations: { readOnlyHint: true },
+  handler: async (context, args) => {
+    const entry = context.terminals.get(args.terminal);
+    const value = entry.harness.checkpoint();
+    return { text: `checkpoint ${value.sequence}`, data: { terminal: entry.id, ...value } };
+  }
+});
 var paste = defineTool({
   name: "terminal.paste",
   title: "Paste text",
@@ -1646,20 +1980,38 @@ var drag = defineTool({
     toTarget: targetObject.optional().describe("drop target; omit when using from/to"),
     from: cellPosition.optional(),
     to: cellPosition.optional(),
-    timeout: timeoutMs.optional()
+    timeout: timeoutMs.optional(),
+    modifiers: mouseModifiersSchema
   },
   outputSchema: receiptFields,
   handler: async (context, args) => {
     const entry = context.terminals.get(args.terminal);
     const source = locatorFor(entry, args);
     if (args.toTarget !== void 0) {
-      await source.dragTo(locatorFor(entry, args.toTarget), optionalTimeout(args.timeout));
+      const destination = locatorFor(entry, args.toTarget);
+      if (source.domain !== destination.domain) {
+        throw usageError("drag source and destination belong to different locator domains");
+      }
+      if (source.domain === "semantic" && destination.domain === "semantic")
+        await source.dragTo(destination, {
+          ...optionalTimeout(args.timeout),
+          ...args.modifiers === void 0 ? {} : { modifiers: args.modifiers }
+        });
+      else if (source.domain === "screen" && destination.domain === "screen")
+        await source.dragTo(destination, {
+          ...optionalTimeout(args.timeout),
+          ...args.modifiers === void 0 ? {} : { modifiers: args.modifiers }
+        });
       return { text: "dragged to target", data: receipt(entry) };
     }
     if (args.from === void 0 || args.to === void 0) {
       throw usageError("drag needs either toTarget, or both from and to");
     }
-    await source.drag({ from: args.from, to: args.to });
+    await entry.harness.mouse.drag({
+      from: args.from,
+      to: args.to,
+      ...args.modifiers === void 0 ? {} : { modifiers: args.modifiers }
+    });
     return {
       text: `dragged (${args.from.row},${args.from.column}) -> (${args.to.row},${args.to.column})`,
       data: receipt(entry)
@@ -1674,14 +2026,16 @@ var wheel = defineTool({
     terminal: terminalId,
     ...targetShape,
     deltaY: z5.number().int(),
-    deltaX: z5.number().int().optional()
+    deltaX: z5.number().int().optional(),
+    modifiers: mouseModifiersSchema
   },
   outputSchema: receiptFields,
   handler: async (context, args) => {
     const entry = context.terminals.get(args.terminal);
     await locatorFor(entry, args).wheel({
       deltaY: args.deltaY,
-      ...args.deltaX === void 0 ? {} : { deltaX: args.deltaX }
+      ...args.deltaX === void 0 ? {} : { deltaX: args.deltaX },
+      ...args.modifiers === void 0 ? {} : { modifiers: args.modifiers }
     });
     return { text: `wheel deltaY=${args.deltaY}`, data: receipt(entry) };
   }
@@ -1801,14 +2155,34 @@ var copySelection = defineTool({
 var waitFor = defineTool({
   name: "terminal.wait_for",
   title: "Wait for a condition",
-  description: 'Revision-driven waits \u2014 never a sleep. "text"/"title" wait for content, "visible"/"hidden"/"attached" wait on a target, "stable" waits for renders to settle, "idle" for output to stop, "render" for a render after a given revision, "exit" for the child to exit.',
+  description: `Revision-driven waits \u2014 never a sleep. "text"/"title" wait for content, locator states use the driver's canonical Conditions, "quiet" explicitly waits for heuristic silence, "render" for a render after a given revision, "exit" for the child to exit.`,
   inputSchema: {
     terminal: terminalId,
-    wait: z5.enum(["text", "title", "visible", "hidden", "attached", "stable", "idle", "render", "exit"]),
+    wait: z5.enum([
+      "text",
+      "title",
+      "visible",
+      "hidden",
+      "attached",
+      "detached",
+      "displayed",
+      "offscreen",
+      "focused",
+      "enabled",
+      "disabled",
+      "checked",
+      "selected",
+      "expanded",
+      "collapsed",
+      "quiet",
+      "shell-prompt",
+      "render",
+      "exit"
+    ]),
     text: z5.string().optional().describe('for wait="text"; "/pattern/flags" is a regular expression'),
     title: z5.string().optional().describe('for wait="title"'),
     ...targetShapeWithoutText,
-    frames: z5.number().int().min(1).optional().describe('for wait="stable"'),
+    quietMs: z5.number().int().min(0).optional().describe('for wait="quiet"'),
     after: z5.number().int().min(0).optional().describe('for wait="render": the revision to beat'),
     timeout: timeoutMs.optional()
   },
@@ -1833,19 +2207,32 @@ var waitFor = defineTool({
       }
       case "visible":
       case "hidden":
-      case "attached": {
+      case "attached":
+      case "detached":
+      case "displayed":
+      case "offscreen": {
         await locatorFor(entry, args).waitFor({ state: args.wait, ...timeout });
         break;
       }
-      case "stable": {
-        await entry.harness.waitForStable({
-          ...args.frames === void 0 ? {} : { frames: args.frames },
+      case "focused":
+      case "enabled":
+      case "disabled":
+      case "checked":
+      case "selected":
+      case "expanded":
+      case "collapsed": {
+        await semanticLocatorFor(entry, args).waitFor({ state: args.wait, ...timeout });
+        break;
+      }
+      case "quiet": {
+        await entry.harness.waitForQuiet({
+          ...args.quietMs === void 0 ? {} : { quietMs: args.quietMs },
           ...timeout
         });
         break;
       }
-      case "idle": {
-        await entry.harness.waitForIdle(timeout);
+      case "shell-prompt": {
+        await entry.harness.waitForShellPrompt(timeout);
         break;
       }
       case "render": {
@@ -1885,10 +2272,16 @@ var TERMINAL_TOOLS = Object.freeze([
   snapshot,
   captureSince,
   query,
+  checkpoint,
+  actionability,
   pointerTool("terminal.click"),
   pointerTool("terminal.double_click"),
+  pointerTool("terminal.hover"),
   press,
   type,
+  fill,
+  checkedTool("check"),
+  checkedTool("uncheck"),
   paste,
   writeRaw,
   drag,
@@ -2147,7 +2540,9 @@ var overview = defineTool({
       );
     }
     if (markers.length > 0) {
-      lines.push(`markers: ${markers.map((marker) => `${marker.timeMs}ms ${marker.label}`).join(", ")}`);
+      lines.push(
+        `markers: ${markers.map((marker) => `${marker.timeMs}ms ${marker.label}`).join(", ")}`
+      );
     }
     const crash = crashOfMeta(meta);
     if (crash !== void 0) lines.push(renderCrash(crash));
@@ -2217,7 +2612,10 @@ ${renderLogs({ entries: reconstructed.logs, omitted: 0, cursor: 0 })}`;
         semanticRevision: reconstructed.semanticRevision,
         semanticTree: reconstructed.semantic === null ? "unavailable" : "available",
         step: step === null ? null : projectStep(step, 0),
-        refs: reconstructed.semantic === null ? [] : refEntries(reconstructed.semantic).map((entry) => ({ ...entry, flags: [...entry.flags] })),
+        refs: reconstructed.semantic === null ? [] : refEntries(reconstructed.semantic).map((entry) => ({
+          ...entry,
+          flags: [...entry.flags]
+        })),
         logs: reconstructed.logs.map((entry) => ({ ...entry })),
         compact,
         ...image === void 0 ? {} : { screenshot: describeImage(image) }
@@ -2235,7 +2633,9 @@ var diff = defineTool({
     toMs: z6.number().min(0),
     maxRows: z6.number().int().min(1).max(1e4).optional(),
     maxSubtrees: z6.number().int().min(1).max(1e3).optional(),
-    maxLogs: z6.number().int().min(0).max(500).optional().describe(`application log entries between the two moments; default ${LOG_LIMITS.maxPerResponse}, 0 to skip`)
+    maxLogs: z6.number().int().min(0).max(500).optional().describe(
+      `application log entries between the two moments; default ${LOG_LIMITS.maxPerResponse}, 0 to skip`
+    )
   },
   outputSchema: {
     traceId: z6.string(),
@@ -2259,7 +2659,10 @@ var diff = defineTool({
   annotations: { readOnlyHint: true },
   handler: async (context, args) => {
     if (args.toMs < args.fromMs) {
-      throw usageError("toMs must not precede fromMs", "swap the two, or read trace.overview for the timeline");
+      throw usageError(
+        "toMs must not precede fromMs",
+        "swap the two, or read trace.overview for the timeline"
+      );
     }
     const trace = context.traces.get(args.traceId);
     const before = await frameAt(trace, args.fromMs, 0);
@@ -2316,7 +2719,7 @@ function toolByName(name) {
 
 // src/version.ts
 var SERVER_NAME = "termwright";
-var SERVER_VERSION = "0.1.0";
+var SERVER_VERSION = "0.3.0";
 var AGENT_CONTEXT_VERSION = 1;
 
 // src/agent-context.ts
@@ -2325,23 +2728,39 @@ var DRIVER_ERROR_KINDS = [
   "timeout",
   "stale-snapshot",
   "ambiguous-locator",
-  "unsupported-action",
+  "semantic-capability-unavailable",
+  "probe-attach-failed",
+  "capability-unavailable",
+  "not-actionable",
+  "input-mode-disabled",
+  "capability-provider-lost",
+  "capability-provider-violation",
+  "evidence-conflict",
+  "adapter-guarantee-violation",
+  "duplicate-semantic-key",
   "history-truncated",
   "protocol-violation",
   "capacity",
   "process-exited",
+  "pty-backend-failed",
   "session-closed",
   "not-found"
 ];
 var ERROR_KINDS = [...DRIVER_ERROR_KINDS, ...MCP_ERROR_KINDS];
+var TARGETING_GUIDANCE = {
+  precedence: "Targeting precedence is `ref`, `selector`, `testId`, `role` (+`name`), `label`, `text`, `screenText`.",
+  semanticUnavailable: "`semanticTree: unavailable` means the program ships no integration \u2014 target physical output with `screenText`, never semantic `text` or `role`."
+};
 var CONVENTIONS = [
-  "A ref looks like n8@42: node id minted at semantic revision 42. A stable semantic identity may be re-resolved in later revisions; frame-local identities and grid refs must be refreshed.",
+  "A semantic ref looks like semantic:n8@42: node id minted at semantic revision 42. A stable semantic identity may be re-resolved in later revisions; frame-local identities and grid refs must be refreshed.",
   "terminal.snapshot returns a screen revision; pass it to terminal.capture_since as cursor to get only the rows and semantic subtrees that changed.",
+  "A wait for PTY text proves visual output, not that a future semantic frame has committed. When semantic state matters, wait for its explicit locator condition before capture_since.",
+  "A semantic postcondition proves a new commit only when the baseline did not already satisfy it; choose a condition that represents the action's actual state change.",
   'Any name or text argument may be written as "/pattern/flags" to match as a regular expression.',
-  "Targeting precedence is ref, selector, testId, role (+name), label, text.",
+  TARGETING_GUIDANCE.precedence,
   'Locators are strict: more than one match fails with kind "ambiguous-locator" unless nth is given.',
-  'semanticTree "unavailable" means the program ships no adapter \u2014 target by text, never by role.',
-  "Errors are returned as tool results with isError set; structuredContent.error.kind is the value to branch on, and structuredContent.error.suggestion says what to try next."
+  TARGETING_GUIDANCE.semanticUnavailable,
+  `Errors are returned as tool results with isError set; _meta["io.termwright/error"].kind is the value to branch on, and that payload's suggestion says what to try next. Error results intentionally omit structuredContent because it is success-schema validated.`
 ];
 function toJsonSchema(shape) {
   return z7.toJSONSchema(z7.object(shape), { io: "input" });
@@ -2375,7 +2794,8 @@ function buildUsage() {
     "",
     "serve",
     "  termwright-mcp                     serve over stdio (what an MCP host spawns)",
-    "  termwright-mcp --http --port 7333  serve Streamable HTTP on /mcp, multi-session",
+    "  termwright-mcp --http --port 7333 --show-auth-token  authenticated Streamable HTTP on loopback",
+    "  remote bind additionally requires: --host HOST --allow-non-loopback",
     "  termwright-mcp agent-context       versioned JSON: tools, params, enums, exit codes",
     "  termwright-mcp usage               this page",
     "  termwright-mcp skill --out DIR     emit an agent-skill package (SKILL.md + reference)",
@@ -2383,13 +2803,14 @@ function buildUsage() {
     "",
     "typical loop",
     '  terminal.launch {command:["node","app.js"]}   -> terminal "t1" + first snapshot',
-    '  terminal.snapshot {terminal:"t1"}             -> refs n8@42 + visible text + revision',
-    '  terminal.click {terminal:"t1", ref:"n8@42"}   -> real mouse report through the PTY',
-    '  terminal.wait_for {terminal:"t1", wait:"text", text:"Approved"}',
+    '  terminal.snapshot {terminal:"t1"}             -> refs semantic:n8@42 + visible text + revision',
+    '  terminal.click {terminal:"t1", ref:"semantic:n9@42"} -> real mouse report through the PTY',
+    '  terminal.wait_for {terminal:"t1", wait:"text", text:"Rejected"}',
+    '  terminal.wait_for {terminal:"t1", wait:"focused", testId:"reject"} -> changed semantic state',
     '  terminal.capture_since {terminal:"t1", cursor:42} -> only what changed',
     '  terminal.close {terminal:"t1"}',
     "",
-    "targeting  ref | selector | testId | role(+name) | label | text   (+ exact, state, nth)",
+    "targeting  ref | selector | testId | role(+name) | label | text | screenText   (+ exact, state, nth)",
     `roles      ${SEMANTIC_ROLES.join(" ")}`,
     `states     ${STATE_NAMES.join(" ")}`,
     "",
@@ -2405,13 +2826,45 @@ var SKILL_DESCRIPTION = "Drive terminal programs (TUIs, CLIs, REPLs) over MCP: l
 function renderParameters(schema) {
   const properties = schema["properties"];
   if (typeof properties !== "object" || properties === null) return "  (no parameters)";
-  const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+  const required = new Set(
+    Array.isArray(schema["required"]) ? schema["required"] : []
+  );
   return Object.entries(properties).map(([name, definition]) => {
     const type2 = typeof definition["type"] === "string" ? definition["type"] : Array.isArray(definition["enum"]) ? definition["enum"].map((value) => JSON.stringify(value)).join("|") : "value";
     const description = typeof definition["description"] === "string" ? ` \u2014 ${definition["description"]}` : "";
     return `- \`${name}\`${required.has(name) ? "" : "?"}: ${type2}${description}`;
   }).join("\n");
 }
+function markdownTableCell(value) {
+  return value.replaceAll("|", "\\|").replace(/\s+/gu, " ").trim();
+}
+function renderMcpToolSurfaceMarkdown() {
+  const context = buildAgentContext();
+  const sections = [
+    ["Live terminal tools", context.tools.filter((tool) => tool.name.startsWith("terminal."))],
+    ["Trace tools", context.tools.filter((tool) => tool.name.startsWith("trace."))]
+  ];
+  return [
+    "<!-- Generated from packages/mcp/src/registry.ts; do not edit this block by hand. -->",
+    ...sections.flatMap(([heading, tools]) => [
+      `### ${heading}`,
+      "",
+      "| Tool | Purpose |",
+      "| --- | --- |",
+      ...tools.map((tool) => `| \`${tool.name}\` | ${markdownTableCell(tool.description)} |`),
+      ""
+    ]),
+    "### Targeting",
+    "",
+    TARGETING_GUIDANCE.precedence,
+    "",
+    TARGETING_GUIDANCE.semanticUnavailable,
+    "",
+    "Names and text accept `/pattern/flags`. Locators are strict: more than one match returns",
+    "`ambiguous-locator` unless `nth` is explicit.",
+    ""
+  ].join("\n");
+}
 function renderSkillMarkdown() {
   return [
     "---",
@@ -2430,8 +2883,11 @@ function renderSkillMarkdown() {
     '1. `terminal.launch { command: ["node", "app.js"] }` \u2014 returns the handle and the first snapshot.',
     "2. `terminal.snapshot { terminal }` \u2014 compact refs, visible text, cursor, modes, scroll position.",
     "3. Act: `terminal.click`, `terminal.press`, `terminal.type`, `terminal.paste`, `terminal.drag`, \u2026",
-    '4. `terminal.wait_for { wait: "text" | "visible" | "stable" | "idle" | "exit", \u2026 }` \u2014 never sleep.',
-    "5. `terminal.capture_since { cursor }` \u2014 only the rows and semantic subtrees that changed.",
+    '4. `terminal.wait_for { wait: "text" | "visible" | "focused" | "quiet" | "render" | "exit", \u2026 }` \u2014 never sleep.',
+    "   PTY text proves visual output only. If later work requires semantic state, wait for that",
+    "   explicit state (`focused`, `checked`, `selected`, \u2026) before capturing the diff.",
+    "   The postcondition must differ from the baseline; an already-satisfied condition proves no new commit.",
+    "5. `terminal.capture_since { cursor }` \u2014 changed rows plus changes in the latest committed tree.",
     "6. `terminal.close { terminal }`.",
     "",
     "## Reading a snapshot",
@@ -2439,8 +2895,8 @@ function renderSkillMarkdown() {
     "```",
     "Terminal t1 100x30 revision 42",
     "semanticTree: available",
-    'dialog "Permission" ref=n7@42 bounds=(8,20,40,9) modal',
-    '  button "Approve" ref=n8@42 bounds=(14,23,11,1) focused',
+    'dialog "Permission" ref=semantic:n7@42 bounds=(8,20,40,9) modal',
+    '  button "Approve" ref=semantic:n8@42 bounds=(14,23,11,1) focused',
     "visible text:",
     "\u2026",
     "```",
@@ -2450,12 +2906,12 @@ function renderSkillMarkdown() {
     "Stable semantic identities can be resolved again after the screen moves on. Frame-local",
     "identities and grid refs cannot; take a fresh snapshot when they become stale.",
     "",
-    "`semanticTree: unavailable` means the program ships no adapter. Target those by `text`; there",
-    "are no invented roles.",
+    TARGETING_GUIDANCE.semanticUnavailable,
     "",
     "## Targeting",
     "",
-    "Precedence: `ref`, `selector`, `testId`, `role` (+`name`), `label`, `text`. Any name or text may",
+    TARGETING_GUIDANCE.precedence,
+    "Any name or text may",
     "be written `/pattern/flags` to match as a regular expression. Locators are strict \u2014 more than one",
     "match fails with `ambiguous-locator` and lists the candidates; pass `nth` to disambiguate, or use",
     "`terminal.query` first to see what matches.",
@@ -2495,10 +2951,10 @@ function renderSkillMarkdown() {
     "",
     "## Reading terminal modes",
     "",
-    "A snapshot reports `modes`. Both mouse fields can read `unknown`, which means the platform hides",
-    "the mode from the emulator \u2014 Windows ConPTY does \u2014 not that the program turned mouse reporting",
-    "off. Clicks still go through there, encoded as SGR. So `unknown` is never a reason to fall back",
-    "to keyboard-only interaction; a real `none` is.",
+    "A snapshot reports `modes`. Certified PTY backends, including pinned passthrough ConPTY, expose",
+    "mouse and focus DECSET directly. `unknown` is reserved for an embedding that explicitly hides",
+    "mode changes; Termwright then fails closed unless authoritative application evidence supplies",
+    "the production parser state. A real `none` means the program turned mouse reporting off.",
     "",
     "## Screenshots",
     "",
@@ -2529,8 +2985,9 @@ function renderSkillMarkdown() {
     "`suggestion`. Branch on the kind: `stale-snapshot` (re-snapshot), `ambiguous-locator` (narrow the",
     "target), `timeout` (the condition never held \u2014 read the screen excerpt), `not-found` (the path you",
     "named holds nothing \u2014 a typo, not a broken artifact; a corrupt archive reports",
-    "`protocol-violation` instead), `unsupported-action` (the",
-    "program never enabled mouse tracking, or has no semantic tree), `no-session` (bad handle),",
+    "`protocol-violation` instead), `probe-attach-failed` (a required semantic probe never attached),",
+    "`capability-unavailable` (the frozen contract lacks the requested fact), `input-mode-disabled`",
+    "(the app did not enable the required terminal input mode), `no-session` (bad handle),",
     '`history-truncated` (cursor too old). The same payload is in `_meta["io.termwright/error"]`.',
     "",
     "See `reference.md` for every tool and parameter, and `agent-context.json` for the machine-readable",
@@ -2595,348 +3052,9 @@ async function writeAgentSkill(directory) {
   return written;
 }
 
-// src/server.ts
-import { createServer } from "http";
-import { randomUUID } from "crypto";
-
-// src/sdk-facade.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-async function connectTransport(server, transport) {
-  await server.connect(transport);
-}
-
-// src/server.ts
-var INSTRUCTIONS = "Drive terminal programs the way a person would. terminal.launch starts a program and returns a handle; terminal.snapshot gives compact refs plus visible text; act with terminal.click / press / type; wait with terminal.wait_for; poll cheaply with terminal.capture_since using the revision a snapshot returned. Refs like n8@42 are only valid at semantic revision 42 \u2014 re-snapshot after the screen changes. Programs without a termwright adapter report semanticTree: unavailable; target them by text instead of by role.";
-function successResult(outcome) {
-  return {
-    content: [
-      { type: "text", text: outcome.text },
-      ...(outcome.images ?? []).map((image) => ({
-        type: "image",
-        data: image.data,
-        mimeType: image.mimeType
-      }))
-    ],
-    structuredContent: outcome.data
-  };
-}
-function withCrashContext(context, args, error) {
-  if (error instanceof CrashContextError) return error;
-  const id = args?.terminal;
-  if (typeof id !== "string") return error;
-  const report = context.terminals.find(id)?.harness.crashReport();
-  return report === void 0 || report === null ? error : new CrashContextError(error, describeCrash(report));
-}
-var ERROR_META_KEY = "io.termwright/error";
-function errorResult(error) {
-  const payload = toErrorPayload(error);
-  return {
-    isError: true,
-    content: [{ type: "text", text: renderErrorPayload(payload) }],
-    _meta: { [ERROR_META_KEY]: payload }
-  };
-}
-function createTermwrightMcpServer(stores) {
-  const server = new McpServer(
-    { name: SERVER_NAME, version: SERVER_VERSION },
-    { capabilities: { tools: {} }, instructions: INSTRUCTIONS }
-  );
-  const context = { terminals: stores.terminals, traces: stores.traces };
-  for (const tool of TOOLS) {
-    server.registerTool(
-      tool.name,
-      {
-        title: tool.title,
-        description: tool.description,
-        inputSchema: tool.inputSchema,
-        outputSchema: tool.outputSchema,
-        annotations: tool.annotations
-      },
-      async (args) => {
-        try {
-          return successResult(await tool.handler(context, args));
-        } catch (error) {
-          return errorResult(withCrashContext(context, args, error));
-        }
-      }
-    );
-  }
-  return server;
-}
-async function connect(stores, transport) {
-  const server = createTermwrightMcpServer(stores);
-  await connectTransport(server, transport);
-  return {
-    server,
-    stores,
-    close: async () => {
-      await closeSessionStores(stores);
-      await server.close();
-    }
-  };
-}
-async function serveStdio(options = {}) {
-  const stores = createSessionStores({ sessionKey: "stdio", storageDir: options.storageDir });
-  return connect(stores, new StdioServerTransport());
-}
-async function serveInMemory(options = {}) {
-  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-  const stores = createSessionStores({
-    sessionKey: options.sessionKey ?? "in-memory",
-    storageDir: options.storageDir
-  });
-  const running = await connect(stores, serverTransport);
-  return { ...running, clientTransport };
-}
-var DEFAULT_IDLE_TTL_MS = 10 * 6e4;
-function sendJson(response, status, body) {
-  const text = JSON.stringify(body);
-  response.writeHead(status, { "content-type": "application/json" });
-  response.end(text);
-}
-async function readBody(request) {
-  const chunks = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.from(chunk);
-    size += buffer.byteLength;
-    if (size > 4 * 1024 * 1024) throw new Error("request body too large");
-    chunks.push(buffer);
-  }
-  if (chunks.length === 0) return void 0;
-  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-}
-async function serveHttp(options = {}) {
-  const path = options.path ?? "/mcp";
-  const log = options.log ?? ((message) => void process.stderr.write(`${message}
-`));
-  const registry = new SessionRegistry({
-    ...options.maxSessions === void 0 ? {} : { maxSessions: options.maxSessions },
-    ...options.storageDir === void 0 ? {} : { storageDir: options.storageDir },
-    ...options.now === void 0 ? {} : { now: options.now },
-    idleTtlMs: options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS,
-    disposeAttachment: async (attachment) => {
-      await attachment.transport.close();
-    },
-    onExpired: (key) => {
-      log(`termwright: session ${key} expired after idling; terminals and traces released`);
-    }
-  });
-  registry.startIdleSweeper();
-  const http = createServer((request, response) => {
-    void (async () => {
-      try {
-        const url = new URL(request.url ?? "/", "http://localhost");
-        if (url.pathname !== path) {
-          sendJson(response, 404, { error: "not found" });
-          return;
-        }
-        const sessionId = request.headers["mcp-session-id"];
-        const key = Array.isArray(sessionId) ? sessionId[0] : sessionId;
-        if (request.method === "DELETE") {
-          if (key !== void 0) await registry.delete(key);
-          response.writeHead(204).end();
-          return;
-        }
-        const body = request.method === "POST" ? await readBody(request) : void 0;
-        if (key !== void 0) {
-          const session2 = registry.get(key);
-          if (session2 === void 0) {
-            sendJson(response, 404, { error: "unknown session", kind: "no-session" });
-            return;
-          }
-          registry.touch(key);
-          await session2.attachment.transport.handleRequest(request, response, body);
-          return;
-        }
-        if (request.method !== "POST" || !isInitializeRequest(body)) {
-          sendJson(response, 400, { error: "missing Mcp-Session-Id", kind: "usage" });
-          return;
-        }
-        const newKey = randomUUID();
-        const session = registry.create(newKey, (stores) => {
-          const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => newKey
-          });
-          const server = createTermwrightMcpServer(stores);
-          transport.onclose = () => {
-            void registry.delete(newKey);
-          };
-          return { transport, server };
-        });
-        await connectTransport(session.attachment.server, session.attachment.transport);
-        await session.attachment.transport.handleRequest(request, response, body);
-      } catch (error) {
-        const payload = toErrorPayload(error);
-        if (!response.headersSent) sendJson(response, 500, { error: payload.message, kind: payload.kind });
-        else response.end();
-      }
-    })();
-  });
-  await new Promise((resolve) => {
-    http.listen(options.port ?? 0, options.host ?? "127.0.0.1", resolve);
-  });
-  const address = http.address();
-  const port = typeof address === "object" && address !== null ? address.port : options.port ?? 0;
-  return {
-    http,
-    registry,
-    port,
-    close: async () => {
-      registry.stopIdleSweeper();
-      await registry.closeAll();
-      await new Promise((resolve) => {
-        http.close(() => {
-          resolve();
-        });
-      });
-    }
-  };
-}
-
-// src/cli.ts
-var defaultIo = {
-  out: (text) => process.stdout.write(`${text}
-`),
-  err: (text) => process.stderr.write(`${text}
-`)
-};
-function parseArgs(argv) {
-  let command = "serve";
-  let json = false;
-  let http = false;
-  let port;
-  let host;
-  let out;
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index] ?? "";
-    switch (arg) {
-      case "--json":
-        json = true;
-        break;
-      case "--http":
-        http = true;
-        break;
-      case "--port": {
-        const value = Number(argv[index + 1]);
-        if (!Number.isInteger(value) || value < 0 || value > 65535) {
-          throw usageError("--port needs an integer between 0 and 65535");
-        }
-        port = value;
-        index += 1;
-        break;
-      }
-      case "--host":
-        host = argv[index + 1];
-        if (host === void 0) throw usageError("--host needs a value");
-        index += 1;
-        break;
-      case "--out":
-        out = argv[index + 1];
-        if (out === void 0) throw usageError("--out needs a directory");
-        index += 1;
-        break;
-      case "--help":
-      case "-h":
-        command = "help";
-        break;
-      case "--version":
-      case "-v":
-        command = "version";
-        break;
-      case "serve":
-      case "stdio":
-        command = "serve";
-        break;
-      case "agent-context":
-        command = "agent-context";
-        break;
-      case "usage":
-        command = "usage";
-        break;
-      case "skill":
-        command = "skill";
-        break;
-      default:
-        throw usageError(
-          `unknown argument ${JSON.stringify(arg)}`,
-          "run `termwright-mcp usage` for the one-screen cheat sheet"
-        );
-    }
-  }
-  return { command, json, http, port, host, out };
-}
-async function runCli(argv, io = defaultIo) {
-  let json = argv.includes("--json");
-  try {
-    const args = parseArgs(argv);
-    json = args.json;
-    switch (args.command) {
-      case "version":
-        io.out(json ? JSON.stringify({ name: SERVER_NAME, version: SERVER_VERSION }) : SERVER_VERSION);
-        return EXIT_CODES.ok;
-      case "help":
-      case "usage":
-        io.out(json ? JSON.stringify(buildAgentContext()) : buildUsage());
-        return EXIT_CODES.ok;
-      case "agent-context":
-        io.out(JSON.stringify(buildAgentContext(), null, json ? 0 : 2));
-        return EXIT_CODES.ok;
-      case "skill": {
-        if (args.out === void 0) {
-          const files = buildAgentSkill();
-          io.out(
-            json ? JSON.stringify(Object.fromEntries(files.map((file) => [file.path, file.contents]))) : files.map((file) => `=== ${file.path}
-${file.contents}`).join("\n")
-          );
-          return EXIT_CODES.ok;
-        }
-        const written = await writeAgentSkill(args.out);
-        io.out(json ? JSON.stringify({ written }) : written.join("\n"));
-        return EXIT_CODES.ok;
-      }
-      case "serve": {
-        if (args.http) {
-          const handle = await serveHttp({
-            ...args.port === void 0 ? {} : { port: args.port },
-            ...args.host === void 0 ? {} : { host: args.host }
-          });
-          io.err(`${SERVER_NAME} MCP listening on http://${args.host ?? "127.0.0.1"}:${handle.port}/mcp`);
-          await new Promise((resolve) => {
-            handle.http.on("close", resolve);
-          });
-          return EXIT_CODES.ok;
-        }
-        const running = await serveStdio();
-        await new Promise((resolve) => {
-          const shutdown = () => {
-            void running.close().then(resolve, resolve);
-          };
-          process.once("SIGINT", shutdown);
-          process.once("SIGTERM", shutdown);
-          running.server.server.onclose = shutdown;
-        });
-        return EXIT_CODES.ok;
-      }
-    }
-  } catch (error) {
-    const payload = toErrorPayload(error);
-    io.err(json ? JSON.stringify(payload) : `${payload.kind}: ${payload.message}`);
-    if (!json && payload.suggestion !== void 0) io.err(`suggestion: ${payload.suggestion}`);
-    return exitCodeFor(payload.kind);
-  }
-}
-async function main() {
-  process.exitCode = await runCli(process.argv.slice(2));
-}
-
 export {
+  describeCrash,
+  CrashContextError,
   EXIT_CODES,
   exitCodeFor,
   McpError,
@@ -2979,13 +3097,8 @@ export {
   AGENT_CONTEXT_VERSION,
   buildAgentContext,
   buildUsage,
+  renderMcpToolSurfaceMarkdown,
   buildAgentSkill,
-  writeAgentSkill,
-  createTermwrightMcpServer,
-  serveStdio,
-  serveInMemory,
-  serveHttp,
-  runCli,
-  main
+  writeAgentSkill
 };
-//# sourceMappingURL=chunk-IPNUAUAN.js.map
+//# sourceMappingURL=chunk-ROMJP5D3.js.map