liteagents 2.6.1 → 2.8.1

package/packages/ampcode/commands/ship.md

@@ -2,17 +2,39 @@
 name: ship
 description: Check pre-deployment
 usage: /ship
-allowed-tools: Bash(npm *), Bash(git *)
+allowed-tools: Read, Grep, Glob, Bash(git *), Bash(npm *), Bash(pnpm *), Bash(yarn *), Bash(pytest *), Bash(python *), Bash(go *), Bash(cargo *), Bash(make *)
 ---
-Pre-deploy checklist:
+Pre-deploy / pre-merge gate. **Detect the stack first** (look for
+`package.json`, `pyproject.toml`/`setup.cfg`, `go.mod`, `Cargo.toml`,
+`Makefile`) and run only the checks that actually exist — never assume a
+script (`lint`, `build`, `migrate`) is present. Report each item as
+**pass / fail / N/A**.
 
-- [ ] Tests pass (`npm test`)
-- [ ] Lint clean (`npm run lint`)
-- [ ] Build succeeds (`npm run build`)
-- [ ] No console.log/debugger statements
-- [ ] Env vars documented
-- [ ] No hardcoded secrets
-- [ ] Error handling complete
-- [ ] Migrations ready
+## Checklist
+- [ ] **Tests pass** — run the project's real test command (`npm test`,
+      `pytest`, `go test ./...`, `cargo test`, `make test`).
+- [ ] **Lint / format clean** — only if a linter or formatter is configured.
+- [ ] **Build succeeds** — only if the project has a build step.
+- [ ] **No debug leftovers** — stray `console.log` / `print` / `debugger` /
+      `dbg!` / commented-out blocks / blocker `TODO`s in the changed files.
+- [ ] **No hardcoded secrets** — scan the diff. Secrets load from env / a
+      secret store; `.env` is gitignored and only a value-less `.env.example`
+      is tracked.
+- [ ] **Error handling complete** — every new IO / network / DB call has a
+      failure path; nothing fails silently; no internal detail leaks to clients.
+- [ ] **Authorization** — new endpoints/actions check **ownership + role**,
+      not just authentication (no IDOR via id-swapping).
+- [ ] **Rate limiting** — new externally reachable routes, including
+      authenticated writes, are bounded.
+- [ ] **Data access scoped & scales** — new queries are constrained to the
+      requesting principal (no cross-tenant leak) and avoid obvious N+1 /
+      unindexed scans on hot paths.
+- [ ] **Migrations ready** — only if the project has a schema / migrations.
+- [ ] **Docs & config in sync** — `.env.example`, README, and any
+      threat-model / PRD updated for new config or new attack surface.
+- [ ] **Clean tree, correct branch, in sync with `origin`.**
 
-Run checks and report: Ready 🚀 or Blocked 🛑 with issues.
+For any security-sensitive change in the diff, run **`/security`** on the
+changed files before shipping.
+
+Report: **Ready 🚀** or **Blocked 🛑** with the specific failing items.

package/packages/claude/commands/git-commit.md

@@ -2,7 +2,7 @@
 name: git-commit
 description: Analyze changes and commit
 usage: /git-commit
-allowed-tools: Bash(git *)
+allowed-tools: Bash(git:*)
 ---
 1. Run `git diff --staged` to see changes
 2. Analyze what was changed and why

package/packages/claude/commands/security.md

@@ -3,19 +3,57 @@ name: security
 description: Scan security [target]
 usage: /security
 argument-hint: [file, directory, or leave empty for full scan]
-allowed-tools: Read, Grep, Glob
+allowed-tools: Read, Grep, Glob, Bash(git log:*), Bash(git grep:*), Bash(rg:*)
 ---
-Audit $ARGUMENTS for security vulnerabilities.
+Audit $ARGUMENTS for security vulnerabilities. Adapt scope to what the target
+actually is — a library, CLI, web app, and service won't all have every
+category. Skip what genuinely doesn't apply; never invent findings to fill a
+section.
 
-## Check For
-- Injection: SQL, command, XSS, template
-- Auth: Weak passwords, session issues, CSRF
-- Data: Exposure, logging secrets, insecure storage
-- Config: Debug mode, default creds, missing headers
-- Dependencies: Known CVEs
+## The recurring six (check every project, where applicable)
+These show up in nearly every quickly-built app regardless of stack:
+
+1. **Secrets in the repo.** Tokens / API keys / `.env` files committed to
+   tracked files or anywhere in git history. Verify `.env` is gitignored and
+   only a value-less `.env.example` is tracked; scan history (`git log -p`,
+   `git grep`) for leaked keys. Secrets must load from env / a secret store at
+   runtime — never hardcoded, never logged.
+2. **Data-access authorization (tenant isolation).** Every record read or
+   written must be scoped to the requesting principal — via DB-level rules
+   (RLS / row policies) and/or application-layer ownership checks. Flag any
+   query that trusts a client-supplied id without an ownership or role gate,
+   and any table/collection with a policy that's too broad or missing.
+3. **Rate limiting.** Every externally reachable endpoint and abuse-prone
+   inbound path is bounded — including **authenticated mutation/write routes**,
+   not just the obvious public GETs. Note any unbounded route.
+4. **Error handling past the happy path.** Third-party / IO / DB failures are
+   caught; nothing fails silently; no internal detail (stack traces, queries,
+   secrets) leaks to the client. Background/async work has its own catch.
+5. **Authorization beyond authentication (IDOR / privilege).** "Logged in" is
+   not "allowed to do this". Confirm ownership AND role/permission checks on
+   every state-changing or privileged action. Mentally swap an id in a request
+   — does it return 403, or does it leak/modify another user's data?
+6. **Inefficient data access (N+1 / unindexed).** Queries inside loops,
+   per-render repeated calls, missing indexes on filtered/joined columns.
+   Correct but falls over under load — a real availability risk.
+
+## Also scan for
+- **Injection:** SQL, command, XSS, template, path traversal.
+- **Auth/session:** weak token handling, CSRF, session fixation, predictable ids.
+- **Trust boundaries:** spoofable headers (e.g. `X-Forwarded-For`) trusted
+  without a vetted proxy; unvalidated untrusted input (uploads, inbound mail,
+  webhooks); services bound to `0.0.0.0` that should be loopback-only.
+- **Config:** debug mode on in prod, default creds, missing security headers,
+  permissive CORS.
+- **Dependencies:** known CVEs; unmaintained or single-maintainer deps in
+  security-critical paths.
 
 ## Output
-Severity-ranked findings with:
-- Location (file:line)
-- Risk explanation
-- Remediation steps
+Severity-ranked findings (Critical → High → Medium → Low), each with:
+- **Location** (`file:line`)
+- **Risk** — what an attacker actually gains
+- **Remediation** — concrete, minimal fix
+
+End with: which of the six classes were checked and found **clean**, and any
+marked **N/A** for this target — so the scan's coverage is auditable, not just
+its hits.

package/packages/claude/commands/ship.md

@@ -2,17 +2,39 @@
 name: ship
 description: Check pre-deployment
 usage: /ship
-allowed-tools: Bash(npm *), Bash(git *)
+allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(pytest:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Bash(make:*)
 ---
-Pre-deploy checklist:
+Pre-deploy / pre-merge gate. **Detect the stack first** (look for
+`package.json`, `pyproject.toml`/`setup.cfg`, `go.mod`, `Cargo.toml`,
+`Makefile`) and run only the checks that actually exist — never assume a
+script (`lint`, `build`, `migrate`) is present. Report each item as
+**pass / fail / N/A**.
 
-- [ ] Tests pass (`npm test`)
-- [ ] Lint clean (`npm run lint`)
-- [ ] Build succeeds (`npm run build`)
-- [ ] No console.log/debugger statements
-- [ ] Env vars documented
-- [ ] No hardcoded secrets
-- [ ] Error handling complete
-- [ ] Migrations ready
+## Checklist
+- [ ] **Tests pass** — run the project's real test command (`npm test`,
+      `pytest`, `go test ./...`, `cargo test`, `make test`).
+- [ ] **Lint / format clean** — only if a linter or formatter is configured.
+- [ ] **Build succeeds** — only if the project has a build step.
+- [ ] **No debug leftovers** — stray `console.log` / `print` / `debugger` /
+      `dbg!` / commented-out blocks / blocker `TODO`s in the changed files.
+- [ ] **No hardcoded secrets** — scan the diff. Secrets load from env / a
+      secret store; `.env` is gitignored and only a value-less `.env.example`
+      is tracked.
+- [ ] **Error handling complete** — every new IO / network / DB call has a
+      failure path; nothing fails silently; no internal detail leaks to clients.
+- [ ] **Authorization** — new endpoints/actions check **ownership + role**,
+      not just authentication (no IDOR via id-swapping).
+- [ ] **Rate limiting** — new externally reachable routes, including
+      authenticated writes, are bounded.
+- [ ] **Data access scoped & scales** — new queries are constrained to the
+      requesting principal (no cross-tenant leak) and avoid obvious N+1 /
+      unindexed scans on hot paths.
+- [ ] **Migrations ready** — only if the project has a schema / migrations.
+- [ ] **Docs & config in sync** — `.env.example`, README, and any
+      threat-model / PRD updated for new config or new attack surface.
+- [ ] **Clean tree, correct branch, in sync with `origin`.**
 
-Run checks and report: Ready 🚀 or Blocked 🛑 with issues.
+For any security-sensitive change in the diff, run **`/security`** on the
+changed files before shipping.
+
+Report: **Ready 🚀** or **Blocked 🛑** with the specific failing items.

package/packages/claude/plugins/live-canvas-marketplace/plugins/live-canvas-channel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "live-canvas-channel",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "description": "Bridges the Live Canvas browser overlay to a Claude Code session. Each overlay Save becomes a claude/channel notification delivered over MCP.",
   "author": { "name": "liteagents" },
   "channels": [

package/packages/claude/plugins/live-canvas-marketplace/plugins/live-canvas-channel/README.md

@@ -12,7 +12,7 @@ Claude Code channel plugin that bridges the Live Canvas browser overlay to a run
 ```
 
 - HTTP listener: `127.0.0.1:8788` (override with `LIVE_CANVAS_PORT`)
-- `GET /health` — overlay probes this to select Live vs Batch mode
+- `GET /health` — overlay probes this to confirm Live mode is reachable
 - `POST /feedback` — wire-compatible with the overlay's v1.0 schema
 - stdio: MCP protocol using `@modelcontextprotocol/sdk`
 
@@ -84,6 +84,6 @@ curl -X POST http://localhost:8788/feedback \
 
 ## Failure modes
 
-- **Port in use** — another Claude session owns 8788. Logs to stderr and exits; overlay health probe fails; overlay falls back to Batch mode silently.
+- **Port in use** — another Claude session owns 8788. Logs to stderr and exits; overlay health probe fails; overlay falls back to JSON mode silently. The skill itself never silently degrades — it stops and asks the user.
 - **Invalid payload** — HTTP 400 with reason; no notification emitted.
 - **MCP transport not connected** — HTTP call still returns 200 (so the overlay shows "pushed"), but stderr logs the drop. Avoids false-negative toasts.

package/packages/claude/plugins/live-canvas-marketplace/plugins/live-canvas-channel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "live-canvas-channel",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "description": "MCP channel server: bridges Live Canvas HTTP overlay events into the Claude Code session.",
   "main": "server.js",
   "type": "commonjs",

package/packages/claude/plugins/live-canvas-marketplace/plugins/live-canvas-channel/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "LiveCanvasFeedback",
-  "description": "Payload shape posted by the Live Canvas overlay to POST /feedback. Wire-compatible with the v1.0 schema produced by overlay-vanilla.js and the upstream React FeedbackOverlay.",
+  "description": "Payload shape posted by the Live Canvas overlay to POST /feedback. v1.0 schema produced by overlay-vanilla.js.",
   "type": "object",
   "required": ["version", "target", "comment"],
   "properties": {

package/packages/claude/plugins/live-canvas-marketplace/plugins/live-canvas-channel/server.js

@@ -2,14 +2,15 @@
 /**
  * live-canvas-channel — MCP channel server for Claude Code.
  *
- * Two concurrent duties:
- *   1. HTTP listener (LIVE_CANVAS_PORT, default 8788) — accepts feedback
- *      POSTs from the Live Canvas overlay running in the browser. The
- *      overlay probes GET /health to decide Live vs Batch mode.
- *   2. MCP stdio server — declares the `experimental: claude/channel`
- *      capability and, on each valid POST, emits a
- *      `notifications/claude/channel` notification so the feedback lands
- *      in the active Claude turn.
+ * Three duties:
+ *   1. MCP stdio server — connects at startup so `/mcp` shows green in
+ *      every Claude session, even sessions that never touch live-canvas.
+ *   2. Tools `channel_open` / `channel_close` — lazily bind/release the
+ *      HTTP listener on LIVE_CANVAS_PORT (default 8788). Only the session
+ *      that calls `channel_open` owns the port; other sessions stay idle.
+ *   3. HTTP listener (only while open) — accepts feedback POSTs from the
+ *      browser overlay and emits a `notifications/claude/channel`
+ *      notification into the owning session's turn.
  *
  * Protocol reference: https://code.claude.com/docs/en/channels-reference
  */
@@ -17,19 +18,28 @@
 'use strict';
 
 const http = require('http');
+const fs = require('fs');
+const path = require('path');
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
 
 const PORT = Number(process.env.LIVE_CANVAS_PORT || 8788);
 const SERVER_NAME = 'live-canvas';
-const SERVER_VERSION = '0.1.0';
+const SERVER_VERSION = '0.5.0';
 
 // ---------- MCP server ----------
 
 const mcp = new Server(
   { name: SERVER_NAME, version: SERVER_VERSION },
   {
-    capabilities: { experimental: { 'claude/channel': {} } },
+    capabilities: {
+      tools: {},
+      experimental: { 'claude/channel': {} },
+    },
     instructions: [
       'Events from the live-canvas channel arrive as <channel source="live-canvas" ...> tags.',
       'Each event is a single click-to-annotate comment made by the user on a UI variant in their browser.',
@@ -38,6 +48,7 @@ const mcp = new Server(
       'When one arrives: acknowledge the feedback briefly, then edit the corresponding variant file',
       'in .claude-design/lab/ using the selector to locate the element. This is a one-way channel —',
       'no reply tool; respond to the user in chat as you would any normal message.',
+      'Before entering Live mode, call the channel_open tool; on exit or abort, call channel_close.',
     ].join(' '),
   }
 );
@@ -80,7 +91,6 @@ function validate(payload) {
   return null;
 }
 
-// Human-readable body the assistant will see inside the Claude turn.
 function formatContent(target, comment) {
   const { variant, element, text } = comment;
   const label = element.textContent ? `, ${element.tagName} with "${element.textContent}"` : '';
@@ -91,7 +101,6 @@ function formatContent(target, comment) {
   ].join('\n');
 }
 
-// All values in `meta` must be strings per the claude/channel contract.
 function buildMeta(target, comment) {
   return {
     source: 'live-canvas',
@@ -103,7 +112,7 @@ function buildMeta(target, comment) {
   };
 }
 
-// ---------- HTTP server ----------
+// ---------- HTTP server (created but not bound) ----------
 
 const server = http.createServer(async (req, res) => {
   cors(res);
@@ -116,6 +125,27 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  if (req.method === 'POST' && req.url === '/feedback-jsonl') {
+    // JSON-mode batch endpoint: appends the submitted payload to
+    // <parent claude cwd>/.claude-design/feedback.jsonl so the user doesn't
+    // have to download a file and paste. No capability gate — JSON mode
+    // doesn't depend on the experimental channels flag.
+    try {
+      const raw = await readBody(req);
+      JSON.parse(raw); // validate JSON only — schema is overlay-defined
+      const dir = path.join(process.cwd(), '.claude-design');
+      fs.mkdirSync(dir, { recursive: true });
+      const file = path.join(dir, 'feedback.jsonl');
+      fs.appendFileSync(file, raw.trim() + '\n');
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, path: file }));
+    } catch (e) {
+      res.writeHead(400, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: String(e.message || e) }));
+    }
+    return;
+  }
+
   if (req.method === 'POST' && req.url === '/feedback') {
     try {
       const raw = await readBody(req);
@@ -133,8 +163,6 @@ const server = http.createServer(async (req, res) => {
           buildMeta(payload.target, payload.comment)
         );
       } catch (e) {
-        // MCP transport not yet connected or closed — still ack the HTTP
-        // caller so the overlay doesn't false-negative.
         process.stderr.write(`[live-canvas] notify failed: ${e.message || e}\n`);
       }
 
@@ -150,28 +178,293 @@ const server = http.createServer(async (req, res) => {
   res.writeHead(404); res.end();
 });
 
-server.on('error', (err) => {
-  if (err.code === 'EADDRINUSE') {
-    process.stderr.write(`[live-canvas] port ${PORT} in use — another session likely owns it; exiting.\n`);
-    process.exit(0);
+// ---------- channel capability check ----------
+
+// Channels are still an experimental Claude Code feature. They only deliver
+// `<channel>` tags into sessions launched with --dangerously-load-development-channels.
+// Without that flag, a plain `claude` session can still load the MCP and bind the
+// port, but every notification we emit is silently dropped — producing the
+// "POST 200, but nothing landed" black hole. Detect by inspecting the parent
+// claude's command-line; refuse to bind from non-qualifying sessions.
+const RELAUNCH_HINT = 'Restart this session with: live-claude  (or: claude --dangerously-load-development-channels plugin:live-canvas-channel@live-canvas-marketplace)';
+
+function parentHasChannelsFlag() {
+  const FLAG = '--dangerously-load-development-channels';
+  const ppid = process.ppid;
+
+  // Linux: /proc/<pid>/cmdline is NUL-separated argv. Fast, no subprocess.
+  try {
+    const raw = require('fs').readFileSync(`/proc/${ppid}/cmdline`, 'utf8');
+    return raw.split('\0').some((arg) => arg === FLAG);
+  } catch { /* fall through */ }
+
+  // macOS / BSD / any POSIX without /proc: `ps -p <pid> -o args=` prints the
+  // full command line. Whitespace splits are fine here — the flag is a single
+  // token with no quoting needed.
+  if (process.platform !== 'win32') {
+    try {
+      const out = require('child_process')
+        .execFileSync('ps', ['-p', String(ppid), '-o', 'args='], { encoding: 'utf8', timeout: 1000 });
+      return out.split(/\s+/).some((arg) => arg === FLAG);
+    } catch { /* fall through */ }
   }
-  process.stderr.write(`[live-canvas] http error: ${err}\n`);
-  process.exit(1);
+
+  // Windows: `wmic process where processid=<pid> get commandline /value`
+  // emits "CommandLine=<full string>". We split on whitespace then match.
+  if (process.platform === 'win32') {
+    try {
+      const out = require('child_process')
+        .execFileSync('wmic', ['process', 'where', `processid=${ppid}`, 'get', 'commandline', '/value'], { encoding: 'utf8', timeout: 1500 });
+      return out.split(/\s+/).some((arg) => arg === FLAG);
+    } catch { /* fall through */ }
+  }
+
+  // Couldn't determine — fail closed. Better a wrong "no_channel_capability"
+  // error than a silent black hole. User can read the message and rerun.
+  return false;
+}
+
+// ---------- lazy bind / release ----------
+
+// Resolve who's holding `port`. Tries `ss` first (fast on Linux), then `lsof`
+// (cross-platform). Returns null if we can't tell.
+function findPortHolder(port) {
+  const { execFileSync } = require('child_process');
+  try {
+    const out = execFileSync('ss', ['-lntpH', `sport = :${port}`], { encoding: 'utf8', timeout: 800 });
+    const m = out.match(/pid=(\d+)/);
+    if (m) return Number(m[1]);
+  } catch { /* not Linux or ss unavailable */ }
+  try {
+    const out = execFileSync('lsof', ['-iTCP:' + port, '-sTCP:LISTEN', '-t'], { encoding: 'utf8', timeout: 800 });
+    const first = out.trim().split('\n')[0];
+    const pid = Number(first);
+    if (pid > 0) return pid;
+  } catch { /* lsof missing */ }
+  return null;
+}
+
+// True iff `pid` is another instance of THIS server.js running as the same uid.
+// "Same plugin binary + same user" is the criterion for safe takeover — it can
+// only be another /live-canvas in another of this user's Claude sessions.
+function isMyPluginServer(pid) {
+  if (!pid || pid === process.pid) return false;
+  const myUid = (typeof process.getuid === 'function') ? process.getuid() : null;
+
+  // Linux: read /proc/<pid>/cmdline + /proc/<pid>/status
+  try {
+    const cmdline = require('fs').readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+    if (!cmdline.split('\0').includes(__filename)) return false;
+    if (myUid !== null) {
+      const status = require('fs').readFileSync(`/proc/${pid}/status`, 'utf8');
+      const m = status.match(/^Uid:\s+(\d+)/m);
+      if (m && Number(m[1]) !== myUid) return false;
+    }
+    return true;
+  } catch { /* fall through */ }
+
+  // macOS / BSD: ps args + ps user
+  try {
+    const { execFileSync } = require('child_process');
+    const args = execFileSync('ps', ['-p', String(pid), '-o', 'args='], { encoding: 'utf8', timeout: 800 });
+    if (!args.includes(__filename)) return false;
+    if (myUid !== null) {
+      const uidOut = execFileSync('ps', ['-p', String(pid), '-o', 'uid='], { encoding: 'utf8', timeout: 800 });
+      if (Number(uidOut.trim()) !== myUid) return false;
+    }
+    return true;
+  } catch { /* fall through */ }
+
+  return false;
+}
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+// One bind attempt. Resolves on success/EADDRINUSE; rejects on other errors.
+function tryBind() {
+  return new Promise((resolve, reject) => {
+    const onError = (err) => {
+      server.off('error', onError);
+      if (err.code === 'EADDRINUSE') resolve(false);
+      else reject(err);
+    };
+    server.once('error', onError);
+    server.listen(PORT, '127.0.0.1', () => {
+      server.off('error', onError);
+      resolve(true);
+    });
+  });
+}
+
+async function openChannel() {
+  const cap = parentHasChannelsFlag();
+  if (cap === false) {
+    return {
+      status: 'no_channel_capability',
+      port: PORT,
+      message: `This Claude session was launched without --dangerously-load-development-channels — channel notifications would be silently dropped. ${RELAUNCH_HINT}`,
+    };
+  }
+  if (server.listening) return { status: 'already_listening', port: PORT };
+
+  if (await tryBind()) {
+    process.stderr.write(`[live-canvas] listening on 127.0.0.1:${PORT}\n`);
+    return { status: 'opened', port: PORT };
+  }
+
+  // Port busy. If the holder is another instance of this same plugin running
+  // as the same uid, take it over — same user, same binary, definitionally
+  // safe. (The flag gate above already authorized this caller for channels.)
+  const holder = findPortHolder(PORT);
+  if (holder && isMyPluginServer(holder)) {
+    process.stderr.write(`[live-canvas] taking over port ${PORT} from sibling pid ${holder}\n`);
+    try { process.kill(holder, 'SIGTERM'); } catch { /* already gone */ }
+
+    // Poll for the port to free (the sibling's shutdown closes its listener).
+    for (let i = 0; i < 15; i++) {
+      await sleep(100);
+      if (await tryBind()) {
+        process.stderr.write(`[live-canvas] listening on 127.0.0.1:${PORT} (took over from pid ${holder})\n`);
+        return { status: 'opened', port: PORT, took_over: holder };
+      }
+    }
+    // Last resort — SIGKILL the holdout, one more try.
+    try { process.kill(holder, 'SIGKILL'); } catch {}
+    await sleep(200);
+    if (await tryBind()) {
+      process.stderr.write(`[live-canvas] listening on 127.0.0.1:${PORT} (force-killed pid ${holder})\n`);
+      return { status: 'opened', port: PORT, took_over: holder, force_killed: true };
+    }
+    return {
+      status: 'in_use',
+      port: PORT,
+      holder_pid: holder,
+      message: `Tried to take over port ${PORT} from sibling pid ${holder} but it wouldn't release. Manual cleanup needed: kill -9 ${holder}`,
+    };
+  }
+
+  // Held by something else (different plugin, different user, or unknown).
+  return {
+    status: 'in_use',
+    port: PORT,
+    holder_pid: holder,
+    message: holder
+      ? `Port ${PORT} is held by pid ${holder} (not a live-canvas server). Stop that process or pick JSON mode. To inspect: ps -fp ${holder}`
+      : `Port ${PORT} is held by an unknown process. Find it with: ss -lntp | grep ${PORT}`,
+  };
+}
+
+function closeChannel() {
+  if (!server.listening) {
+    return Promise.resolve({ status: 'not_listening', port: PORT });
+  }
+  return new Promise((resolve) => {
+    server.close(() => {
+      process.stderr.write(`[live-canvas] released port ${PORT}\n`);
+      resolve({ status: 'closed', port: PORT });
+    });
+  });
+}
+
+// JSON-mode bind. No flag gate — channels aren't used, only /feedback-jsonl.
+// Lets a plain `claude` session bind the port so overlay submissions write
+// straight to <cwd>/.claude-design/feedback.jsonl instead of triggering a
+// browser download.
+function openBatch() {
+  if (server.listening) {
+    return Promise.resolve({ status: 'already_listening', port: PORT });
+  }
+  return new Promise((resolve, reject) => {
+    const onError = (err) => {
+      server.off('error', onError);
+      if (err.code === 'EADDRINUSE') {
+        resolve({
+          status: 'in_use',
+          port: PORT,
+          message: `Port ${PORT} is held by another live-canvas session. JSON-mode submissions in this session will fall back to browser download instead of writing to .claude-design/feedback.jsonl.`,
+        });
+      } else {
+        reject(err);
+      }
+    };
+    server.once('error', onError);
+    server.listen(PORT, '127.0.0.1', () => {
+      server.off('error', onError);
+      process.stderr.write(`[live-canvas] listening on 127.0.0.1:${PORT} (batch-only, no channels)\n`);
+      resolve({ status: 'opened', port: PORT });
+    });
+  });
+}
+
+// ---------- tools ----------
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'channel_open',
+      description: 'Bind the live-canvas HTTP listener on port 8788 so the browser overlay can POST feedback into this session. Call once when entering Live mode. Returns {status, port, message?, took_over?, holder_pid?}. status: "opened" (bound, possibly after taking over a sibling live-canvas server — `took_over` is set to the prior pid if so), "already_listening" (we already had it), "in_use" (held by something that is NOT another live-canvas; `holder_pid` and `message` describe it), or "no_channel_capability" (this session lacks --dangerously-load-development-channels — show the user the message and stop, do not proceed to Live mode).',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      name: 'channel_close',
+      description: 'Release the live-canvas HTTP listener so another session can claim it. Call on /live-canvas cleanup, abort, or when the user is done with Live mode. Returns {status: "closed" | "not_listening", port}.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      name: 'batch_open',
+      description: 'Bind the live-canvas HTTP listener on port 8788 for JSON mode only (no channel notifications, no flag required). Call this in JSON mode so the browser overlay can POST submissions to /feedback-jsonl which writes to <cwd>/.claude-design/feedback.jsonl. Returns {status: "opened" | "already_listening" | "in_use", port, message?}. If status is "in_use", JSON submissions fall back to browser download.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+  ],
+}));
+
+mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name } = req.params;
+  let result;
+  if (name === 'channel_open') {
+    result = await openChannel();
+  } else if (name === 'channel_close') {
+    result = await closeChannel();
+  } else if (name === 'batch_open') {
+    result = await openBatch();
+  } else {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
 });
 
-// ---------- startup ----------
+// ---------- startup / shutdown ----------
 
 async function main() {
   const transport = new StdioServerTransport();
   await mcp.connect(transport);
 
-  server.listen(PORT, '127.0.0.1', () => {
-    process.stderr.write(`[live-canvas] listening on 127.0.0.1:${PORT}\n`);
-  });
+  // When the MCP host disconnects (session closed, /reload-plugins), release
+  // the port if we were holding it. Without this the next bind hits EADDRINUSE.
+  let closing = false;
+  const shutdown = () => {
+    if (closing) return;
+    closing = true;
+    if (server.listening) {
+      server.close(() => process.exit(0));
+      setTimeout(() => process.exit(0), 500).unref();
+    } else {
+      process.exit(0);
+    }
+  };
+  transport.onclose = shutdown;
+  process.stdin.on('end', shutdown);
+  process.stdin.on('close', shutdown);
 }
 
-process.on('SIGTERM', () => { server.close(() => process.exit(0)); });
-process.on('SIGINT',  () => { server.close(() => process.exit(0)); });
+process.on('SIGTERM', () => {
+  if (server.listening) server.close(() => process.exit(0));
+  else process.exit(0);
+});
+process.on('SIGINT', () => {
+  if (server.listening) server.close(() => process.exit(0));
+  else process.exit(0);
+});
 
 main().catch((err) => {
   process.stderr.write(`[live-canvas] fatal: ${err}\n`);