claws-code 0.8.0

package/extension/package.json

@@ -0,0 +1,343 @@
+{
+  "name": "claws",
+  "displayName": "Claws: Programmable Terminal Bridge",
+  "description": "Turn every VS Code terminal into a programmable endpoint. List, create, send, execute, read, and close terminals from any external process via a local socket.",
+  "version": "0.8.0",
+  "publisher": "neunaha",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neunaha/claws"
+  },
+  "bugs": {
+    "url": "https://github.com/neunaha/claws/issues"
+  },
+  "homepage": "https://github.com/neunaha/claws#readme",
+  "icon": "icon.png",
+  "engines": {
+    "vscode": "^1.93.0"
+  },
+  "galleryBanner": {
+    "color": "#111318",
+    "theme": "dark"
+  },
+  "categories": [
+    "Other",
+    "AI",
+    "Machine Learning"
+  ],
+  "keywords": [
+    "terminal",
+    "automation",
+    "orchestration",
+    "ai",
+    "pair-programming",
+    "remote-control",
+    "bridge",
+    "socket",
+    "claude-code",
+    "mcp",
+    "wave-army",
+    "workers"
+  ],
+  "main": "./dist/extension.js",
+  "activationEvents": [
+    "onStartupFinished",
+    "onCommand:claws.healthCheck",
+    "onCommand:claws.showLog",
+    "onCommand:claws.status",
+    "onCommand:claws.statusBar",
+    "onCommand:claws.listTerminals",
+    "onCommand:claws.rebuildPty",
+    "onCommand:claws.uninstallCleanup"
+  ],
+  "scripts": {
+    "schemas": "node ../scripts/codegen/index.mjs",
+    "compile": "npm run schemas && tsc --noEmit && node esbuild.mjs",
+    "build": "npm run schemas && node esbuild.mjs --production && node scripts/bundle-native.mjs",
+    "bundle-native": "node scripts/bundle-native.mjs",
+    "watch": "node esbuild.mjs --watch",
+    "deploy:dev": "npm run build && node scripts/deploy-dev.mjs",
+    "install:vsix": "bash ../scripts/dev-vsix-install.sh",
+    "typecheck": "tsc --noEmit",
+    "test:smoke": "node test/smoke.test.js",
+    "test:native": "node test/native-bundle.test.js",
+    "test:config": "node test/config-reload.test.js",
+    "test:capture-store": "node test/capture-store-trim.test.js",
+    "test:oversized": "node test/oversized-line.test.js",
+    "test:pty-lifecycle": "node test/pty-lifecycle.test.js",
+    "test:profile": "node test/profile-provider.test.js",
+    "test:multiconn": "node test/multi-connection.test.js",
+    "test:v2-hello": "node test/claws-v2-hello.test.js",
+    "test:v2-pubsub": "node test/claws-v2-pubsub.test.js",
+    "test:v2-tasks": "node test/claws-v2-tasks.test.js",
+    "test:v2-correlation-events": "node test/claws-v2-correlation-events.test.js",
+    "test:lifecycle-store": "node test/lifecycle-store.test.js",
+    "test:lifecycle-server": "node test/lifecycle-server.test.js",
+    "test:schemas": "node test/event-schemas.test.js",
+    "test:topic-registry": "node test/topic-registry.test.js",
+    "test:server-validation": "node test/server-validation.test.js",
+    "test:mcp-codegen": "node test/mcp-tools-codegen.test.js",
+    "test:sdk": "node test/sdk-cli.test.js",
+    "test:reverse-channel": "node test/reverse-channel.test.js",
+    "test:event-log": "node test/event-log.test.js",
+    "test:mcp-publish-flow": "node test/mcp-publish-flow.test.js",
+    "test:json-safe": "node test/json-safe.test.js",
+    "test:atomic-file": "node test/atomic-file.test.js",
+    "test:update-socket-probe": "node test/update-socket-probe.test.js",
+    "test:install-cleanup-race": "bash test/install-cleanup-race.test.sh",
+    "test:fix-rebuild-timeout": "bash test/fix-rebuild-timeout.test.sh",
+    "test:fix-editor-detect": "bash test/fix-editor-detect.test.sh",
+    "test:install-arch-verify": "bash test/install-arch-verify.test.sh",
+    "test:update-step6-editor": "bash test/update-step6-editor.test.sh",
+    "test:sdk-socket-timeout": "node test/sdk-socket-timeout.test.js",
+    "test:install-awk-anchor": "bash test/install-awk-anchor.test.sh",
+    "test:install-mcp-merge": "bash test/install-mcp-merge.test.sh",
+    "test:install-hooks-atomic": "bash test/install-hooks-atomic.test.sh",
+    "test:install-awk-empty": "bash test/install-awk-empty.test.sh",
+    "test:inject-claude-md-atomic": "node test/inject-claude-md-atomic.test.js",
+    "test:hooks-lifecycle-state-atomic": "node test/hooks-lifecycle-state-atomic.test.js",
+    "test:uninstall-cleanup-atomic": "node test/uninstall-cleanup-atomic.test.js",
+    "test:install-error-path": "bash test/install-error-path.test.sh",
+    "test:bundle-native-copy-atomic": "node test/bundle-native-copy-atomic.test.js",
+    "test:inject-settings-safe-merge": "node test/inject-settings-safe-merge.test.js",
+    "test:hook-misfire-log": "node test/hook-misfire-log.test.js",
+    "test:hook-cmd-explicit-if": "node test/hook-cmd-explicit-if.test.js",
+    "test:hook-stdin-safety": "node test/hook-stdin-safety.test.js",
+    "test:inject-settings-dedup": "node test/inject-settings-dedup.test.js",
+    "test:hookCmd-canonical-fast-path": "node test/hookCmd-canonical-fast-path.test.js",
+    "test:hook-strict-deny-newline": "node test/hook-strict-deny-newline.test.js",
+    "test:hook-debug-visibility": "node test/hook-debug-visibility.test.js",
+    "test:pre-tool-use-sidecar-recognized": "node test/pre-tool-use-sidecar-recognized.test.js",
+    "test:update-step6-timeout": "bash test/update-step6-timeout.test.sh",
+    "test:update-step6-orphan": "bash test/update-step6-orphan.test.sh",
+    "test:update-claws-log": "bash test/update-claws-log.test.sh",
+    "test:update-probe-path-quoting": "bash test/update-probe-path-quoting.test.sh",
+    "test:update-git-pull-fail": "bash test/update-git-pull-fail.test.sh",
+    "test:update-atomic-hooks": "bash test/update-atomic-hooks.test.sh",
+    "test:extension-rebuild-pty-timeout": "node test/extension-rebuild-pty-timeout.test.js",
+    "test:extension-plutil-timeout": "node test/extension-plutil-timeout.test.js",
+    "test:lifecycle-store-fsync": "node test/lifecycle-store-fsync.test.js",
+    "test:inject-settings-exclusive-lock": "node test/inject-settings-exclusive-lock.test.js",
+    "test:fix-mcp-handshake": "bash test/fix-mcp-handshake.test.sh",
+    "test:fix-mcp-repair": "bash test/fix-mcp-repair.test.sh",
+    "test:update-mcp-path-quoting": "bash test/update-mcp-path-quoting.test.sh",
+    "test:mcp-pconn-timeout": "node test/mcp-pconn-timeout.test.js",
+    "test:vehicle-state": "node test/claws-v2-vehicle-state.test.js",
+    "test:event-log-replay": "node test/claws-event-log-replay.test.js",
+    "test:event-log-retention": "node test/claws-event-log-retention.test.js",
+    "test:auth": "node test/claws-auth.test.js",
+    "test:ws-transport": "node test/claws-ws-transport.test.js",
+    "test:inject-dev-hooks": "node --test test/inject-dev-hooks.test.js",
+    "test:fix-malformed-settings": "bash test/fix-malformed-settings.test.sh",
+    "test:fix-multiple-ext-dirs": "bash test/fix-multiple-ext-dirs.test.sh",
+    "test:fix-claws-bin-integrity": "bash test/fix-claws-bin-integrity.test.sh",
+    "test:fix-shell-hook-sourcing": "bash test/fix-shell-hook-sourcing.test.sh",
+    "test:install-claws-bin-symlink-guard": "bash test/install-claws-bin-symlink-guard.test.sh",
+    "test:install-claws-dir-export": "bash test/install-claws-dir-export.test.sh",
+    "test:fix-mcp-recovery": "bash test/fix-mcp-recovery.test.sh",
+    "test:fix-pipe-mode-probe": "bash test/fix-pipe-mode-probe.test.sh",
+    "test:install-p3-hygiene": "bash test/install-p3-hygiene.test.sh",
+    "test:install-vsix-extraction-poll": "bash test/install-vsix-extraction-poll.test.sh",
+    "test:update-dry-run": "bash test/update-dry-run.test.sh",
+    "test:dev-hooks-path-canonical": "bash test/dev-hooks-path-canonical.test.sh",
+    "test:worker-fixes-v079": "node test/worker-fixes-v079.test.js",
+    "test:version-drift": "node test/version-drift.test.js",
+    "test:ondidclose-publish": "node test/onDidCloseTerminal-publish.test.js",
+    "test:terminal-manager": "node test/terminal-manager.test.js",
+    "test:worker-boot-paste-collapse": "node test/worker-boot-paste-collapse.test.js",
+    "test:install-sweep": "bash test/install-sweep.test.sh",
+    "test:monitor-rearm": "node test/monitor-rearm.test.js",
+    "test:monitor-arm-watch": "node test/monitor-arm-watch.test.js",
+    "test:monitor-corr-arm": "node test/monitor-corr-arm.test.js",
+    "test:terminal-alive": "node test/claws-terminal-alive.test.js",
+    "test:pty-windows-shell": "node test/pty-windows-shell.test.js",
+    "test:named-pipe-server": "node test/named-pipe-server.test.js",
+    "test:conpty-marker-scan": "node test/conpty-marker-scan.test.js",
+    "test:claws-windows-paths": "node test/claws-windows-paths.test.js",
+    "test:paste-gate": "node test/paste-gate.test.js",
+    "test:mac-event-driven-boot": "node test/mac-event-driven-boot.test.js",
+    "test": "npm run typecheck && npm run build && npm run test:smoke && npm run test:native && npm run test:config && npm run test:capture-store && npm run test:oversized && npm run test:pty-lifecycle && npm run test:profile && npm run test:multiconn && npm run test:v2-hello && npm run test:v2-pubsub && npm run test:v2-tasks && npm run test:v2-correlation-events && npm run test:lifecycle-store && npm run test:lifecycle-server && npm run test:schemas && npm run test:topic-registry && npm run test:server-validation && npm run test:mcp-codegen && npm run test:sdk && npm run test:reverse-channel && npm run test:event-log && npm run test:mcp-publish-flow && npm run test:json-safe && npm run test:atomic-file && npm run test:update-socket-probe && npm run test:install-cleanup-race && npm run test:fix-rebuild-timeout && npm run test:fix-editor-detect && npm run test:install-arch-verify && npm run test:update-step6-editor && npm run test:sdk-socket-timeout && npm run test:install-awk-anchor && npm run test:install-mcp-merge && npm run test:install-hooks-atomic && npm run test:install-awk-empty && npm run test:inject-claude-md-atomic && npm run test:hooks-lifecycle-state-atomic && npm run test:uninstall-cleanup-atomic && npm run test:install-error-path && npm run test:bundle-native-copy-atomic && npm run test:inject-settings-safe-merge && npm run test:hook-misfire-log && npm run test:hook-cmd-explicit-if && npm run test:hook-stdin-safety && npm run test:inject-settings-dedup && npm run test:hookCmd-canonical-fast-path && npm run test:hook-strict-deny-newline && npm run test:hook-debug-visibility && npm run test:update-step6-timeout && npm run test:update-step6-orphan && npm run test:update-claws-log && npm run test:update-probe-path-quoting && npm run test:update-git-pull-fail && npm run test:update-atomic-hooks && npm run test:extension-rebuild-pty-timeout && npm run test:extension-plutil-timeout && npm run test:lifecycle-store-fsync && npm run test:inject-settings-exclusive-lock && npm run test:fix-mcp-handshake && npm run test:fix-mcp-repair && npm run test:update-mcp-path-quoting && npm run test:mcp-pconn-timeout && npm run test:vehicle-state && npm run test:event-log-replay && npm run test:event-log-retention && npm run test:auth && npm run test:ws-transport && npm run test:inject-dev-hooks && npm run test:fix-malformed-settings && npm run test:fix-multiple-ext-dirs && npm run test:fix-claws-bin-integrity && npm run test:fix-shell-hook-sourcing && npm run test:install-claws-bin-symlink-guard && npm run test:install-claws-dir-export && npm run test:fix-mcp-recovery && npm run test:fix-pipe-mode-probe && npm run test:install-p3-hygiene && npm run test:install-vsix-extraction-poll && npm run test:update-dry-run && npm run test:dev-hooks-path-canonical && npm run test:worker-fixes-v079 && npm run test:version-drift && npm run test:pre-tool-use-sidecar-recognized && npm run test:ondidclose-publish && npm run test:terminal-manager && npm run test:worker-boot-paste-collapse && npm run test:install-sweep && npm run test:monitor-rearm && npm run test:monitor-arm-watch && npm run test:monitor-corr-arm && npm run test:terminal-alive && npm run test:pty-windows-shell && npm run test:named-pipe-server && npm run test:conpty-marker-scan && npm run test:claws-windows-paths && npm run test:paste-gate && npm run test:mac-event-driven-boot"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/vscode": "^1.93.0",
+    "@types/ws": "^8.5.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.4.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "optionalDependencies": {
+    "@types/ws": "^8.18.1",
+    "node-pty": "^1.1.0",
+    "ws": "^8.20.0"
+  },
+  "contributes": {
+    "commands": [
+      {
+        "command": "claws.status",
+        "title": "Show Status",
+        "category": "Claws"
+      },
+      {
+        "command": "claws.statusBar",
+        "title": "Refresh Status Bar",
+        "category": "Claws"
+      },
+      {
+        "command": "claws.listTerminals",
+        "title": "List Terminals",
+        "category": "Claws"
+      },
+      {
+        "command": "claws.healthCheck",
+        "title": "Health Check",
+        "category": "Claws"
+      },
+      {
+        "command": "claws.showLog",
+        "title": "Show Log",
+        "category": "Claws"
+      },
+      {
+        "command": "claws.rebuildPty",
+        "title": "Rebuild Native PTY",
+        "category": "Claws"
+      },
+      {
+        "command": "claws.uninstallCleanup",
+        "title": "Uninstall Cleanup (remove Claws files from workspaces)",
+        "category": "Claws"
+      }
+    ],
+    "keybindings": [
+      {
+        "command": "claws.healthCheck",
+        "key": "ctrl+alt+c h",
+        "mac": "cmd+alt+c h",
+        "when": "editorTextFocus || !editorTextFocus"
+      },
+      {
+        "command": "claws.showLog",
+        "key": "ctrl+alt+c l",
+        "mac": "cmd+alt+c l",
+        "when": "editorTextFocus || !editorTextFocus"
+      },
+      {
+        "command": "claws.status",
+        "key": "ctrl+alt+c s",
+        "mac": "cmd+alt+c s",
+        "when": "editorTextFocus || !editorTextFocus"
+      }
+    ],
+    "terminal": {
+      "profiles": [
+        {
+          "id": "claws.wrappedTerminal",
+          "title": "Claws Wrapped Terminal",
+          "icon": "terminal-bash"
+        }
+      ]
+    },
+    "configuration": {
+      "title": "Claws",
+      "properties": {
+        "claws.socketPath": {
+          "type": "string",
+          "default": ".claws/claws.sock",
+          "description": "Relative path (from workspace root) for the Unix socket. Default: .claws/claws.sock"
+        },
+        "claws.logDirectory": {
+          "type": "string",
+          "default": ".claws/terminals",
+          "description": "Relative path for wrapped terminal pty logs. Default: .claws/terminals"
+        },
+        "claws.defaultWrapped": {
+          "type": "boolean",
+          "default": false,
+          "description": "Create all new terminals as wrapped (with pty logging) by default."
+        },
+        "claws.maxOutputBytes": {
+          "type": "number",
+          "default": 262144,
+          "description": "Maximum bytes of output buffered per command event (256KB default)."
+        },
+        "claws.maxHistory": {
+          "type": "number",
+          "default": 500,
+          "description": "Maximum command events retained in the ring buffer."
+        },
+        "claws.maxCaptureBytes": {
+          "type": "number",
+          "default": 1048576,
+          "description": "Maximum per-terminal output captured in the in-memory ring buffer for wrapped Pseudoterminal terminals (1 MB default)."
+        },
+        "claws.execTimeoutMs": {
+          "type": "number",
+          "default": 180000,
+          "description": "Default timeout for an `exec` command before the server rejects with timeout (milliseconds, 180s default). Individual requests may override via `timeoutMs` in the request payload."
+        },
+        "claws.pollLimit": {
+          "type": "number",
+          "default": 100,
+          "description": "Maximum number of history events returned by a single `poll` request. Responses exceeding this are truncated to the most-recent `limit` entries and include `truncated: true`."
+        },
+        "claws.enableWebSocket": {
+          "type": "boolean",
+          "default": false,
+          "description": "[Planned] Enable WebSocket server for cross-device access."
+        },
+        "claws.webSocketPort": {
+          "type": "number",
+          "default": 9876,
+          "description": "[Planned] Port for the WebSocket server."
+        },
+        "claws.strictEventValidation": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, the server rejects publish requests that fail envelope or payload schema validation. When false (default), validation failures emit system.malformed.received but the event is still fanned out."
+        },
+        "claws.heartbeatIntervalMs": {
+          "type": "number",
+          "default": 60000,
+          "minimum": 0,
+          "description": "Milliseconds between automatic system.heartbeat events emitted by the server. Set to 0 to disable. Default: 60000 ms (1 minute)."
+        },
+        "claws.auth.enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "[L18 AUTH] When true, hello requests must include a valid HMAC-SHA256 token. Requires claws.auth.tokenPath to be set."
+        },
+        "claws.auth.tokenPath": {
+          "type": "string",
+          "default": ".claws/auth.token",
+          "description": "[L18 AUTH] Path to the shared secret file used for HMAC-SHA256 token validation. Relative paths are resolved from the workspace root."
+        },
+        "claws.webSocket.enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "[L19 TRANSPORT-X] When true, a WebSocket server is started alongside the Unix socket transport. Requires the 'ws' npm package to be installed."
+        },
+        "claws.webSocket.port": {
+          "type": "number",
+          "default": 5678,
+          "minimum": 1024,
+          "maximum": 65535,
+          "description": "[L19 TRANSPORT-X] TCP port for the WebSocket server. Default: 5678."
+        },
+        "claws.webSocket.certPath": {
+          "type": "string",
+          "default": "",
+          "description": "[L19 TRANSPORT-X] Absolute path to TLS certificate file. When set (with keyPath), the server uses wss:// instead of ws://."
+        },
+        "claws.webSocket.keyPath": {
+          "type": "string",
+          "default": "",
+          "description": "[L19 TRANSPORT-X] Absolute path to TLS private key file. When set (with certPath), the server uses wss:// instead of ws://."
+        }
+      }
+    }
+  },
+  "private": false
+}

package/extension/scripts/bundle-native.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// bundle-native.mjs — Harvest node-pty npm prebuilds into native/ for VSIX bundling.
+// Copies node_modules/node-pty/prebuilds/<plat>/ → native/node-pty/prebuilds/<plat>/
+// for each target platform, filtering .pdb files (Windows debug symbols, ~28 MB each).
+// Also copies lib/, package.json, LICENSE, README.md from the node-pty install.
+// Uses atomic staging (M-40) to prevent a kill-window leaving native/ empty.
+//
+// CLI flags:
+//   --strict   exit non-zero on any warning (e.g. missing platform dir)
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, readdirSync, rmSync, renameSync, chmodSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const EXT_ROOT = resolve(__dirname, '..');
+const STRICT = process.argv.includes('--strict');
+
+const NODE_PTY_SRC = join(EXT_ROOT, 'node_modules', 'node-pty');
+const NATIVE_ROOT = join(EXT_ROOT, 'native');
+const NATIVE_DEST = join(NATIVE_ROOT, 'node-pty');
+const METADATA_PATH = join(NATIVE_ROOT, '.metadata.json');
+const PLATFORMS = ['darwin-arm64', 'darwin-x64', 'win32-x64', 'win32-arm64'];
+
+function log(msg) { process.stdout.write(`[bundle-native] ${msg}\n`); }
+function warn(msg) { process.stderr.write(`[bundle-native] WARNING: ${msg}\n`); }
+function fail(msg) { process.stderr.write(`[bundle-native] ERROR: ${msg}\n`); process.exit(1); }
+
+function copyTree(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const n = entry.name;
+    if (n.endsWith('.pdb') || n.endsWith('.d.ts') || n.endsWith('.test.js') || n.endsWith('.test.js.map')) continue;
+    const s = join(src, n), d = join(dest, n);
+    if (entry.isDirectory()) copyTree(s, d);
+    else copyFileSync(s, d);
+  }
+}
+
+function setupStagingDir() {
+  const staging = NATIVE_DEST + '.claws-new';
+  if (existsSync(staging)) rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  return staging;
+}
+
+function main() {
+  log(`extension root: ${EXT_ROOT}`);
+  if (!existsSync(NODE_PTY_SRC)) fail(`node-pty not installed at ${NODE_PTY_SRC}. Run npm install.`);
+
+  const pkg = JSON.parse(readFileSync(join(NODE_PTY_SRC, 'package.json'), 'utf8'));
+  const nodePtyVersion = pkg.version;
+  log(`bundling node-pty@${nodePtyVersion}`);
+
+  const staging = setupStagingDir();
+  const platformsCopied = [];
+
+  // Copy prebuilds for each target platform, skipping .pdb files
+  for (const plat of PLATFORMS) {
+    const src = join(NODE_PTY_SRC, 'prebuilds', plat);
+    if (!existsSync(src)) {
+      warn(`prebuilds/${plat}/ not found in node-pty — skipping`);
+      if (STRICT) { rmSync(staging, { recursive: true, force: true }); process.exit(1); }
+      continue;
+    }
+    copyTree(src, join(staging, 'prebuilds', plat));
+    platformsCopied.push(plat);
+    log(`  copied prebuilds/${plat}/`);
+    // Preserve executable bit on spawn-helper (darwin/linux only; win32 has no spawn-helper).
+    // node-pty uses posix_spawnp to exec spawn-helper; mode 0644 → posix_spawnp EACCES →
+    // every wrapped terminal falls back to pipe-mode. Guard with existsSync so win32
+    // prebuilds (which have no spawn-helper) never trip a spurious ENOENT.
+    const spawnHelperDest = join(staging, 'prebuilds', plat, 'spawn-helper');
+    if (existsSync(spawnHelperDest)) {
+      chmodSync(spawnHelperDest, 0o755);
+      log(`  chmod +x ${plat}/spawn-helper`);
+    }
+  }
+
+  // Copy JS runtime (lib/) and metadata files
+  copyTree(join(NODE_PTY_SRC, 'lib'), join(staging, 'lib'));
+  for (const f of ['package.json', 'LICENSE', 'README.md']) {
+    const s = join(NODE_PTY_SRC, f);
+    if (existsSync(s)) copyFileSync(s, join(staging, f));
+  }
+
+  // M-40 atomic swap: staging → NATIVE_DEST via rename(2)
+  const oldDest = NATIVE_DEST + '.claws-old';
+  if (existsSync(NATIVE_DEST)) renameSync(NATIVE_DEST, oldDest);
+  renameSync(staging, NATIVE_DEST);
+  if (existsSync(oldDest)) { try { rmSync(oldDest, { recursive: true, force: true }); } catch { /* best-effort */ } }
+
+  // Write metadata for diagnostic visibility
+  writeFileSync(METADATA_PATH, JSON.stringify({
+    node_pty_version: nodePtyVersion,
+    copied_at: new Date().toISOString(),
+    platforms_included: platformsCopied,
+  }, null, 2) + '\n', 'utf8');
+  log(`wrote native/.metadata.json (${platformsCopied.length} platforms: ${platformsCopied.join(', ')})`);
+  log('[bundle-native] done.');
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();

package/extension/scripts/deploy-dev.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Deploys the freshly built extension into VS Code's installed-extensions
+// directory so a window reload picks up local changes. Without this step
+// `npm run build` only writes to ./dist — VS Code keeps loading whatever
+// version was last installed via VSIX or the marketplace.
+//
+// Finds every `~/.vscode/extensions/<publisher>.<name>-*` directory matching
+// the package.json publisher+name, copies dist/extension.js, and rsyncs the
+// native/ bundle. Reports what was updated.
+
+import { readFileSync, statSync, readdirSync, copyFileSync, mkdirSync, existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const extRoot = join(__dirname, '..');
+const pkg = JSON.parse(readFileSync(join(extRoot, 'package.json'), 'utf8'));
+const slug = `${pkg.publisher}.${pkg.name}`;
+const extensionsDir = join(homedir(), '.vscode', 'extensions');
+
+const candidates = readdirSync(extensionsDir, { withFileTypes: true })
+  .filter((e) => e.isDirectory() && e.name.startsWith(slug + '-'))
+  .map((e) => join(extensionsDir, e.name));
+
+if (candidates.length === 0) {
+  console.error(`[deploy-dev] no installed extension matching ${slug}-* in ${extensionsDir}`);
+  console.error(`[deploy-dev] install once with: code --install-extension <path-to.vsix>`);
+  process.exit(1);
+}
+
+const distSrc = join(extRoot, 'dist', 'extension.js');
+const nativeSrc = join(extRoot, 'native');
+try { statSync(distSrc); } catch { console.error(`[deploy-dev] missing ${distSrc} — run npm run build first`); process.exit(1); }
+
+const pkgJsonSrc = join(extRoot, 'package.json');
+
+let deployed = 0;
+for (const target of candidates) {
+  const distDst = join(target, 'dist');
+  mkdirSync(distDst, { recursive: true });
+  copyFileSync(distSrc, join(distDst, 'extension.js'));
+  // Sync package.json so VS Code's UI shows the current version label.
+  // VS Code reads `version` from each installed-extension dir's package.json;
+  // without this copy, the panel keeps showing whatever version was first installed.
+  // See `.local/issues/10-deploy-dev-missing-package-json.md`.
+  copyFileSync(pkgJsonSrc, join(target, 'package.json'));
+  const r = spawnSync('rsync', ['-a', '--delete', nativeSrc + '/', join(target, 'native') + '/'], { stdio: 'inherit' });
+  if (r.status !== 0) { console.error(`[deploy-dev] rsync failed for ${target}`); process.exit(r.status ?? 1); }
+  // Copy display artifacts so VS Code Extensions panel shows title, icon, and changelog.
+  for (const artifact of ['README.md', 'CHANGELOG.md', 'icon.png']) {
+    const src = join(extRoot, artifact);
+    if (existsSync(src)) copyFileSync(src, join(target, artifact));
+  }
+  console.log(`[deploy-dev] updated ${target} (version ${pkg.version})`);
+  deployed++;
+}
+
+console.log(`[deploy-dev] ${deployed} install${deployed === 1 ? '' : 's'} updated. Reload VS Code: Cmd+Shift+P → Developer: Reload Window`);

package/extension/src/ansi-strip.ts

@@ -0,0 +1,52 @@
+// Strip ANSI escape sequences and most other control bytes from a pty log so
+// it can be rendered as plain text. Handles the real-world sequences we see
+// from wrapped terminals (shells, vim, claude, ink-based TUIs, etc):
+//
+//   - CSI (Control Sequence Introducer): ESC [ ... final
+//     Covers simple `\x1b[0m`, parameterized `\x1b[?25h`, `\x1b[38;5;123m`,
+//     `\x1b[1;31;48;2;255;100;100m`, etc. Parameter bytes 0x30–0x3F,
+//     intermediate bytes 0x20–0x2F, final byte 0x40–0x7E.
+//
+//   - OSC (Operating System Command): ESC ] ... terminator
+//     Used for terminal titles, hyperlinks, and iTerm proprietary sequences.
+//     Terminator is either BEL (\x07) or ST (ESC \\).
+//
+//   - DCS (Device Control String): ESC P ... ST
+//     Used by sixel graphics, termcap queries, etc.
+//
+//   - APC / PM / SOS: ESC _ / ESC ^ / ESC X — same terminator as DCS.
+//
+//   - Single-char ESC sequences: ESC ( B, ESC ) 0, ESC =, ESC >, ESC M …
+//     Mostly charset selection and cursor save/restore.
+//
+// After removing escape sequences we also strip stray C0/C1 control bytes
+// (with \t, \n, \r spared — they are meaningful plaintext).
+
+const CSI_PATTERN = /\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]/g;
+
+// OSC: ESC ] ... (BEL | ESC \). Use a non-greedy match so consecutive
+// sequences don't collapse into one. `[\s\S]` because OSC strings can
+// technically contain newlines (e.g. tmux pass-through).
+const OSC_PATTERN = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
+
+// DCS / SOS / PM / APC: ESC [P^_X] ... ESC \\.
+const DCS_PATTERN = /\x1b[P^_X][\s\S]*?\x1b\\/g;
+
+// Single-char ESC followed by a final byte from 0x20–0x7E (non-CSI/OSC/DCS).
+// Examples: `\x1b(B` (G0 = ASCII), `\x1b=` (keypad), `\x1bM` (reverse index).
+// Must come AFTER CSI/OSC/DCS so we don't eat their introducers.
+const SINGLE_ESC_PATTERN = /\x1b[\x20-\x2f]*[\x30-\x7e]/g;
+
+// Bare ESC (no follow-on byte, e.g. ESC at end of stream) + C0 controls
+// except tab/newline/carriage-return, plus DEL.
+const CTRL_PATTERN = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+
+export function stripAnsi(text: string): string {
+  if (!text) return text;
+  return text
+    .replace(OSC_PATTERN, '')
+    .replace(DCS_PATTERN, '')
+    .replace(CSI_PATTERN, '')
+    .replace(SINGLE_ESC_PATTERN, '')
+    .replace(CTRL_PATTERN, '');
+}