tmux-watch 2026.2.3 → 2026.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-watch",
-  "version": "2026.2.3",
+  "version": "2026.2.5",
   "type": "module",
   "description": "OpenClaw tmux output watchdog plugin",
   "license": "MIT",

package/skills/SKILL.md

@@ -63,6 +63,46 @@ tmux send-keys -t <session:window.pane> C-l
 tmux capture-pane -p -J -t <session:window.pane> -S -200
 ```
 
+## Screenshot tools (priority + install)
+
+Priority detection order:
+
+1. System-level PATH (`command -v cryosnap` / `command -v freeze`)
+2. User-level bins (`~/.local/bin`, `~/bin`)
+3. OpenClaw tools dir (`$OPENCLAW_STATE_DIR/tools`, default `~/.openclaw/tools`)
+
+If cryosnap exists, use it. If not, use freeze. If neither exists, **auto-install cryosnap**.
+
+Install commands (downloads the latest GitHub release into the OpenClaw tools dir):
+
+```bash
+openclaw tmux-watch install cryosnap
+openclaw tmux-watch install freeze
+openclaw tmux-watch update cryosnap
+openclaw tmux-watch update freeze
+openclaw tmux-watch remove cryosnap
+openclaw tmux-watch remove freeze
+```
+
+### cryosnap (preferred)
+
+```bash
+# tmux pane -> PNG
+cryosnap --tmux --tmux-args "-t %3 -S -200 -J" --config full -o out.png
+```
+
+Notes:
+
+- For zsh, wrap `%3` in quotes or escape `%` (e.g., `"-t %3 -S -200 -J"`).
+- You can pass `-t session:window.pane` instead of `%pane_id`.
+
+### freeze (fallback)
+
+```bash
+# Capture ANSI text first, then render with freeze
+tmux capture-pane -p -J -e -t <session:window.pane> -S -200 | freeze -o out.png
+```
+
 ## Tool: tmux-watch
 
 ### Add subscription
@@ -72,6 +112,7 @@ tmux capture-pane -p -J -t <session:window.pane> -S -200
   "action": "add",
   "target": "session:0.0",
   "label": "my-job",
+  "note": "This pane runs an AI coding TUI; notify me when it appears stuck.",
   "sessionKey": "main",
   "captureIntervalSeconds": 10,
   "stableCount": 6,

package/src/cli.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { installTool, removeTool, type ToolId } from "./tool-install.js";
 
 type Logger = {
   info: (message: string) => void;
@@ -57,6 +58,14 @@ function resolveSocketFromEnv(): string | undefined {
   return socket || undefined;
 }
 
+function normalizeToolId(raw: string): ToolId {
+  const normalized = raw.trim().toLowerCase();
+  if (normalized !== "cryosnap" && normalized !== "freeze") {
+    throw new Error("Tool must be cryosnap or freeze.");
+  }
+  return normalized as ToolId;
+}
+
 export function registerTmuxWatchCli(params: {
   program: Command;
   api: OpenClawPluginApi;
@@ -117,4 +126,56 @@ export function registerTmuxWatchCli(params: {
     .action(() => {
       printSocketHelp(logger);
     });
+
+  root
+    .command("install")
+    .description("Install cryosnap or freeze into the OpenClaw tools directory")
+    .argument("[tool]", "cryosnap or freeze", "cryosnap")
+    .option("--force", "Replace existing tool binary")
+    .action(async (tool: string, options: { force?: boolean }) => {
+      const normalized = normalizeToolId(tool);
+      const result = await installTool({
+        tool: normalized,
+        api,
+        logger,
+        force: Boolean(options.force),
+      });
+      const version = result.version ? ` (${result.version})` : "";
+      logger.info(`Installed ${result.tool}${version}`);
+      logger.info(`Path: ${result.path}`);
+    });
+
+  root
+    .command("update")
+    .description("Update cryosnap or freeze in the OpenClaw tools directory")
+    .argument("[tool]", "cryosnap or freeze", "cryosnap")
+    .action(async (tool: string) => {
+      const normalized = normalizeToolId(tool);
+      const result = await installTool({
+        tool: normalized,
+        api,
+        logger,
+        force: true,
+      });
+      const version = result.version ? ` (${result.version})` : "";
+      logger.info(`Updated ${result.tool}${version}`);
+      logger.info(`Path: ${result.path}`);
+    });
+
+  root
+    .command("remove")
+    .description("Remove cryosnap or freeze from the OpenClaw tools directory")
+    .argument("[tool]", "cryosnap or freeze", "cryosnap")
+    .action(async (tool: string) => {
+      const normalized = normalizeToolId(tool);
+      const result = await removeTool({
+        tool: normalized,
+        api,
+        logger,
+      });
+      if (result.removed) {
+        logger.info(`Removed ${result.tool}`);
+      }
+      logger.info(`Path: ${result.path}`);
+    });
 }

package/src/manager.ts

@@ -53,22 +53,23 @@ type WatchEntry = {
   runtime: WatchRuntime;
 };
 
-type ResolvedTarget = {
+export type ResolvedTarget = {
   channel: string;
   target: string;
   accountId?: string;
   threadId?: string | number;
   label?: string;
-  source: "targets" | "last";
+  source: "targets" | "last" | "last-fallback";
 };
 
-type SessionEntryLike = {
+export type SessionEntryLike = {
   deliveryContext?: {
     channel?: string;
     to?: string;
     accountId?: string;
     threadId?: string | number;
   };
+  updatedAt?: number;
   lastChannel?: string;
   lastTo?: string;
   lastAccountId?: string;
@@ -83,6 +84,7 @@ type MinimalConfig = {
 };
 
 const STATE_VERSION = 1;
+const INTERNAL_LAST_CHANNELS = new Set(["webchat", "tui"]);
 
 export class TmuxWatchManager {
   private readonly api: OpenClawPluginApi;
@@ -455,60 +457,26 @@ export class TmuxWatchManager {
     }
 
     if (includeLast) {
-      const last = await this.resolveLastTarget(sessionKey);
-      if (last) {
-        targets.push({
-          ...last,
-          source: "last",
-        });
+      const lastTargets = await this.resolveLastTargets(sessionKey);
+      if (lastTargets.length > 0) {
+        targets.push(...lastTargets);
       }
     }
 
     return dedupeTargets(targets);
   }
 
-  private async resolveLastTarget(sessionKey: string): Promise<ResolvedTarget | null> {
-    const entry = await this.readSessionEntry(sessionKey);
-    if (!entry) {
-      return null;
-    }
-    const delivery = entry.deliveryContext ?? {};
-    const channel =
-      typeof delivery.channel === "string"
-        ? delivery.channel.trim()
-        : typeof entry.lastChannel === "string"
-          ? entry.lastChannel.trim()
-          : typeof entry.channel === "string"
-            ? entry.channel.trim()
-            : undefined;
-    const target =
-      typeof delivery.to === "string"
-        ? delivery.to.trim()
-        : typeof entry.lastTo === "string"
-          ? entry.lastTo.trim()
-          : undefined;
-    if (!channel || !target) {
-      return null;
+  private async resolveLastTargets(sessionKey: string): Promise<ResolvedTarget[]> {
+    const store = await this.readSessionStore(sessionKey);
+    if (!store) {
+      return [];
     }
-    const accountId =
-      typeof delivery.accountId === "string"
-        ? delivery.accountId.trim()
-        : typeof entry.lastAccountId === "string"
-          ? entry.lastAccountId.trim()
-          : undefined;
-    const threadId =
-      delivery.threadId ?? entry.lastThreadId ?? entry.origin?.threadId ?? undefined;
-    return {
-      channel,
-      target,
-      accountId: accountId || undefined,
-      threadId: parseThreadId(threadId),
-      label: undefined,
-      source: "last",
-    };
+    return resolveLastTargetsFromStore({ store, sessionKey });
   }
 
-  private async readSessionEntry(sessionKey: string): Promise<SessionEntryLike | null> {
+  private async readSessionStore(
+    sessionKey: string,
+  ): Promise<Record<string, SessionEntryLike> | null> {
     const agentId = resolveAgentIdFromSessionKey(sessionKey);
     const storePath = this.api.runtime.channel.session.resolveStorePath(
       this.api.config.session?.store,
@@ -520,8 +488,10 @@ export class TmuxWatchManager {
       if (!store || typeof store !== "object") {
         return null;
       }
-      return store[sessionKey] ?? store[sessionKey.toLowerCase()] ?? null;
-    } catch {
+      return store;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.api.logger.warn(`[tmux-watch] session store read failed: ${message}`);
       return null;
     }
   }
@@ -769,6 +739,125 @@ function normalizeSessionKey(input: string | undefined, cfg?: MinimalConfig) {
   return `agent:${normalizeAgentId(agentId)}:${lowered}`;
 }
 
+type TargetSnapshot = {
+  channel: string;
+  target: string;
+  accountId?: string;
+  threadId?: string | number;
+};
+
+function isInternalLastChannel(channel: string | undefined): boolean {
+  if (!channel) {
+    return false;
+  }
+  return INTERNAL_LAST_CHANNELS.has(channel.trim().toLowerCase());
+}
+
+function extractTargetSnapshot(entry: SessionEntryLike): TargetSnapshot | null {
+  const delivery = entry.deliveryContext ?? {};
+  const channel =
+    typeof delivery.channel === "string"
+      ? delivery.channel.trim()
+      : typeof entry.lastChannel === "string"
+        ? entry.lastChannel.trim()
+        : typeof entry.channel === "string"
+          ? entry.channel.trim()
+          : undefined;
+  const target =
+    typeof delivery.to === "string"
+      ? delivery.to.trim()
+      : typeof entry.lastTo === "string"
+        ? entry.lastTo.trim()
+        : undefined;
+  if (!channel || !target) {
+    return null;
+  }
+  const accountId =
+    typeof delivery.accountId === "string"
+      ? delivery.accountId.trim()
+      : typeof entry.lastAccountId === "string"
+        ? entry.lastAccountId.trim()
+        : undefined;
+  const threadId =
+    delivery.threadId ?? entry.lastThreadId ?? entry.origin?.threadId ?? undefined;
+  return {
+    channel,
+    target,
+    accountId: accountId || undefined,
+    threadId,
+  };
+}
+
+function snapshotKey(snapshot: TargetSnapshot): string {
+  return [snapshot.channel, snapshot.target, snapshot.accountId ?? "", snapshot.threadId ?? ""].join(
+    "|",
+  );
+}
+
+function findLatestExternalTarget(
+  store: Record<string, SessionEntryLike>,
+  exclude: TargetSnapshot,
+): TargetSnapshot | null {
+  const excludeKey = snapshotKey(exclude);
+  let best: { updatedAt: number; target: TargetSnapshot } | null = null;
+  for (const entry of Object.values(store)) {
+    const snapshot = extractTargetSnapshot(entry);
+    if (!snapshot) {
+      continue;
+    }
+    if (isInternalLastChannel(snapshot.channel)) {
+      continue;
+    }
+    if (snapshotKey(snapshot) === excludeKey) {
+      continue;
+    }
+    const updatedAt = typeof entry.updatedAt === "number" ? entry.updatedAt : 0;
+    if (!best || updatedAt > best.updatedAt) {
+      best = { updatedAt, target: snapshot };
+    }
+  }
+  return best?.target ?? null;
+}
+
+function toResolvedTarget(
+  snapshot: TargetSnapshot,
+  source: ResolvedTarget["source"],
+): ResolvedTarget {
+  return {
+    channel: snapshot.channel,
+    target: snapshot.target,
+    accountId: snapshot.accountId,
+    threadId: parseThreadId(snapshot.threadId),
+    label: undefined,
+    source,
+  };
+}
+
+export function resolveLastTargetsFromStore(params: {
+  store: Record<string, SessionEntryLike>;
+  sessionKey: string;
+}): ResolvedTarget[] {
+  const entry =
+    params.store[params.sessionKey] ??
+    params.store[params.sessionKey.toLowerCase()] ??
+    null;
+  if (!entry) {
+    return [];
+  }
+  const primary = extractTargetSnapshot(entry);
+  if (!primary) {
+    return [];
+  }
+  const targets: ResolvedTarget[] = [toResolvedTarget(primary, "last")];
+  if (isInternalLastChannel(primary.channel)) {
+    const fallback = findLatestExternalTarget(params.store, primary);
+    if (fallback) {
+      targets.push(toResolvedTarget(fallback, "last-fallback"));
+    }
+  }
+  return targets;
+}
+
 function hashOutput(output: string): string {
   return createHash("sha256").update(output).digest("hex");
 }

package/src/tool-install.ts

@@ -0,0 +1,307 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+type Logger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+export type ToolId = "cryosnap" | "freeze";
+
+export type ReleaseAsset = {
+  name: string;
+  browser_download_url: string;
+};
+
+type ReleaseResponse = {
+  tag_name?: string;
+  assets?: ReleaseAsset[];
+};
+
+type ToolSpec = {
+  id: ToolId;
+  repo: string;
+  binary: string;
+};
+
+const TOOL_SPECS: Record<ToolId, ToolSpec> = {
+  cryosnap: {
+    id: "cryosnap",
+    repo: "Wangnov/cryosnap",
+    binary: "cryosnap",
+  },
+  freeze: {
+    id: "freeze",
+    repo: "charmbracelet/freeze",
+    binary: "freeze",
+  },
+};
+
+const ARCH_TOKENS: Record<string, string[]> = {
+  x64: ["x86_64", "amd64", "x64"],
+  arm64: ["aarch64", "arm64"],
+  arm: ["armv7", "armv6", "arm"],
+};
+
+const PLATFORM_TOKENS: Record<string, string[]> = {
+  darwin: ["darwin", "apple-darwin", "macos", "mac"],
+  linux: ["linux", "unknown-linux", "linux-gnu", "linux-musl"],
+  win32: ["windows", "win32", "msvc", "pc-windows"],
+};
+
+const ARCHIVE_EXTENSIONS = [".tar.gz", ".tgz", ".zip", ".tar.xz"];
+
+export async function installTool(params: {
+  tool: ToolId;
+  api: OpenClawPluginApi;
+  logger: Logger;
+  force?: boolean;
+}): Promise<{ tool: ToolId; version?: string; path: string; asset: string }> {
+  if (process.env.OPENCLAW_NIX_MODE === "1") {
+    throw new Error("OPENCLAW_NIX_MODE=1; auto-install is disabled.");
+  }
+  const spec = TOOL_SPECS[params.tool];
+  if (!spec) {
+    throw new Error(`Unknown tool: ${params.tool}`);
+  }
+
+  const toolsDir = resolveToolsDir(params.api);
+  await fs.mkdir(toolsDir, { recursive: true, mode: 0o700 });
+
+  const binaryName = resolveBinaryName(spec.binary);
+  const destPath = path.join(toolsDir, binaryName);
+  if (!params.force) {
+    try {
+      await fs.access(destPath);
+      params.logger.info(`Tool already installed: ${destPath}`);
+      return { tool: spec.id, path: destPath, asset: binaryName };
+    } catch {
+      // proceed
+    }
+  }
+
+  params.logger.info(`Fetching latest release for ${spec.repo}...`);
+  const release = await fetchLatestRelease(spec.repo);
+  const assets = release.assets ?? [];
+  const selected = selectReleaseAsset({
+    assets,
+    binaryName: spec.binary,
+  });
+  if (!selected) {
+    throw new Error(
+      `No matching release asset found for ${spec.repo} (${process.platform}/${process.arch}).`,
+    );
+  }
+
+  const tmpDir = await fs.mkdtemp(path.join(toolsDir, `.tmp-${spec.id}-`));
+  try {
+    const downloadPath = path.join(tmpDir, selected.name);
+    params.logger.info(`Downloading ${selected.name}...`);
+    await downloadFile(selected.browser_download_url, downloadPath);
+
+    const extracted = await extractIfNeeded(params.api, downloadPath, tmpDir);
+    const binPath = extracted
+      ? await findBinary(tmpDir, binaryName)
+      : downloadPath;
+
+    if (!binPath) {
+      throw new Error(`Binary ${binaryName} not found in extracted archive.`);
+    }
+
+    await fs.copyFile(binPath, destPath);
+    if (process.platform !== "win32") {
+      await fs.chmod(destPath, 0o755);
+    }
+
+    params.logger.info(`Installed ${spec.id} -> ${destPath}`);
+    return {
+      tool: spec.id,
+      version: release.tag_name,
+      path: destPath,
+      asset: selected.name,
+    };
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+export async function removeTool(params: {
+  tool: ToolId;
+  api: OpenClawPluginApi;
+  logger: Logger;
+}): Promise<{ tool: ToolId; path: string; removed: boolean }> {
+  const spec = TOOL_SPECS[params.tool];
+  if (!spec) {
+    throw new Error(`Unknown tool: ${params.tool}`);
+  }
+  const toolsDir = resolveToolsDir(params.api);
+  const binaryName = resolveBinaryName(spec.binary);
+  const destPath = path.join(toolsDir, binaryName);
+  try {
+    await fs.access(destPath);
+  } catch {
+    params.logger.info(`Tool not found: ${destPath}`);
+    return { tool: spec.id, path: destPath, removed: false };
+  }
+  await fs.rm(destPath, { force: true });
+  params.logger.info(`Removed ${spec.id} -> ${destPath}`);
+  return { tool: spec.id, path: destPath, removed: true };
+}
+
+function resolveToolsDir(api: OpenClawPluginApi): string {
+  const stateDir = resolveStateDir(api);
+  return path.join(stateDir, "tools");
+}
+
+function resolveStateDir(api: OpenClawPluginApi): string {
+  const resolver = api.runtime?.state?.resolveStateDir;
+  if (typeof resolver === "function") {
+    return resolver();
+  }
+  return path.join(os.homedir(), ".openclaw");
+}
+
+function resolveBinaryName(base: string): string {
+  if (process.platform === "win32") {
+    return `${base}.exe`;
+  }
+  return base;
+}
+
+async function fetchLatestRelease(repo: string): Promise<ReleaseResponse> {
+  const url = `https://api.github.com/repos/${repo}/releases/latest`;
+  const response = await fetch(url, {
+    headers: {
+      "User-Agent": "openclaw-tmux-watch",
+      Accept: "application/vnd.github+json",
+    },
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`GitHub release fetch failed (${response.status}): ${body}`);
+  }
+  return (await response.json()) as ReleaseResponse;
+}
+
+export function selectReleaseAsset(params: {
+  assets: ReleaseAsset[];
+  binaryName: string;
+  platform?: string;
+  arch?: string;
+}): ReleaseAsset | null {
+  const platform = params.platform ?? process.platform;
+  const arch = params.arch ?? process.arch;
+  const assets = params.assets ?? [];
+  let best: { asset: ReleaseAsset; score: number } | null = null;
+
+  for (const asset of assets) {
+    const score = scoreAsset(asset.name, params.binaryName, platform, arch);
+    if (score <= 0) {
+      continue;
+    }
+    if (!best || score > best.score) {
+      best = { asset, score };
+    }
+  }
+
+  return best?.asset ?? null;
+}
+
+function scoreAsset(
+  name: string,
+  binaryName: string,
+  platform: string,
+  arch: string,
+): number {
+  const lowered = name.toLowerCase();
+  if (/(sha256|checksums|sbom|sig|signature|\.txt)$/.test(lowered)) {
+    return 0;
+  }
+
+  const platformTokens = PLATFORM_TOKENS[platform] ?? [];
+  const archTokens = ARCH_TOKENS[arch] ?? [];
+
+  let score = 0;
+  if (lowered.includes(binaryName)) {
+    score += 2;
+  }
+  for (const token of platformTokens) {
+    if (lowered.includes(token)) {
+      score += 3;
+      break;
+    }
+  }
+  for (const token of archTokens) {
+    if (lowered.includes(token)) {
+      score += 2;
+      break;
+    }
+  }
+  if (ARCHIVE_EXTENSIONS.some((ext) => lowered.endsWith(ext))) {
+    score += 1;
+  }
+  return score;
+}
+
+async function downloadFile(url: string, destPath: string): Promise<void> {
+  const response = await fetch(url, { headers: { "User-Agent": "openclaw-tmux-watch" } });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Download failed (${response.status}): ${body}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(destPath, buffer);
+}
+
+async function extractIfNeeded(
+  api: OpenClawPluginApi,
+  archivePath: string,
+  destDir: string,
+): Promise<boolean> {
+  const lowered = archivePath.toLowerCase();
+  if (lowered.endsWith(".zip")) {
+    await runCommand(api, ["unzip", "-o", archivePath, "-d", destDir]);
+    return true;
+  }
+  if (lowered.endsWith(".tar.gz") || lowered.endsWith(".tgz")) {
+    await runCommand(api, ["tar", "-xzf", archivePath, "-C", destDir]);
+    return true;
+  }
+  if (lowered.endsWith(".tar.xz")) {
+    await runCommand(api, ["tar", "-xJf", archivePath, "-C", destDir]);
+    return true;
+  }
+  return false;
+}
+
+async function runCommand(api: OpenClawPluginApi, argv: string[]): Promise<void> {
+  const result = await api.runtime.system.runCommandWithTimeout(argv, {
+    timeoutMs: 120_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(`Command failed: ${argv.join(" ")}\n${result.stderr ?? ""}`.trim());
+  }
+}
+
+async function findBinary(dir: string, binaryName: string): Promise<string | null> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === "__MACOSX") {
+      continue;
+    }
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isFile() && entry.name === binaryName) {
+      return fullPath;
+    }
+    if (entry.isDirectory()) {
+      const nested = await findBinary(fullPath, binaryName);
+      if (nested) {
+        return nested;
+      }
+    }
+  }
+  return null;
+}