@tanqory/dev-mcp 0.1.0 → 0.1.3

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,12 +68,16 @@ 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.                                                                                                                                                                                                                                                                                          |
 | `get_store_data_summary`                                                                | Calls `GET /__tq/store-summary` on the dev server: the products, collections, markets, languages and content you can design against.                                                                                                                                                                                                                                 |
-| `push_draft`, `get_build_status`, `get_preview_url`                                     | **Always refuse today** with `draft_push_unavailable`. The platform's build lane for developer themes is not live yet. These tools never upload, never install, never publish and never invent a URL.                                                                                                                                                                |
+| `push_draft {confirm?, planDigest?}`                                                    | Two steps. Without `confirm`: runs `tanqory theme push --build-only --dry-run` and returns the plan (files, bytes, sha256, target development store, `planDigest`); nothing is uploaded. With `confirm: true` and that `planDigest`: runs `tanqory theme push --build-only --plan-digest <d>`: the platform builds the theme in its sandboxed lane, runs conformance and signs it, **private to your development store**. `plan_changed` if the theme changed in between. Nothing is installed or published. |
+| `get_build_status {buildId?}`                                                           | Runs `tanqory theme builds [--id <buildId>] --json`: one build (status, verdict, conformance summary, signature, error) or the store's recent builds and the daily quota.                                                                                                                                                                                             |
+| `get_preview_url`                                                                       | **Refuses today** with `preview_unavailable`: a pushed build is not installed as a draft yet, so no preview URL exists. It never invents one.                                                                                                                                                                                                                        |
 
 **Prompts:** `new-theme`, `new-section`, `fix-check-report` and `port-from-another-template-language`.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanqory/dev-mcp",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "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.3"
+    "create-tanqory-theme": "0.2.6"
   },
   "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; push_draft builds and signs privately for your development store and installs nothing.`
 
 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 },
@@ -523,49 +597,97 @@ Two steps: call WITHOUT confirm to get the plan (every file, full new contents,
     }),
   )
 
-  // ── draft push (backend not live yet: typed refusals) ─────────────────────
-  const REFUSAL = {
-    code: 'draft_push_unavailable',
+  // ── platform builds (P5): push_draft builds + signs privately; install/preview arrive with P6 ──
+  const PREVIEW_REFUSAL = {
+    code: 'preview_unavailable',
     message:
-      "Pushing a theme draft is not available yet: the platform's sandboxed build lane for developer themes, draft install and preview channel are not live. Nothing was uploaded, built, installed or published, and no preview URL exists.",
-    hint: 'Keep developing locally: `tanqory theme dev` + check_theme until every tier passes. When `tanqory theme push` ships, this tool will wrap it with the same two-step confirm.',
-    instead: ['tanqory theme dev (localhost with store data)', 'check_theme (all tiers)', 'screenshot / get_page against the dev server'],
+      'Installing a pushed theme as an unpublished draft, and its preview URL, are not available yet: push_draft builds, checks and signs the theme privately for your development store, and installs nothing. No preview URL exists, so none is returned.',
+    hint: 'Use localhost (dev_server_status / screenshot) to look at the theme. push_draft + get_build_status tell you whether the platform build passed.',
+  }
+  const buildOut = { ...base, mode: z.string().optional(), planDigest: z.string().optional(), buildId: z.string().optional(), verdict: z.string().optional(), build: z.any().optional(), store: z.any().optional(), theme: z.any().optional(), upload: z.any().optional(), notUploaded: z.any().optional(), builds: z.array(z.any()).optional(), quota: z.any().optional() }
+  const buildLines = (b) => {
+    const c = b?.conformance ?? {}
+    return [
+      `build ${b?.id}: ${b?.status} (verdict ${b?.verdict})${b?.signed ? ', signed' : ''}, private to store ${b?.storeId}`,
+      ...(c.status ? [`conformance: ${c.status}${c.basis ? ` on the ${c.basis}` : ''}`] : []),
+      ...(c.warnings ?? []).map((w) => `budget warning: ${w.name} ${w.value} ${w.unit} (budget ${w.budget})`),
+      ...(b?.error ? [`${b.status}: [${b.error.kind}${b.error.code ? `/${b.error.code}` : ''}] ${b.error.message}${b.error.path ? ` (${b.error.path})` : ''}`] : []),
+    ]
   }
-  const refusalOut = { ...base, refused: z.literal(true).optional() }
-  const refuse = () => ({ isError: true, content: [{ type: 'text', text: `${REFUSAL.code}: ${REFUSAL.message}\nWhat to do instead: ${REFUSAL.instead.join('; ')}. ${REFUSAL.hint}` }], structuredContent: { ok: false, refused: true, error: REFUSAL } })
 
   server.registerTool(
     'push_draft',
     {
-      title: 'Push the theme as an unpublished draft (not available yet)',
-      description: `Would upload the theme for a sandboxed platform build and install it as an UNPUBLISHED draft on your dev store (two-step: a plan, then confirm). ALWAYS REFUSES TODAY with ${REFUSAL.code}: the platform build lane is not live. It never uploads, never installs, never publishes, and never returns a preview URL. Do not report a push as done.`,
-      inputSchema: { confirm: z.boolean().optional().describe('Second step (refused today)'), planDigest: z.string().optional() },
-      outputSchema: refusalOut,
-      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+      title: 'Build the theme on the platform (private, signed; installs nothing)',
+      description:
+        'Uploads the theme SOURCE (git-tracked files, .gitignore respected; node_modules, dist, reports, .tanqory/dev and credential files are never uploaded) to the platform\'s sandboxed build lane for your linked DEVELOPMENT store, and waits for build → conformance → signing (`tanqory theme push --build-only`). Two steps: call WITHOUT confirm to get the plan (files, bytes, sha256, target store, planDigest; nothing is uploaded). Then call again with confirm: true and that planDigest; if the theme changed in between it refuses with plan_changed. The result is a signed build PRIVATE to that development store: nothing is installed, previewed or published, and there is no preview URL yet. Run check_theme first: a theme that fails it fails the platform build too. Needs a developer login (`tanqory login`) and a linked development store.',
+      inputSchema: {
+        confirm: z.boolean().optional().describe('true = upload the plan identified by planDigest'),
+        planDigest: z.string().max(100).optional().describe('From the plan step; required with confirm: true'),
+      },
+      outputSchema: buildOut,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     },
-    guard(async () => refuse()),
+    guard(async ({ confirm, planDigest }) => {
+      const root = needTheme()
+      if (!confirm) {
+        const env = await runCli(['theme', 'push', '--build-only', '--dry-run'], { ...cliOpts, root })
+        if (!env.ok) return fail(env.error?.code ?? 'push_plan_failed', env.error?.message ?? '`tanqory theme push --dry-run` failed', env.error?.hint)
+        const d = env.data ?? {}
+        const text = [
+          `PLAN (nothing uploaded): ${d.upload?.files} files, ${d.upload?.bytes} bytes, sha256 ${String(d.upload?.sha256 ?? '').slice(0, 12)}…, theme "${d.theme?.handle}" → development store ${d.store?.handle ?? d.store?.id}.`,
+          ...(d.notUploaded?.secrets?.length ? [`Never uploaded (look like credentials): ${d.notUploaded.secrets.join(', ')}`] : []),
+          `To build it, call push_draft again with confirm: true, planDigest: "${d.planDigest}". The build is private to that development store; nothing is installed.`,
+        ].join('\n')
+        return done({ mode: 'plan', planDigest: d.planDigest, store: d.store, theme: d.theme, upload: d.upload, notUploaded: d.notUploaded }, text)
+      }
+      if (!planDigest) return fail('plan_digest_required', 'confirm: true needs the planDigest of a plan you reviewed.', 'Call push_draft without confirm first.')
+      const env = await runCli(['theme', 'push', '--build-only', '--plan-digest', planDigest], { ...cliOpts, root, timeoutMs: 25 * 60 * 1000 })
+      const d = env.data ?? {}
+      if (!env.ok) {
+        const lines = d.build ? buildLines(d.build) : []
+        return {
+          isError: true,
+          content: [{ type: 'text', text: [`${env.error?.code}: ${env.error?.message}`, ...lines, env.error?.hint ? `What to do: ${env.error.hint}` : ''].filter(Boolean).join('\n') }],
+          structuredContent: { ok: false, error: env.error ?? { code: 'push_failed', message: 'push failed' }, ...(d.build ? { mode: 'build', buildId: d.build.id, verdict: d.build.verdict, build: d.build, store: d.store, theme: d.theme } : {}), ...(d.planDigest ? { planDigest: d.planDigest } : {}) },
+        }
+      }
+      return done(
+        { mode: 'build', planDigest: d.planDigest, buildId: d.buildId, verdict: d.verdict, build: d.build, store: d.store, theme: d.theme, upload: d.upload, quota: d.quota },
+        [...buildLines(d.build), 'Nothing was installed or published; there is no preview URL yet. Follow up with get_build_status if it is still pending.'].join('\n'),
+      )
+    }),
   )
   server.registerTool(
     'get_build_status',
     {
-      title: 'Status of a pushed draft build (not available yet)',
-      description: `Would report the platform build of a pushed draft. ALWAYS REFUSES TODAY with ${REFUSAL.code}: no draft can be pushed yet, so no build exists.`,
-      inputSchema: { buildId: z.string().max(100).optional() },
-      outputSchema: refusalOut,
+      title: 'Status of your platform theme builds',
+      description:
+        'With buildId: that build of your linked development store (status, verdict, conformance summary, signature, error with kind/code/path). Without: the store\'s recent builds and the daily build quota (`tanqory theme builds --json`). Read-only.',
+      inputSchema: { buildId: z.string().uuid().optional().describe('From push_draft; omit for the recent builds') },
+      outputSchema: buildOut,
       annotations: { ...READ, openWorldHint: true },
     },
-    guard(async () => refuse()),
+    guard(async ({ buildId }) => {
+      const root = needTheme()
+      const env = await runCli(['theme', 'builds', ...(buildId ? ['--id', buildId] : [])], { ...cliOpts, root })
+      if (!env.ok) return fail(env.error?.code ?? 'builds_failed', env.error?.message ?? '`tanqory theme builds` failed', env.error?.hint)
+      const d = env.data ?? {}
+      if (buildId) return done({ buildId, verdict: d.build?.verdict, build: d.build, store: d.store }, buildLines(d.build).join('\n'))
+      const builds = d.builds ?? []
+      return done({ builds, store: d.store, quota: d.quota }, [`${builds.length} recent build(s) for ${d.store?.handle ?? d.store?.id}; ${d.quota?.used ?? '?'} of ${d.quota?.limit ?? '?'} used in 24 h`, ...builds.map((b) => `- ${b.id} ${b.status} (${b.verdict})${b.theme?.handle ? ` theme ${b.theme.handle}` : ''} ${b.createdAt}`)].join('\n'))
+    }),
   )
   server.registerTool(
     'get_preview_url',
     {
       title: 'Preview URL of a draft (not available yet)',
-      description: `Would return the shareable preview and editor URLs of a pushed draft. ALWAYS REFUSES TODAY with ${REFUSAL.code}: there is no draft and no preview URL. Never invent one; localhost (dev_server_status) is the only preview today.`,
+      description: `Would return the shareable preview and editor URLs of an installed draft. ALWAYS REFUSES TODAY with ${PREVIEW_REFUSAL.code}: push_draft builds and signs privately but installs nothing, so no preview URL exists. Never invent one; localhost (dev_server_status) is the only preview today.`,
       inputSchema: {},
-      outputSchema: refusalOut,
+      outputSchema: { ...base, refused: z.literal(true).optional() },
       annotations: { ...READ, openWorldHint: true },
     },
-    guard(async () => refuse()),
+    guard(async () => ({ isError: true, content: [{ type: 'text', text: `${PREVIEW_REFUSAL.code}: ${PREVIEW_REFUSAL.message}\nWhat to do instead: ${PREVIEW_REFUSAL.hint}` }], structuredContent: { ok: false, refused: true, error: PREVIEW_REFUSAL } })),
   )
 
   // ── resources: every document as tanqory://docs/<id> ──────────────────────
@@ -589,6 +711,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 }