@chriscode/devmux 1.0.0 → 1.3.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Server } from 'node:http';
+
 type HealthCheckType = {
     type: "port";
     port: number;
@@ -6,16 +8,39 @@ type HealthCheckType = {
     type: "http";
     url: string;
     expectStatus?: number;
-} | {
-    type: "none";
 };
+interface ErrorPatternConfig {
+    name: string;
+    regex: string;
+    severity: "info" | "warning" | "error" | "critical";
+    extractStackTrace?: boolean;
+}
+interface GlobalWatchConfig$1 {
+    enabled?: boolean;
+    outputDir?: string;
+    dedupeWindowMs?: number;
+    contextLines?: number;
+    patternSets?: Record<string, ErrorPatternConfig[]>;
+}
+interface ServiceWatchConfig$1 {
+    enabled?: boolean;
+    include?: string[];
+    exclude?: string[];
+    patterns?: ErrorPatternConfig[];
+    overrides?: Record<string, "info" | "warning" | "error" | "critical">;
+}
 interface ServiceDefinition {
     cwd: string;
     command: string;
-    health: HealthCheckType;
+    health?: HealthCheckType;
     sessionName?: string;
     env?: Record<string, string>;
     stopPorts?: number[];
+    dependsOn?: string[];
+    port?: number;
+    watch?: ServiceWatchConfig$1;
+    /** Show this service in the dashboard. Defaults to true for services with a port. */
+    dashboard?: boolean;
 }
 interface DevMuxConfig {
     version: 1;
@@ -24,19 +49,26 @@ interface DevMuxConfig {
     defaults?: {
         startupTimeoutSeconds?: number;
         remainOnExit?: boolean;
+        dashboard?: boolean | {
+            port?: number;
+        };
     };
+    watch?: GlobalWatchConfig$1;
     services: Record<string, ServiceDefinition>;
 }
 interface ResolvedConfig extends DevMuxConfig {
     configRoot: string;
     resolvedSessionPrefix: string;
+    instanceId: string;
 }
 interface ServiceStatus {
     name: string;
     healthy: boolean;
     tmuxSession: string | null;
     port?: number;
+    resolvedPort?: number;
     managedByDevmux: boolean;
+    instanceId?: string;
 }
 
 declare function loadConfig(startDir?: string): ResolvedConfig;
@@ -51,23 +83,29 @@ interface EnsureResult {
 declare function ensureService(config: ResolvedConfig, serviceName: string, options?: {
     timeout?: number;
     quiet?: boolean;
-}): Promise<EnsureResult>;
+}, _dependencyStack?: Set<string>): Promise<EnsureResult>;
 declare function getStatus(config: ResolvedConfig, serviceName: string): Promise<ServiceStatus>;
 declare function getAllStatus(config: ResolvedConfig): Promise<ServiceStatus[]>;
 declare function stopService(config: ResolvedConfig, serviceName: string, options?: {
     killPorts?: boolean;
     quiet?: boolean;
-}): void;
+}): Promise<void>;
 declare function stopAllServices(config: ResolvedConfig, options?: {
     killPorts?: boolean;
     quiet?: boolean;
-}): void;
+}): Promise<void>;
+declare function restartService(config: ResolvedConfig, serviceName: string, options?: {
+    timeout?: number;
+    killPorts?: boolean;
+    quiet?: boolean;
+}): Promise<EnsureResult>;
 declare function attachService(config: ResolvedConfig, serviceName: string): void;
 
 interface RunOptions {
     services: string[];
     stopOnExit?: boolean;
     quiet?: boolean;
+    dashboard?: boolean;
 }
 declare function runWithServices(config: ResolvedConfig, command: string[], options: RunOptions): Promise<number>;
 
@@ -93,15 +131,182 @@ declare namespace driver {
 
 declare function checkPort(port: number, host?: string): Promise<boolean>;
 declare function checkHttp(url: string, expectStatus?: number): Promise<boolean>;
-declare function checkHealth(health: HealthCheckType): Promise<boolean>;
-declare function getHealthPort(health: HealthCheckType): number | undefined;
+declare function checkTmuxPane(sessionName: string): boolean;
+declare function checkHealth(health: HealthCheckType | undefined, sessionName: string): Promise<boolean>;
+declare function getHealthPort(health: HealthCheckType | undefined): number | undefined;
 
 declare const checkers_checkHealth: typeof checkHealth;
 declare const checkers_checkHttp: typeof checkHttp;
 declare const checkers_checkPort: typeof checkPort;
+declare const checkers_checkTmuxPane: typeof checkTmuxPane;
 declare const checkers_getHealthPort: typeof getHealthPort;
 declare namespace checkers {
-  export { checkers_checkHealth as checkHealth, checkers_checkHttp as checkHttp, checkers_checkPort as checkPort, checkers_getHealthPort as getHealthPort };
+  export { checkers_checkHealth as checkHealth, checkers_checkHttp as checkHttp, checkers_checkPort as checkPort, checkers_checkTmuxPane as checkTmuxPane, checkers_getHealthPort as getHealthPort };
+}
+
+interface ErrorPattern {
+    name: string;
+    regex: string;
+    severity: "info" | "warning" | "error" | "critical";
+    extractStackTrace?: boolean;
+}
+interface PatternSet {
+    [name: string]: ErrorPattern[];
+}
+interface GlobalWatchConfig {
+    enabled?: boolean;
+    outputDir?: string;
+    dedupeWindowMs?: number;
+    contextLines?: number;
+    patternSets?: PatternSet;
+}
+interface ServiceWatchConfig {
+    enabled?: boolean;
+    include?: string[];
+    exclude?: string[];
+    patterns?: ErrorPattern[];
+    overrides?: Record<string, "info" | "warning" | "error" | "critical">;
+}
+interface TriggerEvent {
+    id: string;
+    timestamp: string;
+    source: string;
+    service: string;
+    project: string;
+    severity: "info" | "warning" | "error" | "critical";
+    pattern: string;
+    rawContent: string;
+    context: string[];
+    stackTrace?: string[];
+    status: "pending";
+    contentHash: string;
+    firstSeen: string;
+}
+interface ServiceWatchState {
+    service: string;
+    sessionName: string;
+    pipeActive: boolean;
+    startedAt?: string;
+    lastError?: string;
+}
+interface WatcherOptions {
+    service: string;
+    project: string;
+    sessionName: string;
+    outputDir: string;
+    patterns: ErrorPattern[];
+    dedupeWindowMs: number;
+    contextLines: number;
+}
+interface PatternMatch {
+    pattern: ErrorPattern;
+    line: string;
+}
+
+declare const BUILTIN_PATTERN_SETS: Record<string, ErrorPattern[]>;
+declare function matchPatterns(line: string, patterns: ErrorPattern[]): PatternMatch | null;
+declare function resolvePatterns(globalConfig: GlobalWatchConfig | undefined, serviceConfig: ServiceWatchConfig | undefined): ErrorPattern[];
+declare function isStackTraceLine(line: string): boolean;
+
+declare function computeContentHash(service: string, patternName: string, content: string): string;
+interface RingBuffer<T> {
+    push(item: T): void;
+    getAll(): T[];
+    clear(): void;
+}
+declare function createRingBuffer<T>(capacity: number): RingBuffer<T>;
+declare class DedupeCache {
+    private cache;
+    private windowMs;
+    private maxSize;
+    constructor(windowMs: number, maxSize?: number);
+    isDuplicate(hash: string): boolean;
+    private cleanup;
+}
+
+declare function ensureOutputDir(outputDir?: string): string;
+declare function getQueuePath(outputDir?: string): string;
+declare function writeEvent(options: WatcherOptions, pattern: ErrorPattern, rawContent: string, context: string[], stackTrace?: string[]): TriggerEvent;
+declare function readQueue(outputDir?: string): TriggerEvent[];
+declare function getPendingEvents(outputDir?: string): TriggerEvent[];
+declare function clearQueue(outputDir?: string): void;
+declare function updateEventStatus(eventId: string, status: "pending" | "processing" | "resolved" | "dismissed", outputDir?: string): boolean;
+
+declare function startWatcher$1(options: WatcherOptions): void;
+
+declare function getWatcherStatus(config: ResolvedConfig, serviceName: string): ServiceWatchState;
+declare function getAllWatcherStatuses(config: ResolvedConfig): ServiceWatchState[];
+declare function startWatcher(config: ResolvedConfig, serviceName: string, options?: {
+    quiet?: boolean;
+}): boolean;
+declare function stopWatcher(config: ResolvedConfig, serviceName: string, options?: {
+    quiet?: boolean;
+}): boolean;
+declare function startAllWatchers(config: ResolvedConfig, options?: {
+    quiet?: boolean;
+}): void;
+declare function stopAllWatchers(config: ResolvedConfig, options?: {
+    quiet?: boolean;
+}): void;
+
+declare const index$1_BUILTIN_PATTERN_SETS: typeof BUILTIN_PATTERN_SETS;
+type index$1_DedupeCache = DedupeCache;
+declare const index$1_DedupeCache: typeof DedupeCache;
+type index$1_ErrorPattern = ErrorPattern;
+type index$1_GlobalWatchConfig = GlobalWatchConfig;
+type index$1_PatternMatch = PatternMatch;
+type index$1_PatternSet = PatternSet;
+type index$1_ServiceWatchConfig = ServiceWatchConfig;
+type index$1_ServiceWatchState = ServiceWatchState;
+type index$1_TriggerEvent = TriggerEvent;
+type index$1_WatcherOptions = WatcherOptions;
+declare const index$1_clearQueue: typeof clearQueue;
+declare const index$1_computeContentHash: typeof computeContentHash;
+declare const index$1_createRingBuffer: typeof createRingBuffer;
+declare const index$1_ensureOutputDir: typeof ensureOutputDir;
+declare const index$1_getAllWatcherStatuses: typeof getAllWatcherStatuses;
+declare const index$1_getPendingEvents: typeof getPendingEvents;
+declare const index$1_getQueuePath: typeof getQueuePath;
+declare const index$1_getWatcherStatus: typeof getWatcherStatus;
+declare const index$1_isStackTraceLine: typeof isStackTraceLine;
+declare const index$1_matchPatterns: typeof matchPatterns;
+declare const index$1_readQueue: typeof readQueue;
+declare const index$1_resolvePatterns: typeof resolvePatterns;
+declare const index$1_startAllWatchers: typeof startAllWatchers;
+declare const index$1_stopAllWatchers: typeof stopAllWatchers;
+declare const index$1_updateEventStatus: typeof updateEventStatus;
+declare const index$1_writeEvent: typeof writeEvent;
+declare namespace index$1 {
+  export { index$1_BUILTIN_PATTERN_SETS as BUILTIN_PATTERN_SETS, index$1_DedupeCache as DedupeCache, type index$1_ErrorPattern as ErrorPattern, type index$1_GlobalWatchConfig as GlobalWatchConfig, type index$1_PatternMatch as PatternMatch, type index$1_PatternSet as PatternSet, type index$1_ServiceWatchConfig as ServiceWatchConfig, type index$1_ServiceWatchState as ServiceWatchState, type index$1_TriggerEvent as TriggerEvent, type index$1_WatcherOptions as WatcherOptions, index$1_clearQueue as clearQueue, index$1_computeContentHash as computeContentHash, index$1_createRingBuffer as createRingBuffer, index$1_ensureOutputDir as ensureOutputDir, index$1_getAllWatcherStatuses as getAllWatcherStatuses, index$1_getPendingEvents as getPendingEvents, index$1_getQueuePath as getQueuePath, index$1_getWatcherStatus as getWatcherStatus, index$1_isStackTraceLine as isStackTraceLine, index$1_matchPatterns as matchPatterns, index$1_readQueue as readQueue, index$1_resolvePatterns as resolvePatterns, index$1_startAllWatchers as startAllWatchers, startWatcher as startServiceWatcher, startWatcher$1 as startWatcher, index$1_stopAllWatchers as stopAllWatchers, stopWatcher as stopServiceWatcher, index$1_updateEventStatus as updateEventStatus, index$1_writeEvent as writeEvent };
+}
+
+interface DashboardOptions {
+    port?: number;
+    open?: boolean;
+}
+declare function startDashboard(options?: DashboardOptions): Server;
+
+interface DashboardService {
+    name: string;
+    healthy: boolean;
+    port?: number;
+    resolvedPort?: number;
+    hasHealthCheck: boolean;
+}
+interface DashboardData {
+    project: string;
+    instanceId: string;
+    configPath: string;
+    dashboardPort: number;
+    services: DashboardService[];
+}
+
+type index_DashboardData = DashboardData;
+type index_DashboardOptions = DashboardOptions;
+type index_DashboardService = DashboardService;
+declare const index_startDashboard: typeof startDashboard;
+declare namespace index {
+  export { type index_DashboardData as DashboardData, type index_DashboardOptions as DashboardOptions, type index_DashboardService as DashboardService, index_startDashboard as startDashboard };
 }
 
-export { type DevMuxConfig, type EnsureResult, type HealthCheckType, type ResolvedConfig, type RunOptions, type ServiceDefinition, type ServiceStatus, attachService, discoverFromTurbo, ensureService, formatDiscoveredConfig, getAllStatus, getServiceCwd, getSessionName, getStatus, checkers as health, loadConfig, runWithServices, stopAllServices, stopService, driver as tmux };
+export { type DevMuxConfig, type EnsureResult, type HealthCheckType, type ResolvedConfig, type RunOptions, type ServiceDefinition, type ServiceStatus, attachService, index as dashboard, discoverFromTurbo, ensureService, formatDiscoveredConfig, getAllStatus, getServiceCwd, getSessionName, getStatus, checkers as health, loadConfig, restartService, runWithServices, stopAllServices, stopService, driver as tmux, index$1 as watch };

package/dist/index.js

@@ -1,21 +1,38 @@
+import {
+  discoverFromTurbo,
+  formatDiscoveredConfig,
+  runWithServices,
+  watch_exports
+} from "./chunk-6EU6ODXX.js";
+import "./chunk-32R7KDZB.js";
+import {
+  dashboard_exports
+} from "./chunk-T6I3CPOV.js";
 import {
   attachService,
   checkers_exports,
-  discoverFromTurbo,
   driver_exports,
   ensureService,
-  formatDiscoveredConfig,
   getAllStatus,
   getServiceCwd,
   getSessionName,
   getStatus,
+  init_loader,
   loadConfig,
-  runWithServices,
+  restartService,
   stopAllServices,
   stopService
-} from "./chunk-7JJYYMUP.js";
+} from "./chunk-ALENFKSX.js";
+import {
+  init_esm_shims
+} from "./chunk-66UOCF5R.js";
+
+// src/index.ts
+init_esm_shims();
+init_loader();
 export {
   attachService,
+  dashboard_exports as dashboard,
   discoverFromTurbo,
   ensureService,
   formatDiscoveredConfig,
@@ -25,8 +42,10 @@ export {
   getStatus,
   checkers_exports as health,
   loadConfig,
+  restartService,
   runWithServices,
   stopAllServices,
   stopService,
-  driver_exports as tmux
+  driver_exports as tmux,
+  watch_exports as watch
 };

package/dist/server-manager-6EZWZK56.js

@@ -0,0 +1,106 @@
+import {
+  init_esm_shims
+} from "./chunk-66UOCF5R.js";
+
+// src/telemetry/server-manager.ts
+init_esm_shims();
+import { spawn } from "child_process";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "fs";
+import { join } from "path";
+var PID_FILE = join(process.env.HOME ?? "~", ".opencode", "telemetry-server.pid");
+var DEFAULT_PORT = 9876;
+var DEFAULT_HOST = "0.0.0.0";
+function getPid() {
+  if (!existsSync(PID_FILE)) return null;
+  try {
+    const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+    if (isNaN(pid)) return null;
+    try {
+      process.kill(pid, 0);
+      return pid;
+    } catch {
+      unlinkSync(PID_FILE);
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}
+function savePid(pid) {
+  const dir = join(process.env.HOME ?? "~", ".opencode");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(PID_FILE, String(pid));
+}
+function clearPid() {
+  if (existsSync(PID_FILE)) {
+    unlinkSync(PID_FILE);
+  }
+}
+function getServerStatus() {
+  const pid = getPid();
+  if (!pid) {
+    return { running: false };
+  }
+  return {
+    running: true,
+    pid,
+    port: DEFAULT_PORT,
+    host: DEFAULT_HOST
+  };
+}
+function startServer(options = {}) {
+  const existingPid = getPid();
+  if (existingPid) {
+    console.log(`Telemetry server already running (PID: ${existingPid})`);
+    return false;
+  }
+  const port = options.port ?? DEFAULT_PORT;
+  const host = options.host ?? DEFAULT_HOST;
+  try {
+    const child = spawn("devmux-telemetry-server", ["start", "--port", String(port), "--host", host], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    if (child.pid) {
+      savePid(child.pid);
+      child.unref();
+      console.log(`Telemetry server started (PID: ${child.pid})`);
+      console.log(`Listening on ws://${host}:${port}`);
+      return true;
+    }
+    return false;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      console.error("devmux-telemetry-server not found.");
+      console.error("Install it with: pnpm add -g @chriscode/devmux-telemetry-server");
+      console.error("Or add it to your project: pnpm add -D @chriscode/devmux-telemetry-server");
+    } else {
+      console.error("Failed to start server:", error);
+    }
+    return false;
+  }
+}
+function stopServer() {
+  const pid = getPid();
+  if (!pid) {
+    console.log("Telemetry server is not running");
+    return false;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    clearPid();
+    console.log(`Telemetry server stopped (PID: ${pid})`);
+    return true;
+  } catch (error) {
+    clearPid();
+    console.error("Failed to stop server:", error);
+    return false;
+  }
+}
+export {
+  getServerStatus,
+  startServer,
+  stopServer
+};

package/dist/skill/SKILL.md

@@ -0,0 +1,118 @@
+# DevMux Skill
+
+> **Skill for AI Agents**: Managing persistent development environments via `devmux`.
+
+## Context
+
+You are working in a `devmux`-enabled repository. This means:
+1. **Shared Awareness**: Human developers and AI agents share the same running servers.
+2. **Persistence**: Servers run in background `tmux` sessions, surviving your session.
+3. **Safety**: You must NOT kill services randomly. You must reuse existing ones.
+4. **Error Watching**: Errors can be automatically captured from service logs for investigation.
+
+## Commands (The "DevMux API")
+
+### Service Management
+
+| Goal | Command | Behavior |
+|------|---------|----------|
+| **Start a service** | `devmux ensure <name>` | **Idempotent**. Starts if stopped. Does nothing if healthy. |
+| **Check status** | `devmux status` | Lists all services, ports, and health status. |
+| **Read logs** | `devmux attach <name>` | Shows live logs (Press `Ctrl+B, D` to detach). |
+| **Stop service** | `devmux stop <name>` | **Only if necessary**. Prefer leaving running. |
+
+### Error Watching
+
+| Goal | Command | Behavior |
+|------|---------|----------|
+| **Start watching** | `devmux watch start <name>` | Monitors logs for errors. Captures to queue. |
+| **Stop watching** | `devmux watch stop <name>` | Stops monitoring. |
+| **Check watchers** | `devmux watch status` | Shows which services are being watched. |
+| **View errors** | `devmux watch queue` | Shows pending errors waiting for investigation. |
+| **Clear queue** | `devmux watch queue --clear` | Clears all captured errors. |
+
+## Rules of Engagement (CRITICAL)
+
+### 1. The "Check First" Rule
+**Before** running `pnpm dev` or `npm start`, you MUST check if it's managed by devmux:
+```bash
+devmux status
+```
+* If listed: **USE DEVMUX**. Run `devmux ensure <name>`.
+* If not listed: Run normally.
+
+### 2. The "Idempotency" Rule
+**NEVER** check "is it running?" manually. Just run:
+```bash
+devmux ensure api
+```
+* If it's running: It returns "✅ api already running" (Instant).
+* If it's stopped: It starts it and **waits for health checks** (Port open).
+* **Trust the `ensure` command.**
+
+### 3. The "Dependency" Rule
+Services have dependencies. `web` might need `api`.
+* **Old Way**: "Start API, wait 10s, Start Web."
+* **DevMux Way**: `devmux ensure web`. (It handles the graph and health checks automatically).
+
+### 4. The "Error Queue" Rule
+If errors are detected from services, check the queue:
+```bash
+devmux watch queue
+```
+* Errors are automatically captured with context (surrounding log lines).
+* Stack traces are extracted when possible.
+* Duplicate errors are deduplicated.
+
+### 5. The "Logs" Rule
+If a service fails, **DO NOT** try to run it manually to see errors.
+1. `devmux ensure <name>` (It captures startup errors).
+2. `devmux attach <name>` (View full session logs).
+3. `devmux watch queue` (View captured errors if watching is enabled).
+
+## Session Naming
+
+Sessions follow the pattern: `omo-{project}-{service}`.
+* Example: `omo-waypoint-api`
+* You can use standard `tmux` commands if needed: `tmux capture-pane -t omo-waypoint-api -p`
+
+## Error Queue Format
+
+Errors in the queue include:
+- **Service**: Which service produced the error
+- **Pattern**: What type of error was detected (js-error, type-error, fatal, etc.)
+- **Severity**: info, warning, error, or critical
+- **Context**: Lines before the error for debugging
+- **Stack trace**: Extracted if available
+
+## Built-in Pattern Sets
+
+Pattern sets are **opt-in** via `include` in the service watch config:
+
+| Set | Use for |
+|-----|---------|
+| `node` | Node.js/JavaScript (errors, types, OOM) |
+| `web` | HTTP APIs (5xx, 4xx errors) |
+| `react` | React apps (component errors) |
+| `nextjs` | Next.js (webpack, hydration) |
+| `database` | DB connections (refused, deadlock) |
+| `fatal` | System crashes (PANIC, SIGSEGV) |
+| `python` | Python (exceptions, tracebacks) |
+
+Example config:
+```json
+{
+  "watch": { "include": ["node", "web"] }
+}
+```
+
+## Verification
+
+After starting a service, `devmux` guarantees it is **healthy** (port is listening). You do NOT need to write a loop to check `curl localhost:port`. `devmux ensure` does not return until the service is ready.
+
+## Setup & Configuration
+
+If the user asks to set up DevMux or configure a new project, read the guide at:
+`references/SETUP.md`
+
+It explains how to correctly configure `devmux.config.json` and `package.json`.

package/dist/skill/references/SETUP.md

@@ -0,0 +1,109 @@
+# How to Set Up DevMux
+
+> **Guide for AI Agents & Humans**: The proper way to configure a repository for DevMux.
+
+## 0. Install DevMux
+
+```bash
+pnpm add -D @chriscode/devmux
+```
+
+### Make `devmux` Available on PATH (Recommended)
+
+By default, `devmux` requires `npx devmux` or `pnpm exec devmux`. To use `devmux` directly, add `node_modules/.bin` to your PATH using [direnv](https://direnv.net/).
+
+**One-time setup** (if you don't have direnv):
+```bash
+brew install direnv
+# Add to ~/.zshrc or ~/.bashrc:
+eval "$(direnv hook zsh)"  # or bash
+```
+
+**Per-project setup**:
+```bash
+# In your project root, create .envrc:
+echo 'PATH_add node_modules/.bin' > .envrc
+direnv allow
+```
+
+Now `devmux` works directly:
+```bash
+devmux status      # Instead of: npx devmux status
+devmux ensure api  # Instead of: pnpm exec devmux ensure api
+```
+
+> **Note**: This also makes all other local binaries available (eslint, tsc, etc.)
+
+## 1. Goal
+We want **every** persistent task (servers, watchers) to be managed by DevMux.
+*   ✅ `pnpm dev` -> `devmux ensure web`
+*   ✅ `pnpm ios` -> `devmux ensure ios`
+*   ❌ `pnpm dev` -> `next dev` (Foreground process that blocks the agent)
+
+## 2. Configuration (`devmux.config.json`)
+
+Use the discovery tool to bootstrap:
+```bash
+devmux discover turbo > devmux.config.json
+```
+
+Then edit it to ensure:
+1.  **Health Checks**: Every service needs a port or HTTP check.
+2.  **Dependencies**: Use `dependsOn` to enforce startup order.
+
+Example:
+```json
+{
+  "services": {
+    "api": {
+      "command": "pnpm start:api",
+      "health": { "type": "port", "port": 3000 }
+    },
+    "web": {
+      "command": "pnpm start:web",
+      "dependsOn": ["api"],
+      "health": { "type": "port", "port": 8080 }
+    }
+  }
+}
+```
+
+## 3. Package.json Scripts (The "DevMux Everywhere" Pattern)
+
+Update your root `package.json` so that standard commands use DevMux. This ensures both humans and agents use the safe path.
+
+**Before:**
+```json
+"scripts": {
+  "dev": "turbo dev",
+  "api": "cd api && pnpm dev"
+}
+```
+
+**After (Recommended):**
+```json
+"scripts": {
+  "svc:status": "devmux status",
+  "svc:stop": "devmux stop all",
+  
+  "dev": "devmux ensure web",
+  "dev:api": "devmux ensure api",
+  
+  "// Note": "Use devmux run for one-off commands that need services",
+  "test:e2e": "devmux run --with web -- pnpm playwright test"
+}
+```
+
+## 4. Verification
+
+1.  Run `pnpm dev` (or equivalent).
+2.  It should start services in tmux.
+3.  Run `devmux status` to confirm.
+4.  Ctrl+C should stop them (if running in foreground wrapper) or leave them (if using ensure).
+
+## 5. Agent Instructions
+
+Ensure the project has an `AGENTS.md` (or similar) that tells the agent to use `devmux`. You can generate the latest instructions via:
+```bash
+devmux skill
+```

package/dist/watch/watcher-cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node