@lattices/cli 0.5.0 → 0.6.1

package/README.md

@@ -7,7 +7,7 @@
 The agentic workspace manager for macOS.
 
 Lattices turns your Mac workspace into a coherent API, so agents can see and
-control windows, tmux sessions, screen text, and layouts. It also gives you
+control windows, terminal sessions, screen text, and layouts. It also gives you
 an assistant to control that workspace in plain language.
 
 **[lattices.dev](https://lattices.dev)** · [Docs](https://lattices.dev/docs/overview) · [Download](https://github.com/arach/lattices/releases/latest)
@@ -31,10 +31,11 @@ your project directory.
 ### Install the CLI
 
 ```sh
-npm install -g @lattices/cli
+npm install -g @arach/lattices
 ```
 
-The CLI and app work independently — use either or both.
+Also published as `@lattices/cli` for existing installs. The CLI and app work
+independently — use either or both.
 
 ### Build from source
 
@@ -46,7 +47,7 @@ cd lattices
 npm install
 
 # Build/install/relaunch the dev app at the stable permission target
-./run.sh
+./scripts/run.sh
 ```
 
 To build a signed, notarized DMG for distribution:
@@ -64,9 +65,15 @@ See [Release](docs/release.md) for the CI and local maintainer workflows.
 ## Quick start
 
 ```sh
+# Show workspace status for the current directory
+lattices
+
 # Launch the menu bar app
 lattices app
 
+# Start or reattach a tmux session
+lattices start
+
 # Open the command palette from anywhere
 # Cmd+Shift+M
 ```
@@ -163,7 +170,7 @@ events over WebSocket. Anything you can do from the app, an agent or
 script can do over the API.
 
 ```js
-import { daemonCall } from '@lattices/cli/daemon-client'
+import { daemonCall } from '@arach/lattices/daemon-client'
 
 // Search windows by content — title, app, session tags, OCR
 const results = await daemonCall('windows.search', { query: 'myproject' })
@@ -182,6 +189,7 @@ Or from the CLI:
 ```sh
 lattices search myproject           # Find windows by content
 lattices search myproject --deep    # Include terminal tab/process data
+lattices search myproject --all     # Same as --deep (all search sources)
 lattices place myproject left       # Search + focus + tile in one step
 ```
 
@@ -199,6 +207,7 @@ lattices ls                 List active sessions
 lattices kill [name]        Kill a session
 lattices search <query>     Search windows by title, app, session, OCR
 lattices search <q> --deep  Deep search: index + terminal inspection
+lattices search <q> --all   Same as --deep (all search sources)
 lattices place <query> [pos]  Deep search + focus + tile
 lattices focus <session>    Raise a session's window
 lattices tile <position>    Tile frontmost window

package/apps/mac/Info.plist

@@ -26,15 +26,17 @@
         </dict>
     </array>
     <key>CFBundleVersion</key>
-    <string>0.4.8</string>
+    <string>0.6.1</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.4.8</string>
+    <string>0.6.1</string>
     <key>LSMinimumSystemVersion</key>
     <string>13.0</string>
     <key>LSUIElement</key>
     <true/>
     <key>NSHighResolutionCapable</key>
     <true/>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Lattices uses the microphone for Hudson Voice dictation and voice commands.</string>
     <key>NSSupportsAutomaticTermination</key>
     <true/>
 </dict>

package/apps/mac/Lattices.app/Contents/Info.plist

@@ -26,15 +26,17 @@
         </dict>
     </array>
     <key>CFBundleVersion</key>
-    <string>0.5.0</string>
+    <string>0.6.1</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.5.0</string>
+    <string>0.6.1</string>
     <key>LSMinimumSystemVersion</key>
     <string>13.0</string>
     <key>LSUIElement</key>
     <true/>
     <key>NSHighResolutionCapable</key>
     <true/>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>Lattices uses the microphone for Hudson Voice dictation and voice commands.</string>
     <key>NSSupportsAutomaticTermination</key>
     <true/>
 </dict>

package/apps/mac/Lattices.app/Contents/Resources/docs/assistant-knowledge.md

@@ -0,0 +1,130 @@
+---
+type: Assistant Knowledge Base
+title: Lattices — Assistant Knowledge
+description: Orientation + capability map the in-app Workspace Assistant uses to explain Lattices and point to the right feature or doc
+audience: assistant
+---
+
+> You are reading the Workspace Assistant's knowledge base. It summarizes what
+> Lattices can do and links to the deeper docs. Treat the **structured context**
+> in your prompt (current settings, file paths, CLI commands) as ground truth for
+> *this user's* configuration; treat this file as ground truth for *how Lattices
+> works*. When a question goes deeper than this summary, name the relevant doc
+> (see [References](#references)) instead of guessing.
+
+## What Lattices is
+
+Lattices is an **agentic window manager for macOS** — a programmable workspace
+that pairs a native menu bar app with managed tmux sessions and a scriptable
+agent API. Three layers, one product:
+
+1. **Programmable workspace** — a CLI and a WebSocket agent API (`ws://127.0.0.1:9399`,
+   35+ methods, real-time events) that let scripts and AI agents observe and drive
+   the desktop the same way a person does.
+2. **Smart layout manager** — the menu bar app tracks every window across all
+   monitors: tiling, switchable layers, snap zones, and screen-text indexing.
+3. **Managed tmux sessions** — declare a dev environment in `.lattices.json`;
+   Lattices builds it, runs it, and keeps it alive across reboots.
+
+Requirements: macOS 26+, Node 18+; tmux only for session management.
+See [Overview](/docs/overview) and [Concepts](/docs/concepts).
+
+## Capability map
+
+Each area below is a one-paragraph summary plus the doc to cite for detail.
+
+### Window tiling & placement
+Snap windows to preset positions — halves, quarters, thirds, maximize, center —
+from the command palette or `lattices tile <position>`. There is also a grid
+placement primitive: compact `CxR:c,r` starts at 1 for command entry, while
+canonical `grid:CxR:c,r` starts at 0 for APIs. → [Tiling reference](/docs/tiling-reference), positions in [Configuration](/docs/config).
+
+### Workspace layers & tab groups
+Group projects into named **layers** you can switch between, and tab-group related
+windows. `workspace.json` layers launch/focus/tile projects. Studio layers are
+rule-backed live window sets persisted in `~/.lattices/layers.json`; their clauses
+support app/title/session exact, substring, regex, Space, visibility, and exclusion
+matches. → [Layers](/docs/layers).
+
+### Command palette & menu bar app
+The palette (**Cmd+Shift+M**) is the app's primary surface: launch projects, tile,
+sync, restart, open settings — all searchable. → [Menu Bar App](/docs/app).
+
+### tmux sessions (`.lattices.json`)
+Declare panes, commands, and layout per project. `lattices start` builds/attaches a
+persistent session named `<basename>-<hash>`; `lattices sync` reconciles a running
+session to its config. **Ensure** re-runs exited commands on reattach; **prefill**
+types them and waits. → [Concepts](/docs/concepts), [Configuration](/docs/config).
+
+### Screen OCR & search
+The app reads on-screen text via the Accessibility API (~60s) and Apple Vision OCR
+on background windows (~2h), indexing everything with FTS5. Search across titles,
+app names, session tags, and OCR with `lattices search <query>` (add `--deep` or
+`--all` to inspect terminal tabs by cwd). → [Screen OCR & Search](/docs/ocr).
+
+### Voice commands
+Natural-language voice control for window management ("put the browser on the
+right", "switch to the backend layer"). → [Voice Commands](/docs/voice).
+
+### Mouse gestures
+Hold a mouse button, draw a direction or shape, release — runs the matched action.
+Configured via `mouseGestures.enabled` plus `~/.lattices/mouse-shortcuts.json`.
+→ [Mouse Gestures](/docs/mouse-gestures).
+
+### Agent API & CLI
+Agents connect over WebSocket and get the same control as a person: list
+windows/projects, launch sessions, tile, switch layers, read screen text, and
+subscribe to events (`windows.changed`, `tmux.changed`, `layer.switched`).
+→ [Agent Guide](/docs/agents), [Agent API](/docs/api).
+
+### Project twins
+Pi-backed project "twins" for mediated, persistent agent execution scoped to a
+project. → [Project Twins](/docs/twins).
+
+## Key shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd+Shift+M** | Open the command palette |
+| `lattices tile <position>` | Tile the focused window (CLI) |
+| `lattices layer [name\|index]` | Switch workspace layer (CLI) |
+| **Ctrl+B** then `D` / `Z` / arrows | tmux: detach / zoom / move pane (inside a session) |
+
+Tiling and grid hotkeys are user-configurable — for the live set, point the user to
+Settings or the [Tiling reference](/docs/tiling-reference) rather than asserting one.
+
+## CLI quick reference
+
+`lattices` · `lattices init` · `lattices sync` · `lattices start` ·
+`lattices restart [pane]` · `lattices tile <position>` · `lattices group [id]` ·
+`lattices layer [name|index]` · `lattices windows --json` ·
+`lattices search <query> [--deep|--all] [--json] [--wid]` · `lattices place <query> [position]` ·
+`lattices app restart`. Full flags: [Configuration](/docs/config).
+
+## Config & file locations
+
+- **Per project:** `.lattices.json` in the project root (panes, commands, layout, ensure/prefill).
+- **User config (`~/.lattices/`):** `workspace.json`, `layers.json`, `mouse-shortcuts.json`,
+  `snap-zones.json`, `clusters.json`, `ocr.db`, `lattices.log`.
+- **Defaults domain:** `dev.lattices.app` (read/write app settings via `defaults`).
+
+The exact current values and paths for *this* machine arrive in your structured
+context — prefer those over the generic paths above when answering.
+
+## References
+
+| Topic | Doc |
+|-------|-----|
+| What it is / who it's for | [Overview](/docs/overview) |
+| Install & first run | [Quickstart](/docs/quickstart) |
+| Architecture, glossary, internals | [Concepts](/docs/concepts) |
+| `.lattices.json`, CLI, tile positions | [Configuration](/docs/config) |
+| Command palette, tiling, sessions | [Menu Bar App](/docs/app) |
+| Tiling & grid placement | [Tiling reference](/docs/tiling-reference) |
+| Layers & tab groups | [Layers](/docs/layers) |
+| Screen OCR & full-text search | [Screen OCR & Search](/docs/ocr) |
+| Voice control | [Voice Commands](/docs/voice) |
+| Mouse gestures | [Mouse Gestures](/docs/mouse-gestures) |
+| Agent contracts (voice/CLI/daemon) | [Agent Guide](/docs/agents) |
+| WebSocket RPC method reference | [Agent API](/docs/api) |
+| Project twins | [Project Twins](/docs/twins) |

package/apps/mac/Lattices.app/Contents/_CodeSignature/CodeResources

@@ -8,6 +8,10 @@
 		<data>
 		3sIZmtGJHMo2S/XvIMl46SOHcFY=
 		</data>
+		<key>Resources/docs/assistant-knowledge.md</key>
+		<data>
+		+ps2zJk/lYJk2p6BwFaTyELnEYc=
+		</data>
 		<key>Resources/tap.wav</key>
 		<data>
 		eOpp5td/ovQGMumXPpwy4Vyt/uc=
@@ -22,6 +26,13 @@
 			LZsztS/9I1hmuQmDOk+anfxOpqVryB3y4a1kwSaUK4s=
 			</data>
 		</dict>
+		<key>Resources/docs/assistant-knowledge.md</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			R8Iq4eNj09I0SVKg3WEFeYJ6q1tLM4x3hwTG9XO7oco=
+			</data>
+		</dict>
 		<key>Resources/tap.wav</key>
 		<dict>
 			<key>hash2</key>

package/apps/mac/Lattices.entitlements

@@ -11,5 +11,11 @@
     <true/>
     <key>com.apple.security.network.client</key>
     <true/>
+
+    <!-- Microphone: required under Hardened Runtime for the embedded Hudson Voice
+         dictation/voice-command capture. Without it, AVCaptureDevice.requestAccess
+         is denied instantly with no prompt. -->
+    <key>com.apple.security.device.audio-input</key>
+    <true/>
 </dict>
 </plist>

package/bin/assistant-intelligence.ts

@@ -87,7 +87,7 @@ export const intentDefinitions: IntentDefinition[] = [
     intent: "tile_window",
     description: "Tile one window to a named position or grid cell.",
     slots: [
-      { name: "position", required: true, description: "Named tile position or grid:CxR:C,R syntax." },
+      { name: "position", required: true, description: "Named tile position, canonical 0-based grid:CxR:C,R, or compact 1-based CxR:C,R syntax." },
       { name: "app", description: "Loose app name when no window id is known." },
       { name: "wid", description: "Specific macOS window id from the desktop snapshot." },
       { name: "session", description: "Tmux session name." },
@@ -96,6 +96,7 @@ export const intentDefinitions: IntentDefinition[] = [
       "tile chrome left",
       "snap this to the top right",
       "maximize the window",
+      "put chrome in the top-right cell of a 4x4 grid",
     ],
   },
   {
@@ -687,8 +688,11 @@ function parseLayerSwitch(text: string): string | null {
 }
 
 function findPosition(text: string): { position: string; phrase: string } | null {
-  const grid = text.match(/grid:\d+x\d+:\d+,\d+/);
-  if (grid) return { position: grid[0], phrase: grid[0] };
+  const grid = text.match(/(?:grid:)?\d+x\d+:\d+,\d+(?:-\d+,\d+)?/);
+  if (grid) {
+    const position = canonicalGridPosition(grid[0]);
+    if (position) return { position, phrase: grid[0] };
+  }
 
   for (const entry of positionAliases) {
     for (const phrase of entry.phrases) {
@@ -700,6 +704,40 @@ function findPosition(text: string): { position: string; phrase: string } | null
   return null;
 }
 
+function canonicalGridPosition(raw: string): string | null {
+  const match = raw.toLowerCase().match(/^(grid:)?(\d+)x(\d+):(\d+),(\d+)(?:-(\d+),(\d+))?$/);
+  if (!match) return null;
+
+  const oneBased = !match[1];
+  const columns = Number(match[2]);
+  const rows = Number(match[3]);
+  let c0 = Number(match[4]);
+  let r0 = Number(match[5]);
+  let c1 = match[6] === undefined ? c0 : Number(match[6]);
+  let r1 = match[7] === undefined ? r0 : Number(match[7]);
+  if (oneBased) {
+    c0 -= 1;
+    r0 -= 1;
+    c1 -= 1;
+    r1 -= 1;
+  }
+
+  const left = Math.min(c0, c1);
+  const right = Math.max(c0, c1);
+  const top = Math.min(r0, r1);
+  const bottom = Math.max(r0, r1);
+  if (
+    columns <= 0 || rows <= 0 ||
+    left < 0 || top < 0 ||
+    right >= columns || bottom >= rows
+  ) {
+    return null;
+  }
+
+  if (left === right && top === bottom) return `grid:${columns}x${rows}:${left},${top}`;
+  return `grid:${columns}x${rows}:${left},${top}-${right},${bottom}`;
+}
+
 function regionFromText(text: string): string | null {
   const hit = findPosition(text);
   if (!hit) return null;

package/bin/cli/capture.ts

@@ -0,0 +1,252 @@
+import {
+  hasFlag,
+  nonFlagArgs,
+  parseFlagValue,
+  parseOptionalNumber,
+} from "./helpers.ts";
+import { withDaemon } from "./daemon.ts";
+
+export async function captureCommand(subcommand?: string, ...rawArgs: string[]): Promise<void> {
+  const sub = subcommand || "window";
+  const dashIndex = rawArgs.indexOf("--");
+  const commandArgs = dashIndex >= 0 ? rawArgs.slice(0, dashIndex) : rawArgs;
+  const childArgs = dashIndex >= 0 ? rawArgs.slice(dashIndex + 1) : [];
+  const jsonFlag = hasFlag(commandArgs, "json");
+  const positional = nonFlagArgs(commandArgs);
+
+  if (["stop", "stop-recording", "stopRecording"].includes(sub)) {
+    const params: Record<string, unknown> = {};
+    const runId = positional[0] || parseFlagValue(commandArgs, "run-id") || parseFlagValue(commandArgs, "runId") || parseFlagValue(commandArgs, "id");
+    const stopFile = parseFlagValue(commandArgs, "stop-file") || parseFlagValue(commandArgs, "stopFile");
+    const finishedFile = parseFlagValue(commandArgs, "finished-file") || parseFlagValue(commandArgs, "finishedFile");
+    const timeoutMs = Number(parseFlagValue(commandArgs, "timeout-ms") || parseFlagValue(commandArgs, "timeoutMs") || 30000);
+    if (runId) params.runId = runId;
+    if (stopFile) params.stopFile = stopFile;
+    if (finishedFile) params.finishedFile = finishedFile;
+    if (Number.isFinite(timeoutMs)) params.timeoutMs = timeoutMs;
+    params.wait = !hasFlag(commandArgs, "no-wait");
+
+    await withDaemon(async ({ daemonCall }) => {
+      const result = await daemonCall("capture.stopRecording", params, timeoutMs + 5000) as any;
+      if (jsonFlag) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(result.finished ? "Recording finished." : "Recording stop requested.");
+      if (result.run?.id) console.log(`  run: ${result.run.id}`);
+      if (result.marker) console.log(`  marker: ${result.marker}`);
+    });
+    return;
+  }
+
+  const isRecordCommand = [
+    "record-command",
+    "recordCommand",
+    "record-run",
+    "recordRun",
+    "record-exec",
+    "recordExec",
+  ].includes(sub);
+
+  if (isRecordCommand) {
+    if (!childArgs.length) {
+      console.log(`lattices capture record-command — record while running a command
+
+Usage:
+  lattices capture record-command --app Scout --filename demo.mov -- <command> [...args]
+`);
+      return;
+    }
+
+    const params: Record<string, unknown> = { source: "cli" };
+    const explicitWid = positional[0] ? Number(positional[0]) : NaN;
+    if (Number.isFinite(explicitWid)) params.wid = explicitWid;
+
+    const session = parseFlagValue(commandArgs, "session");
+    const app = parseFlagValue(commandArgs, "app");
+    const title = parseFlagValue(commandArgs, "title");
+    const filename = parseFlagValue(commandArgs, "filename");
+    const runId = parseFlagValue(commandArgs, "run-id") || parseFlagValue(commandArgs, "runId");
+    const mode = parseFlagValue(commandArgs, "mode");
+    const fps = parseOptionalNumber(commandArgs, "fps");
+    const scale = parseOptionalNumber(commandArgs, "scale");
+    const timeoutMs = Number(parseFlagValue(commandArgs, "timeout-ms") || parseFlagValue(commandArgs, "timeoutMs") || 30000);
+    if (session) params.session = session;
+    if (app) params.app = app;
+    if (title) params.title = title;
+    if (filename) params.filename = filename;
+    if (runId) params.runId = runId;
+    if (mode) params.mode = mode;
+    if (fps !== undefined) params.fps = fps;
+    if (scale !== undefined) params.scale = scale;
+
+    for (const [flag, key] of [["x", "x"], ["y", "y"], ["width", "width"], ["height", "height"], ["w", "w"], ["h", "h"]] as const) {
+      const value = parseOptionalNumber(commandArgs, flag);
+      if (value !== undefined) params[key] = value;
+    }
+
+    const recordsRegion = hasFlag(commandArgs, "region") ||
+      (params.x !== undefined && params.y !== undefined &&
+        (params.width !== undefined || params.w !== undefined) &&
+        (params.height !== undefined || params.h !== undefined));
+    const method = recordsRegion ? "capture.recordRegion" : "capture.recordWindow";
+
+    await withDaemon(async ({ daemonCall }) => {
+      const start = await daemonCall(method, params, 20000) as any;
+      let childExitCode = 0;
+      let childError: string | undefined;
+
+      try {
+        const proc = Bun.spawn(childArgs, {
+          cwd: process.cwd(),
+          env: process.env,
+          stdin: "inherit",
+          stdout: "inherit",
+          stderr: "inherit",
+        });
+        childExitCode = await proc.exited;
+      } catch (error) {
+        childExitCode = 127;
+        childError = (error as Error).message;
+      }
+
+      const stop = await daemonCall(
+        "capture.stopRecording",
+        { runId: start.run?.id, wait: true, timeoutMs },
+        timeoutMs + 5000
+      ) as any;
+
+      if (jsonFlag) {
+        console.log(JSON.stringify({
+          ok: childExitCode === 0 && stop.ok !== false,
+          child: {
+            command: childArgs,
+            exitCode: childExitCode,
+            error: childError,
+          },
+          recording: start,
+          stopResult: stop,
+        }, null, 2));
+      } else {
+        const artifact = start.artifact || {};
+        const run = stop.run || start.run || {};
+        console.log(`Recording finished.`);
+        console.log(`  run: ${run.id || start.run?.id || "?"}`);
+        console.log(`  artifact: ${artifact.path || "?"}`);
+        console.log(`  child exit: ${childExitCode}`);
+        if (childError) console.log(`  child error: ${childError}`);
+      }
+
+      if (childExitCode !== 0 && !hasFlag(commandArgs, "ignore-child-failure")) {
+        process.exitCode = childExitCode;
+      }
+    });
+    return;
+  }
+
+  const isRecord = ["record", "record-window", "recording", "video"].includes(sub);
+  const isRecordRegion = ["record-region", "recordRegion", "region-recording"].includes(sub) ||
+    (sub === "record" && ["region", "rect"].includes(positional[0] || ""));
+
+  if (isRecord || isRecordRegion) {
+    const params: Record<string, unknown> = { source: "cli" };
+    const targetKind = sub === "record" ? positional[0] : undefined;
+    const positionalOffset = targetKind === "window" || targetKind === "region" || targetKind === "rect" ? 1 : 0;
+    const explicitWid = positional[positionalOffset] ? Number(positional[positionalOffset]) : NaN;
+    if (Number.isFinite(explicitWid)) params.wid = explicitWid;
+
+    const session = parseFlagValue(commandArgs, "session");
+    const app = parseFlagValue(commandArgs, "app");
+    const title = parseFlagValue(commandArgs, "title");
+    const filename = parseFlagValue(commandArgs, "filename");
+    const runId = parseFlagValue(commandArgs, "run-id") || parseFlagValue(commandArgs, "runId");
+    const mode = parseFlagValue(commandArgs, "mode");
+    const fps = parseOptionalNumber(commandArgs, "fps");
+    const scale = parseOptionalNumber(commandArgs, "scale");
+    const durationMs = parseOptionalNumber(commandArgs, "duration-ms", "durationMs", "duration");
+    if (session) params.session = session;
+    if (app) params.app = app;
+    if (title) params.title = title;
+    if (filename) params.filename = filename;
+    if (runId) params.runId = runId;
+    if (mode) params.mode = mode;
+    if (fps !== undefined) params.fps = fps;
+    if (scale !== undefined) params.scale = scale;
+
+    for (const [flag, key] of [["x", "x"], ["y", "y"], ["width", "width"], ["height", "height"], ["w", "w"], ["h", "h"]] as const) {
+      const value = parseOptionalNumber(commandArgs, flag);
+      if (value !== undefined) params[key] = value;
+    }
+
+    await withDaemon(async ({ daemonCall }) => {
+      const method = isRecordRegion ? "capture.recordRegion" : "capture.recordWindow";
+      const result = await daemonCall(method, params, 20000) as any;
+
+      if (durationMs !== undefined && durationMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, durationMs));
+        const stop = await daemonCall(
+          "capture.stopRecording",
+          { runId: result.run?.id, wait: true, timeoutMs: 30000 },
+          35000
+        ) as any;
+        result.stopResult = stop;
+      }
+
+      if (jsonFlag) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const artifact = result.artifact || {};
+      const run = result.stopResult?.run || result.run || {};
+      console.log(`Recording ${result.stopResult ? "finished" : "started"}.`);
+      console.log(`  run: ${run.id || result.run?.id || "?"}`);
+      console.log(`  artifact: ${artifact.path || "?"}`);
+      if (!result.stopResult) {
+        console.log(`  stop: lattices capture stop ${result.run?.id || ""}`);
+      }
+    });
+    return;
+  }
+
+  if (!["window", "screenshot", "shot"].includes(sub)) {
+    console.log(`lattices capture — capture run artifacts
+
+Usage:
+  lattices capture window [wid] [--json]
+  lattices capture screenshot [wid] [--session name] [--app name]
+  lattices capture record window [wid] [--app name] [--duration-ms 5000] [--json]
+  lattices capture record region --x N --y N --width N --height N [--duration-ms 5000]
+  lattices capture record-command --app Scout --filename demo.mov -- <command> [...args]
+  lattices capture stop <run-id>
+`);
+    return;
+  }
+
+  const params: Record<string, unknown> = { source: "cli" };
+  const explicitWid = positional[0] ? Number(positional[0]) : NaN;
+  if (Number.isFinite(explicitWid)) params.wid = explicitWid;
+  const session = parseFlagValue(commandArgs, "session");
+  const app = parseFlagValue(commandArgs, "app");
+  const title = parseFlagValue(commandArgs, "title");
+  const filename = parseFlagValue(commandArgs, "filename");
+  const runId = parseFlagValue(commandArgs, "run-id") || parseFlagValue(commandArgs, "runId");
+  if (session) params.session = session;
+  if (app) params.app = app;
+  if (title) params.title = title;
+  if (filename) params.filename = filename;
+  if (runId) params.runId = runId;
+
+  await withDaemon(async ({ daemonCall }) => {
+    const result = await daemonCall("capture.screenshotWindow", params, 20000) as any;
+    if (jsonFlag) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const artifact = result.artifact || {};
+    const run = result.run || {};
+    const target = result.target || {};
+    console.log(`Captured ${target.app || "window"} ${target.wid ? `wid:${target.wid}` : ""}`);
+    console.log(`  run: ${run.id || "?"}`);
+    console.log(`  artifact: ${artifact.path || "?"}`);
+  });
+}

package/bin/cli/daemon.ts

@@ -0,0 +1,22 @@
+export type DaemonClient = typeof import("../daemon-client.ts");
+
+export async function withDaemon<T>(
+  fn: (client: DaemonClient) => Promise<T>,
+  opts?: { message?: string; exitCode?: number }
+): Promise<T> {
+  const message = opts?.message ?? "Daemon not running. Start with: lattices app";
+  const exitCode = opts?.exitCode ?? 1;
+
+  const client = await import("../daemon-client.ts");
+  if (!(await client.isDaemonRunning())) {
+    console.error(message);
+    process.exit(exitCode);
+  }
+
+  try {
+    return await fn(client);
+  } catch (e: unknown) {
+    console.error(`Error: ${(e as Error).message}`);
+    process.exit(exitCode);
+  }
+}