@lattices/cli 0.4.2 → 0.4.6

package/bin/lattices-app.ts

@@ -22,6 +22,7 @@ const REPO = "arach/lattices";
 const RELEASE_APP_ASSET_NAMES = ["Lattices.dmg"];
 const RELEASE_BINARY_ASSET_NAMES = ["Lattices-macos-arm64", "LatticeApp-macos-arm64"];
 type ReleaseAsset = { name: string; browser_download_url: string };
+const selfScriptPath = resolve(__dirname, "lattices-app.ts");
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
@@ -79,6 +80,14 @@ function launch(extraArgs: string[] = []): void {
   console.log("lattices app launched.");
 }
 
+function relaunchIfNeeded(shouldLaunch: boolean, extraArgs: string[] = []): void {
+  if (!shouldLaunch) {
+    console.log("App updated. Launch with: lattices app");
+    return;
+  }
+  launch(extraArgs);
+}
+
 function resolveSigningIdentity(): string | null {
   try {
     const identities = execSync("security find-identity -v -p codesigning", { stdio: "pipe" }).toString();
@@ -93,6 +102,11 @@ function resolveSigningIdentity(): string | null {
 function signBundle(): void {
   const identity = resolveSigningIdentity();
   const entFlag = existsSync(entitlementsPath) ? ` --entitlements '${entitlementsPath}'` : "";
+  const tempBinaryPath = `${binaryPath}.cstemp`;
+
+  try {
+    if (existsSync(tempBinaryPath)) rmSync(tempBinaryPath, { force: true });
+  } catch {}
 
   if (identity) {
     console.log(`Signing with: ${identity}`);
@@ -113,6 +127,10 @@ function signBundle(): void {
     `codesign --force --sign -${entFlag} --identifier com.arach.lattices '${bundlePath}'`,
     { stdio: "pipe" }
   );
+
+  try {
+    if (existsSync(tempBinaryPath)) rmSync(tempBinaryPath, { force: true });
+  } catch {}
 }
 
 function writeInfoPlist(): void {
@@ -304,11 +322,48 @@ async function ensureBinary(): Promise<void> {
   process.exit(1);
 }
 
+function spawnDetachedUpdateWorker(extraArgs: string[] = [], shouldLaunch = false): void {
+  const workerArgs = [
+    selfScriptPath,
+    "update",
+    "--worker",
+    ...(shouldLaunch ? ["--launch"] : []),
+    ...extraArgs,
+  ];
+  const child = spawn(process.execPath, workerArgs, {
+    cwd: cliRoot,
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+async function updateApp(extraArgs: string[] = [], shouldLaunch = false): Promise<void> {
+  const wasRunning = isRunning();
+  if (wasRunning) {
+    quit();
+  }
+
+  const downloaded = await download();
+  if (!downloaded) {
+    console.error("Update failed.");
+    if (wasRunning || shouldLaunch || extraArgs.length > 0) {
+      launch(extraArgs);
+    }
+    process.exit(1);
+  }
+
+  relaunchIfNeeded(shouldLaunch || wasRunning || extraArgs.length > 0, extraArgs);
+}
+
 const cmd = process.argv[2];
 const flags = process.argv.slice(3);
 const launchFlags: string[] = [];
 if (flags.includes("--diagnostics") || flags.includes("-d")) launchFlags.push("--diagnostics");
 if (flags.includes("--screen-map") || flags.includes("-m")) launchFlags.push("--screen-map");
+const shouldLaunchAfterUpdate = flags.includes("--launch") || launchFlags.length > 0;
+const shouldDetachUpdate = flags.includes("--detach");
+const isUpdateWorker = flags.includes("--worker");
 
 if (cmd === "build") {
   if (!hasSwift()) {
@@ -334,6 +389,13 @@ if (cmd === "build") {
     process.exit(1);
   }
   launch(launchFlags);
+} else if (cmd === "update") {
+  if (shouldDetachUpdate && !isUpdateWorker) {
+    spawnDetachedUpdateWorker(launchFlags, shouldLaunchAfterUpdate);
+    console.log("lattices app update started.");
+  } else {
+    await updateApp(launchFlags, shouldLaunchAfterUpdate);
+  }
 } else {
   await ensureBinary();
   launch(launchFlags);

package/bin/lattices-dev

@@ -34,6 +34,8 @@ sign_bundle() {
     local identity sign_status=0
     local -a ent_flags=()
 
+    rm -f "$BUNDLE_BIN".cstemp
+
     if [ -f "$ENTITLEMENTS" ]; then
         ent_flags=(--entitlements "$ENTITLEMENTS")
     fi
@@ -53,6 +55,8 @@ sign_bundle() {
         dim "No usable signing identity found. Using ad-hoc signature."
         codesign --force --sign - "${ent_flags[@]}" --identifier com.arach.lattices "$BUNDLE"
     fi
+
+    rm -f "$BUNDLE_BIN".cstemp
 }
 
 write_info_plist() {

package/bin/lattices.ts

@@ -47,7 +47,7 @@ function hasTmux(): boolean {
 const tmuxRequiredCommands = new Set([
   "init", "ls", "list", "kill", "rm", "sync", "reconcile",
   "restart", "respawn", "group", "groups", "tab", "status",
-  "inventory", "distribute", "sessions",
+  "inventory", "sessions",
 ]);
 
 function requireTmux(command: string | undefined): void {
@@ -56,7 +56,8 @@ function requireTmux(command: string | undefined): void {
   const isImplicitCreate = command && !tmuxRequiredCommands.has(command)
     && !["search", "s", "focus", "place", "tile", "t", "windows", "window",
          "voice", "call", "layer", "layers", "diag", "diagnostics", "scan",
-         "ocr", "daemon", "dev", "app", "mouse", "help", "-h", "--help"].includes(command);
+         "ocr", "daemon", "dev", "app", "mouse", "assistant",
+         "help", "-h", "--help"].includes(command);
 
   if (command && !tmuxRequiredCommands.has(command) && !isImplicitCreate) return;
 
@@ -1182,6 +1183,34 @@ async function voiceCommand(subcommand?: string, ...rest: string[]): Promise<voi
   }
 }
 
+async function assistantCommand(subcommand?: string, ...rest: string[]): Promise<void> {
+  if (subcommand !== "plan") {
+    console.log("Usage: lattices assistant plan <text> [--json]");
+    return;
+  }
+
+  const jsonOut = rest.includes("--json");
+  const text = rest.filter((arg) => arg !== "--json").join(" ").trim();
+  if (!text) {
+    console.log("Usage: lattices assistant plan <text> [--json]");
+    return;
+  }
+
+  const { tryLocalAssistantPlan } = await import("./assistant-intelligence.ts");
+  const result = tryLocalAssistantPlan(text) ?? {
+    actions: [],
+    spoken: "No local TS plan matched.",
+    _meta: { source: "local-rule", matched: false },
+  };
+
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(result.spoken);
+}
+
 async function callCommand(method?: string, ...rest: string[]): Promise<void> {
   if (!method) {
     console.log("Usage: lattices call <method> [params-json]");
@@ -1401,14 +1430,14 @@ async function diagCommand(limit?: string): Promise<void> {
   }
 }
 
-async function distributeCommand(): Promise<void> {
-  try {
-    const { daemonCall } = await getDaemonClient();
-    await daemonCall("space.optimize", { scope: "visible", strategy: "balanced" });
-    console.log("Distributed visible windows into grid");
-  } catch {
-    console.log("Daemon not running. Start with: lattices app");
-  }
+async function distributeCommand(rawArgs: string[] = []): Promise<void> {
+  const request = parseSpaceOptimizeArgs(rawArgs, "visible");
+  await optimizeWindowsCommand(request, "Distributed");
+}
+
+async function tileFamilyCommand(rawArgs: string[]): Promise<void> {
+  const request = parseSpaceOptimizeArgs(rawArgs, "active-app");
+  await optimizeWindowsCommand(request, "Smart-tiled");
 }
 
 async function daemonLsCommand(): Promise<boolean> {
@@ -1711,7 +1740,8 @@ Usage:
   lattices windows [--json]   List all desktop windows (daemon required)
   lattices sessions [--json]  List active tmux sessions via daemon
   lattices tile <position>    Tile the frontmost window (left, right, top, etc.)
-  lattices distribute         Smart-grid all visible windows (daemon required)
+  lattices tile family [app] [region]  Smart-grid the frontmost app family, or a named app
+  lattices distribute [app] [region]   Smart-grid visible windows or just one app (daemon required)
   lattices layer [name|index]  List layers or switch by name/index (daemon required)
   lattices layer create <name> [wid:N ...] [--json '<specs>']  Create a session layer
   lattices layer snap [name]   Snapshot visible windows into a session layer
@@ -1721,6 +1751,7 @@ Usage:
   lattices voice status       Voice provider status
   lattices voice simulate <t> Parse and execute a voice command
   lattices voice intents      List all available intents
+  lattices assistant plan <t> Preview the TS assistant planner
   lattices call <method> [p]  Raw daemon API call (params as JSON)
   lattices scan               Show text from all visible windows
   lattices scan --full        Full text dump
@@ -1737,6 +1768,7 @@ Usage:
   lattices daemon status      Show daemon status
   lattices diag [limit]       Show diagnostic log entries
   lattices app                Launch the menu bar companion app
+  lattices app update         Download the latest menu bar app and relaunch
   lattices app build          Rebuild the menu bar app
   lattices app restart        Rebuild and relaunch the menu bar app
   lattices app quit           Stop the menu bar app
@@ -1901,6 +1933,69 @@ const tilePresets: Record<string, (s: ScreenBounds) => number[]> = {
   "right-third":  (s) => [s.x + Math.round(s.w * 0.667), s.y, s.x + s.w, s.y + s.h],
 };
 
+type SpaceOptimizeScope = "visible" | "active-app" | "app";
+
+interface SpaceOptimizeRequest {
+  scope: SpaceOptimizeScope;
+  app?: string;
+  region?: string;
+}
+
+function isPlacementToken(value?: string): boolean {
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized in tilePresets || /^grid:\d+x\d+:\d+,\d+$/i.test(normalized);
+}
+
+function parseSpaceOptimizeArgs(rawArgs: string[], defaultScope: SpaceOptimizeScope): SpaceOptimizeRequest {
+  const parts = rawArgs.filter(Boolean);
+  if (!parts.length) return { scope: defaultScope };
+
+  const last = parts[parts.length - 1];
+  const region = isPlacementToken(last) ? last : undefined;
+  const appParts = region ? parts.slice(0, -1) : parts;
+  const app = appParts.length ? appParts.join(" ") : undefined;
+
+  if (app) return { scope: "app", app, region };
+  return { scope: defaultScope, region };
+}
+
+function formatOptimizeTarget(request: SpaceOptimizeRequest): string {
+  if (request.app) return `"${request.app}"`;
+  return request.scope === "active-app" ? "the frontmost app" : "all visible windows";
+}
+
+async function optimizeWindowsCommand(
+  request: SpaceOptimizeRequest,
+  successVerb: string
+): Promise<void> {
+  try {
+    const { daemonCall } = await getDaemonClient();
+    const params: Record<string, unknown> = {
+      scope: request.scope,
+      strategy: "balanced",
+    };
+    if (request.app) params.app = request.app;
+    if (request.region) params.region = request.region;
+
+    const result = await daemonCall("space.optimize", params) as any;
+    const count = result?.windowCount ?? 0;
+    const target = formatOptimizeTarget(request);
+    const regionSuffix = request.region ? ` in the ${request.region} region` : "";
+
+    if (count === 0) {
+      console.log(`No eligible windows found for ${target}${regionSuffix}.`);
+      return;
+    }
+
+    console.log(
+      `${successVerb} ${count} window${count === 1 ? "" : "s"} for ${target}${regionSuffix}.`
+    );
+  } catch {
+    console.log("Daemon not running. Start with: lattices app");
+  }
+}
+
 function tileWindow(position: string): void {
   const preset = tilePresets[position];
   if (!preset) {
@@ -2098,14 +2193,27 @@ switch (command) {
     }
     break;
   case "distribute":
-    await distributeCommand();
+    await distributeCommand(args.slice(1));
     break;
   case "tile":
   case "t":
-    if (args[1]) {
+    if (args[1] === "family" || args[1] === "app") {
+      await tileFamilyCommand(args.slice(2));
+    } else if (args[1] === "all") {
+      await distributeCommand(args.slice(2));
+    } else if (args[1]) {
       tileWindow(args[1]);
     } else {
-      console.log("Usage: lattices tile <position>\n");
+      console.log("Usage:");
+      console.log("  lattices tile <position>");
+      console.log("  lattices tile family [app-name] [region]");
+      console.log("  lattices tile all [app-name] [region]\n");
+      console.log("Examples:");
+      console.log("  lattices tile left");
+      console.log("  lattices tile family");
+      console.log("  lattices tile family right");
+      console.log("  lattices tile family iTerm2");
+      console.log("  lattices tile all Google Chrome left\n");
       console.log("Positions: left, right, top, bottom, top-left, top-right,");
       console.log("           bottom-left, bottom-right, maximize, center,");
       console.log("           left-third, center-third, right-third");
@@ -2141,6 +2249,9 @@ switch (command) {
   case "voice":
     await voiceCommand(args[1], ...args.slice(2));
     break;
+  case "assistant":
+    await assistantCommand(args[1], ...args.slice(2));
+    break;
   case "call":
     await callCommand(args[1], ...args.slice(2));
     break;

package/docs/agents.md

@@ -140,3 +140,17 @@ same canonical actions:
 
 That keeps the interaction layer flexible while the executor stays
 predictable.
+
+## Assistant intelligence boundary
+
+Assistant planning lives in TypeScript where possible:
+
+- `bin/assistant-intelligence.ts` owns the intent catalog, prompt assembly,
+  local rule planner, desktop snapshot formatting, and plan normalization.
+- `bin/handsoff-worker.ts` and `bin/handsoff-infer.ts` call that module before
+  falling back to model inference.
+- Swift should remain the macOS execution layer: hotkeys, windows, AX/CG,
+  SkyLight, panels, and visual feedback.
+
+Use `lattices assistant plan <text> --json` to inspect the TS planner without
+launching the app or mutating the desktop.

package/docs/api.md

@@ -164,10 +164,65 @@ try {
 
 | Method | Type | Description |
 |--------|------|-------------|
+| `deck.manifest` | read | Shared companion deck manifest |
+| `deck.snapshot` | read | Current companion deck runtime snapshot |
+| `deck.perform` | write | Perform a companion deck action |
 | `daemon.status` | read | Health check and stats |
 | `api.schema` | read | Full API schema for self-discovery |
 | `diagnostics.list` | read | Recent diagnostic entries |
 
+#### `deck.manifest`
+
+Return the shared `DeckKit` manifest exposed by the macOS app. This is
+the contract a future Lattices companion can consume to discover pages,
+capabilities, and security mode.
+
+**Params**: none
+
+#### `deck.snapshot`
+
+Return the current `DeckKit` runtime snapshot for the macOS host.
+
+**Params**: none
+
+**Returns**: a `DeckRuntimeSnapshot` object containing:
+
+- `voice`
+- `desktop`
+- `switcher`
+- `history`
+- `questions`
+
+#### `deck.perform`
+
+Perform a `DeckKit` action against the running macOS host and return a
+`DeckActionResult`.
+
+**Params**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `pageID` | string | no | Deck page ID |
+| `actionID` | string | yes | Deck action identifier |
+| `payload` | object | no | Deck action payload |
+
+Example:
+
+```json
+{
+  "id": "1",
+  "method": "deck.perform",
+  "params": {
+    "pageID": "layout",
+    "actionID": "layout.optimize",
+    "payload": {
+      "strategy": "balanced",
+      "region": "right"
+    }
+  }
+}
+```
+
 #### `daemon.status`
 
 Health check and basic stats.

package/docs/app.md

@@ -11,6 +11,7 @@ workspace from there.
 
 ```bash
 lattices app          # Build (or download) and launch
+lattices app update   # Download the latest release and relaunch
 lattices app build    # Rebuild from source
 lattices app restart  # Quit, rebuild, relaunch
 lattices app quit     # Stop the app
@@ -73,6 +74,7 @@ Available when `layers` are configured in `~/.lattices/workspace.json`
 | Command           | Description                              |
 |-------------------|------------------------------------------|
 | Settings          | Open preferences (terminal, scan root)   |
+| Update Lattices   | Download the latest release and relaunch |
 | Diagnostics       | View logs and debug info                 |
 | Refresh Projects  | Re-scan for .lattices.json configs        |
 | Quit Lattices      | Exit the menu bar app                    |
@@ -166,6 +168,7 @@ The settings window has four tabs:
 | Terminal   | Which terminal to use (auto-detected from installed) |
 | Mode       | `learning` or `auto` (see below)                     |
 | Scan Root  | Directory to scan for .lattices.json configs (type a path or click Browse) |
+| Updates    | Download the latest release and relaunch the app     |
 
 **Mode** controls how the app handles session interaction:
 

package/docs/companion-deck.md

@@ -0,0 +1,180 @@
+# Companion Deck
+
+This document defines the first extraction boundary for the Lattices
+companion deck work.
+
+## Goals
+
+- Build the deck architecture in `lattices` first, without modifying
+  `talkie`.
+- Treat `talkie` as the donor and reference implementation, not the
+  place where the first shared abstraction is born.
+- Let `lattices` own Mac functionality.
+- Let `talkie` continue to own Talkie-specific flows.
+- Keep the transport and UI shell generic enough that both products can
+  embed the same deck later.
+
+## Product Ownership
+
+### Lattices owns
+
+- Voice agent control
+- Layout and screen state
+- Application, window, tab, and task switching
+- Session and layer switching
+- Desktop questions and agent follow-up
+- Action history and undo-oriented playback
+
+### Talkie owns
+
+- Dictation
+- Memo recording
+- Scratchpad and compose flows
+- Capture-specific flows
+- Talkie-branded deck pages and follow-up actions
+
+### Shared deck kit owns
+
+- Page model
+- Action model
+- Runtime snapshot model
+- Security mode model
+- App and task switcher model
+- History feed model
+- Generic host protocol
+
+## Security Modes
+
+The deck must support two security modes.
+
+### Standalone
+
+Used by a future standalone `Lattices Companion`.
+
+- Bonjour discovery
+- Local network only
+- No Tailscale or external relay dependency
+- QR or code-based pairing on top of the local network path
+- Per-device keypairs
+- Signed requests with nonce and timestamp protection
+- Local companion gateway with a reduced action surface
+
+### Embedded
+
+Used when the deck is embedded inside `talkie`.
+
+- Pairing, trust, transport, and signing are delegated to Talkie
+- Lattices focuses only on local functionality and state
+- The Lattices deck host does not need to own remote security in this mode
+
+## First Lattices Companion Scope
+
+The first iPad/iPhone companion for Lattices should focus on these pages:
+
+1. Voice
+2. Layout
+3. Switch
+4. History
+
+These pages cover the highest-value mobile control loops without pulling
+Talkie-specific concepts into the new product.
+
+## Module Plan
+
+### `swift/DeckKit`
+
+Cross-product contract incubated in the Lattices repo first.
+
+- Shared deck schema
+- Security mode model
+- Runtime snapshot model
+- Host protocol
+
+### `LatticesDeckHost`
+
+Mac-side adapter owned by Lattices.
+
+- Publishes deck pages and runtime state
+- Maps deck actions to the existing Lattices desktop APIs
+- Uses the existing desktop model, layout engine, switcher logic, and
+  voice agent surfaces
+
+### `Lattices Companion`
+
+Future iOS or iPadOS app that consumes `DeckKit` and the Lattices
+companion gateway.
+
+### `TalkieDeckHost`
+
+Future Talkie-side adapter that adds Talkie-only pages on top of the
+shared deck shell.
+
+## Current Lattices Milestone
+
+The first host-side integration now lives in the Lattices macOS app.
+
+- `swift/DeckKit` continues to own the shared manifest, snapshot,
+  action, and security contract.
+- `app/Sources/LatticesDeckHost.swift` is the first concrete Mac host.
+- The menu bar app daemon now exposes:
+  - `deck.manifest`
+  - `deck.snapshot`
+  - `deck.perform`
+
+That gives the future iPhone/iPad companion a stable local contract
+before transport and pairing are finalized.
+
+The current transport now runs as a local network bridge in the macOS
+app with Bonjour discovery on port `5287` (`LATS` on a phone keypad).
+Standalone mode now uses:
+
+- local Mac approval for first-time device pairing
+- per-device key agreement
+- signed requests with nonce and timestamp checks
+- encrypted deck payloads for snapshots, actions, and trackpad events
+
+The bridge still keeps `/health`, `/deck/manifest`, and pairing
+bootstrap lightweight so a new companion can connect and establish trust
+without an external relay or Tailscale dependency.
+
+## Initial Action Surface
+
+The first deck action IDs are intentionally small and map to existing
+desktop behavior:
+
+- `voice.toggle`
+- `voice.cancel`
+- `layout.activateLayer`
+- `layout.optimize`
+- `layout.placeFrontmost`
+- `switch.focusItem`
+- `history.undoLast`
+
+This keeps the first bridge focused on real Mac control loops instead
+of inventing a second execution stack.
+
+## Rollout Sequence
+
+1. Leave Talkie untouched and use it as the donor reference.
+2. Incubate `DeckKit` in `lattices`.
+3. Build a clean Lattices companion around `Voice`, `Layout`,
+   `Switch`, and `History`.
+4. Prove standalone local pairing and strong security for Lattices.
+5. Harden the deck contract.
+6. Retrofit the stabilized deck kit back into Talkie.
+
+Embedded mode remains a first-class constraint throughout the rollout.
+The standalone bridge must not leak into the shared deck contract in a
+way that would make Talkie embedding awkward later.
+
+## Vox
+
+Vox is the preferred voice dependency for the Lattices companion path.
+
+- Prefer direct embedding through `VoxCore` and `VoxEngine` for
+  in-process ASR and TTS inside Apple apps.
+- Keep `VoxBridge` available as an optional daemon-style path when a
+  shared runtime is more appropriate than direct embedding.
+- Keep the first contract in `DeckKit` voice-agnostic.
+- Let `LatticesDeckHost` decide whether voice is served by embedded Vox
+  or another local service surface.