@tanqory/dev-mcp 0.1.0-alpha.1 → 0.1.2

package/README.md

@@ -17,24 +17,39 @@ theme, only after you confirm a plan.
 
 ## Setup
 
-A theme from `npm create tanqory-theme` is already configured. To configure one by hand, run the server from the
-theme folder:
+A theme from `npm create tanqory-theme` is already configured: it has this package as a devDependency and starts it
+with `node` from `node_modules`. Start it the same way when you configure a theme by hand (`npm install -D
+@tanqory/dev-mcp` first). Avoid `npx` here: an agent host that starts its first turn while MCP servers are still
+connecting (Codex does) sees no tools while `npx` resolves the package (1.4–7.4 s, against about 0.25 s for `node`).
 
 ```jsonc
 // .mcp.json (Claude Code)
-{ "mcpServers": { "tanqory": { "command": "npx", "args": ["-y", "@tanqory/cli", "mcp"] } } }
+{
+  "mcpServers": {
+    "tanqory": {
+      "command": "node",
+      "args": ["node_modules/@tanqory/dev-mcp/bin/tanqory-dev-mcp.mjs"],
+    },
+  },
+}
 ```
 
 ```toml
-# .codex/config.toml (Codex)
+# .codex/config.toml (Codex; read only in a trusted folder)
 [mcp_servers.tanqory]
-command = "npx"
-args = ["-y", "@tanqory/cli", "mcp"]
+command = "node"
+args = ["node_modules/@tanqory/dev-mcp/bin/tanqory-dev-mcp.mjs"]
+tool_timeout_sec = 900   # check_theme takes minutes
 ```
 
-`tanqory mcp` (from `@tanqory/cli`) starts this server and passes itself as the CLI to call. To run the server on
-its own, use `npx -y @tanqory/dev-mcp`. It then looks for the CLI in the theme's `node_modules/.bin`, then on
-`PATH`. Node 20 or newer.
+The server looks for the CLI in the theme's `node_modules/.bin`, then on `PATH`. `tanqory mcp` (from
+`@tanqory/cli`) also starts this server, passing itself as the CLI to call. Node 20 or newer.
+
+**Sandboxed agent shells.** Some hosts run each shell command in an OS sandbox (Codex). There, headless Chromium
+cannot start, and a command may not signal a process another command started. The server the host configured runs
+outside that sandbox, so use its tools (`start_dev_server`, `screenshot`, `check_theme`, `stop_dev_server`). A copy
+started from a sandboxed shell (`CODEX_SANDBOX` set) refuses the browser and check tools at once with
+`sandboxed_shell`, instead of failing minutes later.
 
 ## Tools
 
@@ -53,7 +68,9 @@ next.
 | `validate_manifest`                                                                     | Checks `dist/abi/manifest.json` with the theme's own `validateManifest` plus the JCS byte rule. Problems are traced to the `src/` file and line that declares them.                                                                                                                                                                                                  |
 | `check_theme {tier?}`                                                                   | Runs `tanqory theme check --json`. The tiers are security (the 9 ABI suites), storefront and budgets. Each failure carries `tier`, `checkId`, `message` and `hint`, plus `file:line` when known.                                                                                                                                                                     |
 | `run_storefront_checks`                                                                 | Runs `tanqory theme check --tier storefront --json`.                                                                                                                                                                                                                                                                                                                 |
-| `dev_server_status`                                                                     | Reads `.tanqory/dev-server.json` and `GET /__tq/status`, then reports the URL, the store, the mode and the last build's errors. It never starts the server for you.                                                                                                                                                                                                  |
+| `start_dev_server {mock?, port?}`                                                       | Starts `tanqory theme dev` (output in `.tanqory/dev-server.log`) and waits until it serves. Returns the URL, the pid and the last build. Already running: returns that one. A server that exits first returns its own error. Dev servers it started stop when the MCP server shuts down.                                                                             |
+| `stop_dev_server`                                                                       | Runs `tanqory theme dev --stop`: `POST /__tq/stop` with the token in `.tanqory/dev-server.json`, else a signal to its verified pid. It never stops a process by name.                                                                                                                                                                                                |
+| `dev_server_status`                                                                     | Reads `.tanqory/dev-server.json` and `GET /__tq/status`, then reports the URL, the store, the mode and the last build's errors. It never starts or stops the server.                                                                                                                                                                                                 |
 | `get_page {path, locale?, market?, viewport?, maxHtmlChars?}`                           | Gets the server-rendered HTML from `GET /__tq/page`. It also loads the page in headless Chromium and collects console errors.                                                                                                                                                                                                                                        |
 | `screenshot {path, viewport, locale?, market?, fullPage?}`                              | Returns a PNG, as an MCP image block, from local Playwright.                                                                                                                                                                                                                                                                                                         |
 | `list_dev_stores`                                                                       | Runs `tanqory stores --json` and reports the store this theme is linked to.                                                                                                                                                                                                                                                                                          |

package/bin/tanqory-dev-mcp.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// The Tanqory theme-development MCP server on stdio. Configure your agent host to run `npx -y @tanqory/dev-mcp`
-// (or `npx -y @tanqory/cli mcp`) in the theme folder.
+// The Tanqory theme-development MCP server on stdio. Configure your agent host to run it from the theme folder with
+// `node node_modules/@tanqory/dev-mcp/bin/tanqory-dev-mcp.mjs` (a theme devDependency; no npx at startup).
 import { main } from '../src/index.mjs'
 
 if (process.argv.includes('--version')) {

package/bundled/theme-conformance/docs/storefront-tier.md

@@ -105,9 +105,9 @@ Status per check: `pass`, `fail`, `warn` (reported, never fails the tier), `not_
 
 **What is approximated (exactly).** Lighthouse is not run: its own navigation would bypass the gateway
 that answers every request in-process. The runner measures in its own Chromium instead:
-- mobile 390×844 DPR 2; CPU slowed 4× (`Emulation.setCPUThrottlingRate`); every response delayed by
-  150 ms + (bytes on the wire × 8 / 1638.4 kbps) by the gateway, text counted gzipped (Lighthouse's
-  "slow 4G" figures applied per response, not a simulated connection pool);
+- mobile 390×844 DPR 2; CPU slowed 4× relative to the **uncontended** host (see "Busy hosts" below);
+  every response delayed by 150 ms + (bytes on the wire × 8 / 1638.4 kbps) by the gateway, text counted
+  gzipped (Lighthouse's "slow 4G" figures applied per response, not a simulated connection pool);
 - FCP, LCP and CLS from `PerformanceObserver`; TBT = Σ(long task − 50 ms) after FCP over load + 3 s;
 - **Speed Index is not measured** (no filmstrip); it is taken as (FCP + LCP) / 2;
 - the score uses Lighthouse's mobile log-normal curves and weights (FCP 10, SI 10, LCP 25, TBT 30, CLS 25);
@@ -116,6 +116,35 @@ that answers every request in-process. The runner measures in its own Chromium i
 
 Both scores are labelled `lab-approximation` in the report and are not Lighthouse scores.
 
+**Busy hosts (host calibration).** `Emulation.setCPUThrottlingRate` slows the renderer relative to the machine
+it runs on, so on a machine whose cores are busy with other work the page is slowed by the throttle *and* by
+the contention: the same theme scored 96–99 on a quiet 6-core host and 76–83 at load 50–240. The runner
+therefore measures and removes the contention instead of letting it count against the theme:
+
+1. *Before* each lab run it times a fixed busy loop in the page's renderer, unthrottled: wall-clock ÷ the main
+   thread's CPU time (`Performance.getMetrics` `ThreadTime`) is the host contention, 1.0 on an idle core. The
+   CDP rate is `4 ÷ contention`, never below 1.
+2. *During* the run it records a `toplevel` trace. Σ wall ÷ Σ CPU time (`dur` / `tdur`) of the renderer main
+   thread's tasks is the contention the measured page actually saw (the throttle burns CPU on that thread,
+   so it cancels out). `effectiveSlowdown = rate × that factor` is the slowdown the page really got.
+3. A run *decides* the verdict when its effective slowdown is 4× within ×1.25 (3.2–5×). A run slowed more
+   than that still proves a **pass** (the theme passed under a harsher device); a run slowed less still
+   proves a **fail**. A run off the target is repeated with the rate corrected by its own measured contention,
+   kept strictly between the highest rate that slowed the page too little and the lowest that slowed it too
+   much (the contention depends on the rate: a heavily throttled renderer burns CPU and is scheduled like a
+   batch job, a lightly throttled one stays interactive, so a plain correction can overshoot the band).
+4. One run per page is enough when it decides and is ≥ 5 points from the budget; otherwise up to four.
+   The page score is the lower median of its deciding runs; the check is the minimum over the pages.
+5. If a page has no deciding run (every run was over-slowed and below 85, or under-slowed and above it) and
+   no decided page failed, `budgets:performance` is **`warn`** with `inconclusive: this host was too busy…`
+   and the measured factors — not a failure, and not a pass of the theme. Re-run on a quieter machine.
+
+On a quiet host the contention is ~1.0, the rate stays 4× and the result is what it was before calibration.
+The busy-loop is not an absolute reference device: throttling stays relative to the machine's own idle
+speed, as before, so a quiet fast machine and a quiet slow one judge a theme exactly as they did. Every run's
+`hostFactor`, `cpuRate`, `windowFactor` and `effectiveSlowdown` is in the check's `evidence.details.pages[].runs`,
+and the maxima in the `performanceScoreMobile` measurement note.
+
 ## 4. Locale-key patterns (the semantic fallback)
 
 When no hook is present, a control is a button/link (by ARIA role) whose accessible name equals one of the

package/bundled/versions.json

@@ -1,6 +1,6 @@
 {
   "@tanqory/theme-abi": "2.0.0-alpha.14",
-  "@tanqory/theme-conformance": "0.1.0-alpha.14",
+  "@tanqory/theme-conformance": "0.1.0-alpha.15",
   "@tanqory/theme-kit": "2.0.0-alpha.3",
   "examples": {
     "blank": "create-tanqory-theme templates/blank"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanqory/dev-mcp",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.2",
   "description": "Local MCP server (stdio) for building Tanqory storefront themes with coding agents: versioned docs and schemas, kit examples, section scaffolding, theme checks, and pages and screenshots of the running dev server.",
   "keywords": [
     "tanqory",
@@ -43,7 +43,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "create-tanqory-theme": "0.2.1"
+    "create-tanqory-theme": "0.2.5"
   },
   "publishConfig": {
     "registry": "https://npm.pkg.github.com"

package/src/browser.mjs

@@ -8,6 +8,7 @@ import { spawnSync } from 'node:child_process'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { SANDBOX_HINT, SANDBOX_MESSAGE, SANDBOX_SIGNS, inSandboxedShell } from './sandbox.mjs'
 
 export const VIEWPORTS = {
   mobile: { width: 390, height: 844, deviceScaleFactor: 2, isMobile: true, hasTouch: true },
@@ -15,9 +16,9 @@ export const VIEWPORTS = {
 }
 
 export class BrowserUnavailable extends Error {
-  constructor(message, hint) {
+  constructor(message, hint, code = 'browser_unavailable') {
     super(message)
-    this.code = 'browser_unavailable'
+    this.code = code
     this.hint = hint
   }
 }
@@ -53,6 +54,7 @@ export class Browser {
     try {
       return await pw.chromium.launch(opts)
     } catch (e) {
+      if (inSandboxedShell() || SANDBOX_SIGNS.test(e.message)) throw new BrowserUnavailable(SANDBOX_MESSAGE, SANDBOX_HINT, 'sandboxed_shell')
       const missing = /Executable doesn't exist|browserType\.launch: .*(not found|ENOENT)/i.test(e.message)
       if (!missing || opts.executablePath || process.env.TANQORY_MCP_NO_BROWSER_DOWNLOAD === '1')
         throw new BrowserUnavailable(`Headless Chromium could not start: ${e.message.split('\n')[0]}`, HINT)

package/src/devcontrol.mjs

@@ -0,0 +1,118 @@
+/**
+ * Start and stop `tanqory theme dev` from the MCP server, so an agent never manages the process from its shell.
+ *
+ * Why it lives here: some agent hosts run every shell command in its own sandbox (Codex's seatbelt), where a
+ * command may not signal a process another command started and headless Chromium cannot launch. The MCP server is
+ * started by the host itself, outside that sandbox, so a dev server it starts is one it can always see and stop.
+ *
+ *   start: spawn `tanqory theme dev [--mock] [--port n] --json` in the theme root (its output goes to
+ *          .tanqory/dev-server.log), then wait until .tanqory/dev-server.json names that pid and /__tq/status
+ *          answers. A server that exits first comes back as its own error (code, message, hint) from the log.
+ *   stop:  `tanqory theme dev --stop --json`: POST /__tq/stop with the record's token, else the pid-verified signal.
+ *          Never by name.
+ * Dev servers this MCP server started are stopped when it shuts down, so a finished agent session leaves none behind.
+ */
+import { spawn } from 'node:child_process'
+import { closeSync, mkdirSync, openSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CliError, parseEnvelope, resolveCli, runCli } from './cli.mjs'
+import { devGet, readDevServer } from './devserver.mjs'
+
+export const DEV_SERVER_LOG = join('.tanqory', 'dev-server.log')
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+const tail = (path, lines = 25) => {
+  try {
+    return readFileSync(path, 'utf8').trim().split('\n').slice(-lines).join('\n')
+  } catch {
+    return ''
+  }
+}
+
+export class DevControl {
+  constructor({ root, cli, log = () => {} }) {
+    this.root = root
+    this.cli = cli
+    this.log = log
+    /** @type {Set<import('node:child_process').ChildProcess>} */
+    this.children = new Set()
+  }
+
+  /** @returns {Promise<object>} the running server: { running, alreadyRunning, url, port, mode, store, pid, editor, log } */
+  async start({ mock = false, port, timeoutMs = 180_000 } = {}) {
+    const root = this.root
+    const existing = readDevServer(root)
+    if (existing.running) {
+      const st = await devGet(existing.record.url, '/__tq/status', { timeoutMs: 5000 }).catch(() => null)
+      if (st?.body?.pid === existing.record.pid) {
+        const r = existing.record
+        return { running: true, alreadyRunning: true, url: r.url, port: r.port, mode: r.mode, store: r.store, pid: r.pid, editor: `${r.url}/__editor`, lastBuild: st.body?.lastBuild }
+      }
+    }
+    const bin = resolveCli({ root, cli: this.cli })
+    if (!bin) throw new CliError('cli_not_found', 'The Tanqory CLI (`tanqory`) was not found in this theme.', 'Run `npm install` in the theme (the starters pin @tanqory/cli), then call start_dev_server again.')
+    mkdirSync(join(root, '.tanqory'), { recursive: true })
+    const logPath = join(root, DEV_SERVER_LOG)
+    const fd = openSync(logPath, 'w', 0o600)
+    const spawnedAt = Date.now()
+    const args = [...bin.args, 'theme', 'dev', ...(mock ? ['--mock'] : []), ...(port ? ['--port', String(port)] : []), '--json']
+    let child
+    try {
+      child = spawn(bin.command, args, { cwd: root, env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' }, stdio: ['ignore', fd, fd] })
+    } finally {
+      closeSync(fd)
+    }
+    this.children.add(child)
+    let exited = null
+    child.once('exit', (code, signal) => {
+      exited = { code, signal }
+      this.children.delete(child)
+    })
+    child.once('error', (e) => {
+      exited = { code: null, signal: null, error: e.message }
+      this.children.delete(child)
+    })
+    this.log(`start_dev_server: pid ${child.pid}: ${[bin.command, ...args].join(' ')}`)
+
+    const until = Date.now() + timeoutMs
+    while (Date.now() < until) {
+      if (exited) {
+        const out = tail(logPath, 60)
+        const env = parseEnvelope(out)
+        if (env && env.ok === false && env.error) throw new CliError(env.error.code ?? 'dev_server_failed_to_start', `The dev server exited before it was ready: ${env.error.message}`, env.error.hint ?? `See ${DEV_SERVER_LOG}.`, { stderr: tail(logPath) })
+        throw new CliError('dev_server_failed_to_start', `The dev server exited (${exited.error ?? `code ${exited.code}${exited.signal ? `, ${exited.signal}` : ''}`}) before it was ready.`, `Its output is in ${DEV_SERVER_LOG}; fix what it says (a build error names file:line), then call start_dev_server again.`, { stderr: tail(logPath) })
+      }
+      const s = readDevServer(root)
+      // ours: the pid we spawned (or, behind a wrapper such as a Windows .cmd shim, a record written after the spawn)
+      if (s.running && (s.record.pid === child.pid || Date.parse(s.record.startedAt ?? '') >= spawnedAt - 1000)) {
+        const st = await devGet(s.record.url, '/__tq/status', { timeoutMs: 5000 }).catch(() => null)
+        if (st && st.status === 200) {
+          const r = s.record
+          return { running: true, alreadyRunning: false, url: r.url, port: r.port, mode: r.mode, store: r.store, pid: r.pid, editor: `${r.url}/__editor`, lastBuild: st.body?.lastBuild, log: DEV_SERVER_LOG }
+        }
+      }
+      await sleep(400)
+    }
+    child.kill('SIGTERM')
+    throw new CliError('dev_server_start_timeout', `The dev server did not come up within ${Math.round(timeoutMs / 1000)} s and was stopped.`, `See ${DEV_SERVER_LOG}.`, { stderr: tail(logPath) })
+  }
+
+  /** `tanqory theme dev --stop`: the record's own server only. */
+  async stop() {
+    const env = await runCli(['theme', 'dev', '--stop'], { root: this.root, cli: this.cli, timeoutMs: 60_000 })
+    if (!env.ok) throw new CliError(env.error?.code ?? 'dev_server_stop_failed', env.error?.message ?? '`tanqory theme dev --stop` failed.', env.error?.hint, { stderr: env.stderrTail })
+    // a child of ours exits on its own once stopped; wait for it so the next start finds the port free
+    for (const c of [...this.children]) {
+      if (env.data?.pid === c.pid) await Promise.race([new Promise((r) => c.once('exit', r)), sleep(10_000)])
+    }
+    return env.data ?? { stopped: false }
+  }
+
+  /** On MCP shutdown: stop the dev servers this server started (never any other). */
+  async close() {
+    const kids = [...this.children]
+    if (!kids.length) return
+    await this.stop().catch(() => {})
+    for (const c of kids) if (c.exitCode === null && c.signalCode === null) c.kill('SIGTERM')
+  }
+}

package/src/devserver.mjs

@@ -32,7 +32,7 @@ const alive = (pid) => {
   }
 }
 
-const NOT_RUNNING_HINT = 'Start it yourself in the background from the theme folder: `npm run dev -- --mock` (offline fixture store; `npm run dev` when signed in with `npx tanqory login`), wait until dev_server_status says it is running, then call this tool again. Stop it later with `npm run dev -- --stop`, never pkill.'
+const NOT_RUNNING_HINT = 'Start it with the start_dev_server tool (mock: true = the offline fixture store), then call this tool again. Shell fallback: `npm run dev -- --mock` in the background. Stop it with stop_dev_server (or `npm run dev -- --stop`), never pkill.'
 
 /** The dev-server record, or a reason it cannot be used. Never throws. */
 export function readDevServer(root) {

package/src/sandbox.mjs

@@ -0,0 +1,13 @@
+/**
+ * Sandboxed agent shells. Some hosts run each shell command under an OS sandbox (Codex: macOS seatbelt, with
+ * CODEX_SANDBOX set in the command's environment). The build and the dev server run there, but headless Chromium does
+ * not: its Mach-port rendezvous is denied (`bootstrap_check_in … Permission denied`), so screenshots and the
+ * storefront checks fail or stall. The host starts MCP servers outside that sandbox, so the configured server's tools
+ * work; a copy an agent starts from its shell does not. Say so at once.
+ */
+export const SANDBOX_SIGNS = /bootstrap_check_in|MachPortRendezvous|Operation not permitted|sandbox_init|seatbelt/i
+export const SANDBOX_MESSAGE = 'You are in a sandboxed shell: headless Chromium cannot start here, so this server (started from that shell) cannot take screenshots or run the checks.'
+export const SANDBOX_HINT = 'Use the `tanqory` MCP tools your host configured (it runs them outside the sandbox). If they are not in your tool list, wait a few seconds and list your tools again. Do not start `tanqory mcp`, Playwright or `theme check` yourself from a sandboxed shell.'
+
+/** True when this process was started from a sandboxed agent shell. */
+export const inSandboxedShell = (env = process.env) => Boolean(env.CODEX_SANDBOX)

package/src/server.mjs

@@ -13,23 +13,29 @@ import { z } from 'zod'
 import { Browser, BrowserUnavailable, VIEWPORTS } from './browser.mjs'
 import { CliError, runCli } from './cli.mjs'
 import { DOCS, DocCorpus } from './docs.mjs'
+import { DevControl } from './devcontrol.mjs'
 import { DevServerError, devGet, readDevServer, requireDevServer } from './devserver.mjs'
-import { kitCatalogue, kitExamples } from './kit.mjs'
 import { registerPrompts } from './prompts.mjs'
 import { LAYOUTS, ScaffoldError, planSection, writeSection } from './scaffold.mjs'
 import { SCHEMA_KINDS, getSchema } from './schemas.mjs'
+import { SANDBOX_HINT, SANDBOX_MESSAGE, inSandboxedShell } from './sandbox.mjs'
 import { loadTheme } from './theme.mjs'
-import { validateManifestFile } from './manifest.mjs'
+
+// Only what a tool call needs is loaded on that call: the agent host waits for `initialize` before it lists the
+// tools, and some hosts (Codex) start the first turn without waiting at all.
+const kitModule = () => import('./kit.mjs')
+const manifestModule = () => import('./manifest.mjs')
 
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 
 const INSTRUCTIONS = `Tanqory theme development (Theme ABI v2). Use these tools, not only the shell, for every theme change:
-1. Start the dev server in the background and keep it running: \`npm run dev -- --mock\` (plain \`npm run dev\` when signed in). dev_server_status says when it is up.
+1. Start the dev server with start_dev_server (mock: true = offline fixture store; shell fallback \`npm run dev -- --mock\`). It rebuilds on every save; dev_server_status shows build errors.
 2. New section: scaffold_section (plan, then confirm with the planDigest). Kit APIs: search_docs / get_kit_example, not node_modules.
 3. Look at your work: screenshot (desktop and mobile, th and en) and get_page (HTML + console errors).
 4. Verify with check_theme, not \`npm run check\`: fix every failure it reports, including ones you did not cause, until passed is true.
-5. Stop the dev server with \`npm run dev -- --stop\` (the pid in .tanqory/dev-server.json). Never pkill, killall or a pid found by name.
-You are not done until check_theme passes and you have seen the change in a screenshot. Every storefront function (cart, variants, search, filters, markets, forms, SEO, i18n, live edit) comes from @tanqory/theme-kit; the theme owns markup and CSS. This server never calls a model, never takes a store id and never publishes.`
+5. Stop the dev server with stop_dev_server (shell fallback \`npm run dev -- --stop\`). Never pkill, killall or a pid found by name.
+Never start \`tanqory mcp\`, Playwright or \`theme check\` yourself from a sandboxed shell: Chromium cannot start there; these tools do it.
+You are not done until check_theme returned passed: true and you have seen the change in a screenshot; never say a check is green otherwise. Every storefront function (cart, variants, search, filters, markets, forms, SEO, i18n, live edit) comes from @tanqory/theme-kit; the theme owns markup and CSS. This server never calls a model, never takes a store id and never publishes.`
 
 const errorSchema = z.object({ code: z.string(), message: z.string(), hint: z.string().optional() }).passthrough()
 const base = { ok: z.boolean().describe('false when the tool could not do what was asked; see error'), error: errorSchema.optional() }
@@ -86,7 +92,7 @@ function checkResult(env, requestedTier) {
     ...shown.map((f) => `- [${f.tier}] ${f.checkId}${f.file ? ` ${f.file}${f.line ? `:${f.line}` : ''}` : ''}${f.route ? ` route ${f.route}` : ''}${f.locale ? ` (${f.locale})` : ''}: ${f.message}${f.hint ? `\n    fix: ${f.hint}` : ''}`),
     ...(failures.length > shown.length ? [`… ${failures.length - shown.length} more (structuredContent.failures is complete)`] : []),
     ...(passed
-      ? ['Next: if you have not looked at your change yet, call screenshot on the page you changed (viewport desktop and mobile). Stop the dev server with `npm run dev -- --stop` when you are finished, never pkill.']
+      ? ['Next: if you have not looked at your change yet, call screenshot on the page you changed (viewport desktop and mobile). Stop the dev server with stop_dev_server when you are finished, never pkill.']
       : ['Fix every failure above, including ones you did not cause (look a check up with search_docs {query: "<checkId>"}), then call check_theme again.']),
   ]
   return {
@@ -105,6 +111,14 @@ export function createTanqoryMcpServer(options = {}) {
   const corpus = new DocCorpus(theme)
   const browser = new Browser(theme.root, log)
   const cliOpts = { root: theme.root, cli: options.cli }
+  const devControl = new DevControl({ root: theme.root, cli: options.cli, log })
+  // Started from a sandboxed agent shell (not by the host): Chromium cannot launch here, so the browser and check
+  // tools say so at once instead of failing minutes later.
+  const sandboxed = inSandboxedShell()
+  if (sandboxed) log(`${SANDBOX_MESSAGE} ${SANDBOX_HINT}`)
+  const refuseInSandbox = () => {
+    if (sandboxed) throw new BrowserUnavailable(SANDBOX_MESSAGE, SANDBOX_HINT, 'sandboxed_shell')
+  }
   const server = new McpServer({ name: 'tanqory', title: 'Tanqory theme development', version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { logging: {} } })
 
   const needTheme = () => {
@@ -201,6 +215,7 @@ export function createTanqoryMcpServer(options = {}) {
     const ex = DOCS.find((x) => x.id === 'kit/exports')
     const docText = await corpus.read(d)
     const exportsText = await corpus.read(ex)
+    const { kitCatalogue } = await kitModule()
     return kitCatalogue({ docText: docText?.text, exportsDts: exportsText?.text, installedVersion: theme.versions['@tanqory/theme-kit'], source: docText?.source })
   }
 
@@ -247,6 +262,7 @@ export function createTanqoryMcpServer(options = {}) {
       const c = await catalogue()
       const api = c.components.find((x) => x.name.toLowerCase() === name.toLowerCase()) ?? null
       const canonical = api?.name ?? name
+      const { kitExamples } = await kitModule()
       const examples = kitExamples({ name: canonical, themeRoot: theme.root, limit: limit ?? 2 })
       if (!api && !examples.length) return fail('unknown_kit_name', `"${name}" is not a kit API this server knows and no code uses it.`, 'list_kit_components lists every name; search_docs finds prose.')
       const text = [
@@ -322,6 +338,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
       annotations: READ,
     },
     guard(async () => {
+      const { validateManifestFile } = await manifestModule()
       const r = await validateManifestFile(needTheme(), theme.versions['@tanqory/theme-abi'])
       if (r.error) return fail(r.error.code, r.error.message, r.error.hint)
       const text = r.valid ? `manifest valid (${r.manifestPath}, @tanqory/theme-abi ${r.abiVersion})` : [`manifest INVALID: ${r.errors.length} problem(s)`, ...r.errors.map((e) => `- ${e.path}: ${e.message}${e.file ? ` (${e.file}:${e.line})` : ''}${e.hint ? `\n    fix: ${e.hint}` : ''}`)].join('\n')
@@ -345,6 +362,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
     },
     guard(async ({ tier }) => {
       needTheme()
+      refuseInSandbox()
       const env = await runCli(['theme', 'check', ...(tier ? ['--tier', tier] : [])], cliOpts)
       return checkResult(env, tier)
     }),
@@ -362,6 +380,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
     },
     guard(async () => {
       needTheme()
+      refuseInSandbox()
       return checkResult(await runCli(['theme', 'check', '--tier', 'storefront'], cliOpts), 'storefront')
     }),
   )
@@ -372,7 +391,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
     {
       title: 'Is `tanqory theme dev` running?',
       description:
-        "Read .tanqory/dev-server.json and ask the running dev server for /__tq/status: url, store, mode (store = real dev-store data, mock = fixture data), the theme it serves and its last build with errors (file:line). Never starts or stops the dev server; when it is not running the answer says how to start it (in the background: `npm run dev -- --mock`).",
+        "Read .tanqory/dev-server.json and ask the running dev server for /__tq/status: url, store, mode (store = real dev-store data, mock = fixture data), the theme it serves and its last build with errors (file:line). Never starts or stops the dev server (start_dev_server / stop_dev_server do); when it is not running the answer says how to start it.",
       inputSchema: {},
       outputSchema: {
         ...base,
@@ -401,6 +420,59 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
     }),
   )
 
+  const devOut = {
+    ...base,
+    running: z.boolean().optional(),
+    alreadyRunning: z.boolean().optional(),
+    url: z.string().optional(),
+    port: z.number().optional(),
+    mode: z.string().optional(),
+    store: z.any().optional(),
+    pid: z.number().optional(),
+    editor: z.string().optional(),
+    lastBuild: z.any().optional(),
+    log: z.string().optional(),
+  }
+  server.registerTool(
+    'start_dev_server',
+    {
+      title: 'Start `tanqory theme dev`',
+      description:
+        "Start the theme's dev server (`tanqory theme dev`) on http://localhost:9292 and wait until it serves: workerd under the platform's production shim, rebuilt on every save, the editor at /__editor. mock: true uses the offline fixture store; without it, the store this theme is linked to (needs `npx tanqory login` in a terminal first). Returns the url, pid and last build. Already running: returns that one. Use this instead of starting it from a shell: this server runs it outside any shell sandbox, so screenshot, get_page and stop_dev_server can always reach it. It is stopped when this MCP server shuts down.",
+      inputSchema: {
+        mock: z.boolean().optional().describe('true = the offline fixture store (no login needed); default false = the linked store'),
+        port: z.number().int().min(1024).max(65535).optional().describe('Port on localhost (default 9292)'),
+      },
+      outputSchema: devOut,
+      // openWorldHint false: it starts a local process. (Codex asks for approval on any non-read-only tool with an
+      // open-world or destructive hint, and `codex exec` never approves: P3e run C1 lost every screenshot to that.)
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    guard(async ({ mock, port }) => {
+      needTheme()
+      const r = await devControl.start({ mock: !!mock, port })
+      const text = [`Dev server ${r.alreadyRunning ? 'already running' : 'started'}: ${r.url} (${r.mode}${r.store?.handle ? `, store ${r.store.handle}` : ''}, pid ${r.pid}); editor ${r.editor}`, `last build: ${r.lastBuild?.ok === false ? 'FAILED' : 'ok'}`, ...(r.lastBuild?.errors ?? []).map((e) => `- ${e.file ?? '?'}${e.line ? `:${e.line}` : ''}: ${e.message}`), 'Next: screenshot / get_page the page you change. Stop it with stop_dev_server when you are finished.'].join('\n')
+      return done(r, text)
+    }),
+  )
+  server.registerTool(
+    'stop_dev_server',
+    {
+      title: 'Stop `tanqory theme dev`',
+      description:
+        "Stop this theme's dev server, and only it: `tanqory theme dev --stop` (an authenticated POST /__tq/stop with the token in .tanqory/dev-server.json, else a signal to its verified pid). Works whoever started it, including a sandboxed shell. Never stops a process by name. Not running: stopped is false with the reason.",
+      inputSchema: {},
+      outputSchema: { ...base, stopped: z.boolean().optional(), reason: z.string().optional(), pid: z.number().optional(), url: z.string().optional(), via: z.string().optional() },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    guard(async () => {
+      needTheme()
+      const r = await devControl.stop()
+      const text = r.stopped ? `Stopped the dev server (pid ${r.pid}, ${r.url}${r.via ? `, via ${r.via}` : ''}).` : `No dev server was running (${r.reason ?? 'not_running'}).`
+      return done({ stopped: !!r.stopped, ...(r.reason ? { reason: r.reason } : {}), ...(r.pid ? { pid: r.pid } : {}), ...(r.url ? { url: r.url } : {}), ...(r.via ? { via: r.via } : {}) }, text)
+    }),
+  )
+
   const pageArgs = {
     path: z.string().regex(/^\//, 'must start with /').max(500).describe('Storefront path, e.g. "/", "/products/linen-shirt", "/collections/all?sort=price-asc"'),
     locale: z.string().max(10).optional().describe('Language, e.g. "th" or "en"'),
@@ -442,6 +514,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
       const consoleErrors = [...(page.consoleErrors ?? []).map((m) => (typeof m === 'string' ? { kind: 'server-reported', message: m } : m))]
       let browserInfo = { available: true }
       try {
+        refuseInSandbox()
         const r = await browser.withPage(browserUrl(rec.url, { path, locale, market }), { viewport: viewport ?? 'desktop' }, async () => null)
         consoleErrors.push(...r.errors.map((e) => ({ ...e, kind: `browser-${e.kind}` })))
       } catch (e) {
@@ -465,6 +538,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
       annotations: READ,
     },
     guard(async ({ path, locale, market, viewport, fullPage }) => {
+      refuseInSandbox()
       const rec = requireDevServer(theme.root)
       const url = browserUrl(rec.url, { path, locale, market })
       const r = await browser.withPage(url, { viewport }, async (page) => {
@@ -491,7 +565,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
     {
       title: 'List your development stores',
       description:
-        "The development stores your Tanqory login can use (`tanqory stores --json`), and which one this theme is linked to (tanqory.config.json). Read-only; it never creates a store and never takes a store id. When you are not logged in the answer says to run `tanqory login` in a terminal.",
+        "The development stores of your Tanqory developer login, plus any store you signed in to (`tanqory stores --json`; each row has `type` 'development' or 'store'), and which one this theme is linked to (tanqory.config.json). Read-only; it never creates a store and never takes a store id. When you are not logged in the answer says to run `tanqory login` in a terminal; a developer with no development store yet can ask the user to run `tanqory stores create --dev --name \"<name>\"` (free, no card).",
       inputSchema: {},
       outputSchema: { ...base, stores: z.array(z.any()).optional(), linked: z.any().optional(), raw: z.any().optional() },
       annotations: { ...READ, openWorldHint: true },
@@ -589,6 +663,7 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
   const close = server.close.bind(server)
   server.close = async () => {
     await browser.close()
+    await devControl.close()
     await close()
   }
   return { server, theme, browser }