@akira-tl/forgerelay 0.5.6 → 0.6.0

package/scripts/debug/accept.mjs

@@ -120,7 +120,7 @@ try {
   assert.match(serverInstructions, /Shell commands may modify ordinary project files/);
   assert.match(serverInstructions, /\/etc\/sudoers/);
   assert.match(serverInstructions, /configuration files through shell only when the user's request explicitly calls for that configuration change/);
-  assert.match(serverInstructions, /managed-worktrees capability guide/);
+  assert.match(serverInstructions, /Project-work order: open_workspace if needed → activity_panel\(workspaceId\) once → work tools/);
   assert.ok(serverInstructions.length < 3_000, `server instructions should stay compact, got ${serverInstructions.length} characters`);
   assert.doesNotMatch(serverInstructions, /fast-forwards the original target branch/);
   assert.doesNotMatch(serverInstructions, /Do not create or modify files with bash/);
@@ -146,6 +146,10 @@ try {
   const toolNames = tools.map((tool) => tool.name);
   assert.deepEqual(toolNames, [
     "open_workspace",
+    "activity_panel",
+    "activity_snapshot",
+    "activity_detail",
+    "activity_output",
     "capability",
     "close_workspace",
     "read",
@@ -176,14 +180,13 @@ try {
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityGuides);
   const capabilityTool = tools.find((tool) => tool.name === "capability");
   assert.deepEqual(capabilityTool?._meta?.["openai/fileParams"], ["file"]);
-  const templateUri = capabilityTool?._meta?.ui?.resourceUri;
+  const activityPanelTool = tools.find((tool) => tool.name === "activity_panel");
+  const activityTemplateUri = activityPanelTool?._meta?.ui?.resourceUri;
   assert.match(
-    templateUri ?? "",
-    /^ui:\/\/forgerelay\/workspace-app-[0-9a-f]{12}\.html$/,
-    JSON.stringify(bashTool ?? {}),
+    activityTemplateUri ?? "",
+    /^ui:\/\/forgerelay\/activity-panel-app-[0-9a-f]{12}\.html$/,
   );
-  assert.deepEqual(capabilityTool?._meta?.ui?.visibility, ["model", "app"]);
-  assert.equal(capabilityTool?._meta?.["openai/outputTemplate"], templateUri);
+  assert.deepEqual(activityPanelTool?._meta?.ui?.visibility, ["model", "app"]);
   pass("MCP tools/list", `${toolNames.length} tools: ${toolNames.join(", ")}`);
 
   const resources = mcpRequest(oauth.accessToken, sessionId, {
@@ -192,9 +195,13 @@ try {
     method: "resources/list",
     params: {},
   }).message.result.resources;
-  const currentResource = resources.find((resource) => resource.uri === templateUri);
-  assert.ok(currentResource);
-  assert.equal(currentResource._meta?.ui?.domain, debugBaseUrl);
+  const currentActivityResource = resources.find((resource) => resource.uri === activityTemplateUri);
+  assert.ok(currentActivityResource);
+  assert.equal(currentActivityResource._meta?.ui?.domain, debugBaseUrl);
+  assert.equal(
+    resources.some((resource) => /^ui:\/\/forgerelay\/workspace-lifecycle-app-/.test(resource.uri)),
+    false,
+  );
   assert.ok(resources.some((resource) => resource.uri === "ui://forgerelay/workspace-app.html"));
 
   const resourceTemplates = mcpRequest(oauth.accessToken, sessionId, {
@@ -204,7 +211,10 @@ try {
     params: {},
   }).message.result.resourceTemplates;
   assert.ok(resourceTemplates.some(
-    (resourceTemplate) => resourceTemplate.uriTemplate === "ui://forgerelay/workspace-app-{revision}.html",
+    (resourceTemplate) => resourceTemplate.uriTemplate === "ui://forgerelay/workspace-lifecycle-app-{revision}.html",
+  ));
+  assert.ok(resourceTemplates.some(
+    (resourceTemplate) => resourceTemplate.uriTemplate === "ui://forgerelay/activity-panel-app-{revision}.html",
   ));
 
   const readTemplate = (id, uri) => mcpRequest(oauth.accessToken, sessionId, {
@@ -214,28 +224,21 @@ try {
     params: { uri },
   }).message.result.contents[0];
 
-  const template = readTemplate(23, templateUri);
-  assert.equal(template.uri, templateUri);
-  assert.equal(template.mimeType, "text/html;profile=mcp-app");
-  assert.match(template.text ?? "", /<script type="module" crossorigin src="[^"]+\/mcp-app-assets\//);
-  assert.equal(template._meta?.ui?.domain, debugBaseUrl);
-  assert.ok(template._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
-  const scriptUrl = template.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
+  const activityTemplate = readTemplate(24, activityTemplateUri);
+  assert.equal(activityTemplate.uri, activityTemplateUri);
+  assert.equal(activityTemplate.mimeType, "text/html;profile=mcp-app");
+  assert.match(activityTemplate.text ?? "", /activity-panel-app-[^\"]+\.js/);
+  assert.equal(activityTemplate._meta?.ui?.domain, debugBaseUrl);
+  assert.ok(activityTemplate._meta?.ui?.csp?.resourceDomains?.includes(debugBaseUrl));
+  const scriptUrl = activityTemplate.text?.match(/<script type="module" crossorigin src="([^"]+)"/)?.[1];
   assert.ok(scriptUrl);
   const scriptAsset = curlRequest({ method: "GET", url: scriptUrl });
   assert.equal(scriptAsset.status, 200, scriptAsset.body);
 
-  const legacyTemplate = readTemplate(24, "ui://forgerelay/workspace-app.html");
+  const legacyTemplate = readTemplate(25, "ui://forgerelay/workspace-app.html");
   assert.equal(legacyTemplate.uri, "ui://forgerelay/workspace-app.html");
   assert.equal(legacyTemplate.mimeType, "text/html;profile=mcp-app");
-  assert.equal(legacyTemplate.text, template.text);
-
-  const historicalUri = "ui://forgerelay/workspace-app-0.2.4.html";
-  const historicalTemplate = readTemplate(25, historicalUri);
-  assert.equal(historicalTemplate.uri, historicalUri);
-  assert.equal(historicalTemplate.mimeType, "text/html;profile=mcp-app");
-  assert.equal(historicalTemplate.text, template.text);
-  pass("MCP app template", `${templateUri} + legacy/history compatibility -> ${scriptUrl}`);
+  pass("MCP app templates", `${activityTemplateUri} + historical compatibility templates`);
 
   const workspaceConversationMeta = { "openai/session": "acceptance-workspace" };
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
@@ -259,6 +262,7 @@ try {
       "hooks.lifecycle",
       "capability-guides.read",
       "code.intelligence",
+      "batch.execute",
       ...(process.platform === "linux" ? ["artifact.native-download"] : []),
       "ui.mcp-app",
       "review.changes",
@@ -269,6 +273,7 @@ try {
     "hooks.check",
     "review.changes",
     "code.intelligence",
+    "batch.execute",
     ...(process.platform === "linux" ? ["artifact.download"] : []),
   ]);
   assert.equal(capabilityCatalog[0].available, true);
@@ -398,6 +403,7 @@ try {
     "host-integration",
     "shell-processes",
     "code-intelligence",
+    "batch-execution",
   ]);
   const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {
     workspaceId,
@@ -407,6 +413,52 @@ try {
   assert.match(hooksGuide.structuredContent.result, /BeforeWorktreeClose/);
   pass("open_workspace", `${workspaceId} -> ${capabilityCatalog.length} capabilities + ${capabilityGuides.length} capability guides`);
 
+  const unifiedPanel = callTool(oauth.accessToken, sessionId, 89, "activity_panel", {
+    workspaceId,
+  }, workspaceConversationMeta);
+  assert.equal(unifiedPanel.isError, undefined);
+  assert.equal(
+    unifiedPanel._meta?.["forgerelay/activityPanelWorkspace"]?.workspaceId,
+    workspaceId,
+  );
+  assert.equal(
+    unifiedPanel._meta?.["forgerelay/activityPanelWorkspace"]?.root,
+    checkoutWorkspace,
+  );
+  pass("unified ForgeRelay Panel", `${workspaceId} -> Workspace + Activity`);
+
+  const inspectorActivityPath = join(checkoutWorkspace, "inspector-activity.txt");
+  writeFileSync(inspectorActivityPath, "inspector transport-scoped activity\n");
+  try {
+    const inspectorPanel = callTool(oauth.accessToken, sessionId, 90, "activity_panel", {
+      workspaceId,
+    });
+    const inspectorTurnId = inspectorPanel.structuredContent.turnId;
+    const inspectorRead = callTool(oauth.accessToken, sessionId, 91, "read", {
+      workspaceId,
+      path: "inspector-activity.txt",
+      offset: 1,
+      limit: 2,
+    });
+    assert.equal(inspectorRead.isError, undefined);
+    const inspectorSnapshot = callTool(oauth.accessToken, sessionId, 92, "activity_snapshot", {
+      turnId: inspectorTurnId,
+    });
+    assert.equal(inspectorSnapshot.isError, undefined);
+    assert.ok(inspectorSnapshot.structuredContent.revision > 0);
+    assert.deepEqual(
+      inspectorSnapshot.structuredContent.activities.map(({ tool, workspaceId: activityWorkspaceId, target }) => ({
+        tool,
+        workspaceId: activityWorkspaceId,
+        target,
+      })),
+      [{ tool: "read", workspaceId, target: "inspector-activity.txt" }],
+    );
+    pass("Inspector-style Activity scope", `${sessionId} -> ${inspectorTurnId} -> read captured`);
+  } finally {
+    rmSync(inspectorActivityPath, { force: true });
+  }
+
   const written = callTool(oauth.accessToken, sessionId, 4, "write", {
     workspaceId,
     path: "acceptance.txt",

package/scripts/debug/host/run.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$repo_root"
+
+debug_host_port="${FORGERELAY_DEBUG_HOST_PORT:-7677}"
+inspector_client_port="${MCP_INSPECTOR_CLIENT_PORT:-6274}"
+inspector_sandbox_port="${MCP_INSPECTOR_SANDBOX_PORT:-6275}"
+for port_value in "$debug_host_port" "$inspector_client_port" "$inspector_sandbox_port"; do
+  if [[ ! "$port_value" =~ ^[0-9]+$ ]] || (( port_value < 1 || port_value > 65535 )); then
+    echo "[forgerelay:debug-host] debug/Inspector ports must be integers from 1 to 65535." >&2
+    exit 1
+  fi
+done
+
+health_url="http://127.0.0.1:${debug_host_port}/healthz"
+mcp_url="http://127.0.0.1:${debug_host_port}/mcp"
+inspector_url="http://127.0.0.1:${inspector_client_port}"
+inspector_package="${MCP_INSPECTOR_PACKAGE:-@modelcontextprotocol/inspector@2.3.0}"
+inspector_node_dir="${MCP_INSPECTOR_NODE_DIR:-}"
+
+if [[ -z "$inspector_node_dir" ]]; then
+  current_node_major="$(node -p 'Number(process.versions.node.split(".")[0])')"
+  if (( current_node_major >= 25 )) && [[ -d "$HOME/.nvm/versions/node" ]]; then
+    inspector_node_dir="$(find "$HOME/.nvm/versions/node" -mindepth 1 -maxdepth 1 -type d -name 'v24.*' -printf '%p\n' 2>/dev/null | sort -V | tail -n 1)/bin"
+    if [[ "$inspector_node_dir" == "/bin" || ! -x "$inspector_node_dir/node" || ! -x "$inspector_node_dir/npx" ]]; then
+      inspector_node_dir=""
+    fi
+  fi
+fi
+
+inspector_path="$PATH"
+if [[ -n "$inspector_node_dir" ]]; then
+  if [[ ! -x "$inspector_node_dir/node" || ! -x "$inspector_node_dir/npx" ]]; then
+    echo "[forgerelay:debug-host] MCP_INSPECTOR_NODE_DIR must contain executable node and npx binaries." >&2
+    exit 1
+  fi
+  inspector_path="$inspector_node_dir:$PATH"
+fi
+
+if ! PATH="$inspector_path" command -v npx >/dev/null 2>&1; then
+  echo "[forgerelay:debug-host] npx is required to launch MCP Inspector." >&2
+  exit 1
+fi
+
+port_in_use() {
+  ss -H -ltn "sport = :$1" 2>/dev/null | grep -q .
+}
+
+if port_in_use "$debug_host_port"; then
+  cat >&2 <<EOF
+[forgerelay:debug-host] port ${debug_host_port} is already in use.
+[forgerelay:debug-host] refusing to replace or reuse that process because its publicBaseUrl/widgets may not match local Host mode.
+[forgerelay:debug-host] stop it, or temporarily set FORGERELAY_DEBUG_HOST_PORT to another loopback port.
+EOF
+  exit 1
+fi
+
+for inspector_port in "$inspector_client_port" "$inspector_sandbox_port"; do
+  if port_in_use "$inspector_port"; then
+    echo "[forgerelay:debug-host] Inspector port ${inspector_port} is already in use; refusing to replace that process." >&2
+    exit 1
+  fi
+done
+
+log_dir="$repo_root/logs"
+server_log="$log_dir/debug-host-server.log"
+inspector_log="$log_dir/debug-host-inspector.log"
+mkdir -p "$log_dir"
+: >"$server_log"
+: >"$inspector_log"
+
+server_pid=""
+inspector_pid=""
+cleanup() {
+  local status=$?
+  trap - EXIT INT TERM
+  if [[ -n "$inspector_pid" ]] && kill -0 "$inspector_pid" >/dev/null 2>&1; then
+    kill "$inspector_pid" >/dev/null 2>&1 || true
+    wait "$inspector_pid" >/dev/null 2>&1 || true
+  fi
+  if [[ -n "$server_pid" ]] && kill -0 "$server_pid" >/dev/null 2>&1; then
+    kill "$server_pid" >/dev/null 2>&1 || true
+    wait "$server_pid" >/dev/null 2>&1 || true
+  fi
+  exit "$status"
+}
+trap cleanup EXIT INT TERM
+
+FORGERELAY_DEBUG_HOST_PORT="$debug_host_port" \
+  node scripts/debug/host/serve.mjs > >(tee -a "$server_log") 2>&1 &
+server_pid=$!
+
+ready=0
+for _ in $(seq 1 120); do
+  if curl --silent --fail --max-time 1 "$health_url" >/dev/null 2>&1; then
+    ready=1
+    break
+  fi
+  if ! kill -0 "$server_pid" >/dev/null 2>&1; then
+    echo "[forgerelay:debug-host] ForgeRelay debug server exited before becoming ready." >&2
+    echo "[forgerelay:debug-host] see $server_log" >&2
+    exit 1
+  fi
+  sleep 0.25
+done
+
+if [[ "$ready" != "1" ]]; then
+  echo "[forgerelay:debug-host] ForgeRelay debug server did not become ready on ${debug_host_port}." >&2
+  echo "[forgerelay:debug-host] see $server_log" >&2
+  exit 1
+fi
+
+inspector_token="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
+
+echo "[forgerelay:debug-host] ForgeRelay ready: $mcp_url"
+echo "[forgerelay:debug-host] launching MCP Inspector Web Host via $inspector_package"
+if [[ -n "$inspector_node_dir" ]]; then
+  inspector_node_version="$(PATH="$inspector_path" node --version)"
+  echo "[forgerelay:debug-host] Inspector compatibility runtime: $inspector_node_version ($inspector_node_dir)"
+fi
+echo "[forgerelay:debug-host] complete OAuth with the persisted debug Owner password when prompted."
+echo "[forgerelay:debug-host] logs: $server_log and $inspector_log (Inspector tokens are redacted from the log)"
+
+HOST=127.0.0.1 \
+CLIENT_PORT="$inspector_client_port" \
+MCP_SANDBOX_PORT="$inspector_sandbox_port" \
+MCP_AUTO_OPEN_ENABLED=false \
+MCP_INSPECTOR_API_TOKEN="$inspector_token" \
+PATH="$inspector_path" \
+  npx -y "$inspector_package" --web --server-url "$mcp_url" --transport http \
+  > >(tee >(sed -E \
+      -e 's/(MCP_INSPECTOR_API_TOKEN=)[[:alnum:]]+/\1<redacted>/g' \
+      -e 's/(Auth token: )[[:alnum:]]+/\1<redacted>/g' \
+      >"$inspector_log")) 2>&1 &
+inspector_pid=$!
+
+inspector_ready=0
+for _ in $(seq 1 160); do
+  if curl --silent --fail --max-time 1 "$inspector_url/" >/dev/null 2>&1; then
+    inspector_ready=1
+    break
+  fi
+  if ! kill -0 "$inspector_pid" >/dev/null 2>&1; then
+    echo "[forgerelay:debug-host] MCP Inspector exited before becoming ready." >&2
+    echo "[forgerelay:debug-host] see $inspector_log" >&2
+    wait "$inspector_pid" || true
+    exit 1
+  fi
+  sleep 0.25
+done
+
+if [[ "$inspector_ready" != "1" ]]; then
+  echo "[forgerelay:debug-host] MCP Inspector did not become ready on ${inspector_client_port}." >&2
+  echo "[forgerelay:debug-host] see $inspector_log" >&2
+  exit 1
+fi
+
+encoded_mcp_url="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$mcp_url")"
+deep_link="${inspector_url}/?serverUrl=${encoded_mcp_url}&transport=http&autoConnect=${inspector_token}"
+
+echo "[forgerelay:debug-host] Inspector ready: $inspector_url"
+echo "[forgerelay:debug-host] MCP Apps sandbox: http://127.0.0.1:${inspector_sandbox_port}/sandbox"
+echo "[forgerelay:debug-host] open this one-shot local Host link:"
+echo "$deep_link"
+
+if [[ "${MCP_INSPECTOR_AUTO_OPEN:-1}" == "1" ]]; then
+  if command -v wslview >/dev/null 2>&1; then
+    wslview "$deep_link" >/dev/null 2>&1 || true
+  elif command -v xdg-open >/dev/null 2>&1; then
+    xdg-open "$deep_link" >/dev/null 2>&1 || true
+  fi
+fi
+
+set +e
+wait "$inspector_pid"
+inspector_status=$?
+set -e
+exit "$inspector_status"

package/scripts/debug/host/serve.mjs

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import {
+  createInteractiveDebugEnvironment,
+  repoRoot,
+} from "../runtime.mjs";
+
+const { configDir, env } = createInteractiveDebugEnvironment();
+const hostPort = parseHostPort(process.env.FORGERELAY_DEBUG_HOST_PORT);
+const localBaseUrl = `http://127.0.0.1:${hostPort}`;
+const localMcpUrl = `${localBaseUrl}/mcp`;
+
+// The normal interactive debug profile may mirror the product's public tunnel.
+// A local MCP Apps Host must instead receive localhost resource and asset URLs,
+// otherwise the Inspector ends up exercising the remote deployment again.
+env.HOST = "127.0.0.1";
+env.PORT = String(hostPort);
+env.FORGERELAY_PUBLIC_BASE_URL = localBaseUrl;
+env.FORGERELAY_WIDGETS = process.env.FORGERELAY_DEBUG_WIDGETS ?? "full";
+
+console.error("[forgerelay:debug-host] local MCP Apps Host server");
+console.error(`[forgerelay:debug-host] debug config: ${configDir}/config.json`);
+console.error(`[forgerelay:debug-host] health: ${localBaseUrl}/healthz`);
+console.error(`[forgerelay:debug-host] MCP: ${localMcpUrl}`);
+console.error(`[forgerelay:debug-host] public base override: ${localBaseUrl}`);
+console.error(`[forgerelay:debug-host] widgets: ${env.FORGERELAY_WIDGETS}`);
+console.error(`[forgerelay:debug-host] Owner password loaded from ${configDir}/auth.json`);
+console.error("[forgerelay:debug-host] all runtime state is under .forgerelay-debug/");
+
+const child = spawn(process.execPath, ["scripts/dev-server.mjs"], {
+  cwd: repoRoot,
+  env,
+  stdio: "inherit",
+});
+
+let stopping = false;
+function stop(signal = "SIGTERM") {
+  if (stopping) return;
+  stopping = true;
+  child.kill(signal);
+}
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => stop(signal));
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});
+
+function parseHostPort(value) {
+  if (value === undefined || value === "") return 7677;
+  if (!/^\d+$/.test(value)) {
+    throw new Error("FORGERELAY_DEBUG_HOST_PORT must be an integer from 1 to 65535.");
+  }
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("FORGERELAY_DEBUG_HOST_PORT must be an integer from 1 to 65535.");
+  }
+  return port;
+}

package/scripts/debug/runtime.mjs

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
-import { mkdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
@@ -15,6 +16,60 @@ export function createDebugOwnerToken() {
   return randomBytes(32).toString("base64url");
 }
 
+export function interactiveDebugConfigDir({ env = process.env, home = homedir() } = {}) {
+  const explicit = env.FORGERELAY_DEBUG_CONFIG_DIR;
+  if (explicit) return resolve(explicit.startsWith("~/") ? join(home, explicit.slice(2)) : explicit);
+  return resolve(join(home, ".forgerelay", "debug"));
+}
+
+function interactiveDebugOwnerToken(configDir) {
+  const authPath = join(configDir, "auth.json");
+  let auth;
+  try {
+    auth = JSON.parse(readFileSync(authPath, "utf8"));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Unable to load interactive debug Owner password from ${authPath}: ${reason}`);
+  }
+
+  const token = typeof auth.ownerToken === "string" ? auth.ownerToken.trim() : "";
+  if (!token) {
+    throw new Error(`Interactive debug Owner password is missing from ${authPath}.`);
+  }
+  return token;
+}
+
+export function createInteractiveDebugEnvironment({
+  env = process.env,
+  home = homedir(),
+} = {}) {
+  const configDir = interactiveDebugConfigDir({ env, home });
+  const ownerToken = interactiveDebugOwnerToken(configDir);
+  mkdirSync(debugRoot, { recursive: true });
+
+  const debugEnv = { ...env };
+  for (const key of Object.keys(debugEnv)) {
+    if (key === "HOST" || key === "PORT") {
+      delete debugEnv[key];
+      continue;
+    }
+    if (key.startsWith("DEVSPACE_")) {
+      delete debugEnv[key];
+      continue;
+    }
+    if (
+      key.startsWith("FORGERELAY_")
+      && !key.startsWith("FORGERELAY_LOG_")
+      && !key.startsWith("FORGERELAY_DEBUG_")
+    ) {
+      delete debugEnv[key];
+    }
+  }
+  debugEnv.FORGERELAY_CONFIG_DIR = configDir;
+
+  return { ownerToken, configDir, env: debugEnv };
+}
+
 export function createDebugEnvironment({
   ownerToken,
   stateDir = resolve(debugRoot, "state"),

package/scripts/debug/runtime.test.mjs

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { createInteractiveDebugEnvironment, interactiveDebugConfigDir } from "./runtime.mjs";
+
+async function withDebugConfig(t) {
+  const home = await mkdtemp(join(tmpdir(), "forgerelay-interactive-debug-"));
+  t.after(() => rm(home, { recursive: true, force: true }));
+  const configDir = join(home, ".forgerelay", "debug");
+  await mkdir(configDir, { recursive: true });
+  await writeFile(join(configDir, "config.json"), JSON.stringify({
+    host: "127.0.0.1",
+    port: 7677,
+    allowedRoots: [home],
+    allowedHosts: ["localhost", "127.0.0.1", "::1", "debug.example.test"],
+    publicBaseUrl: "https://debug.example.test/forgerelay/debug",
+  }) + "\n");
+  await writeFile(join(configDir, "auth.json"), JSON.stringify({
+    ownerToken: "debug-owner-password-123456",
+  }) + "\n");
+  return { home, configDir };
+}
+
+test("interactive debug uses one dedicated persisted config under ~/.forgerelay/debug", async (t) => {
+  const { home, configDir } = await withDebugConfig(t);
+  const result = createInteractiveDebugEnvironment({
+    env: {
+      HOST: "0.0.0.0",
+      PORT: "9999",
+      FORGERELAY_CONFIG_DIR: "/wrong/product/config",
+      FORGERELAY_PUBLIC_BASE_URL: "https://wrong.example.test",
+      FORGERELAY_ALLOWED_HOSTS: "wrong.example.test",
+      FORGERELAY_OAUTH_OWNER_TOKEN: "wrong-owner-password-123456",
+      FORGERELAY_WIDGETS: "off",
+      DEVSPACE_ALLOWED_ROOTS: "/wrong/root",
+      FORGERELAY_LOG_LEVEL: "debug",
+    },
+    home,
+  });
+
+  assert.equal(interactiveDebugConfigDir({ env: {}, home }), configDir);
+  assert.equal(result.ownerToken, "debug-owner-password-123456");
+  assert.equal(result.configDir, configDir);
+  assert.equal(result.env.FORGERELAY_CONFIG_DIR, configDir);
+  assert.equal(result.env.HOST, undefined);
+  assert.equal(result.env.PORT, undefined);
+  assert.equal(result.env.FORGERELAY_PUBLIC_BASE_URL, undefined);
+  assert.equal(result.env.FORGERELAY_ALLOWED_ROOTS, undefined);
+  assert.equal(result.env.FORGERELAY_ALLOWED_HOSTS, undefined);
+  assert.equal(result.env.FORGERELAY_OAUTH_OWNER_TOKEN, undefined);
+  assert.equal(result.env.FORGERELAY_WIDGETS, undefined);
+  assert.equal(result.env.DEVSPACE_ALLOWED_ROOTS, undefined);
+  assert.equal(result.env.FORGERELAY_LOG_LEVEL, "debug");
+});
+
+test("interactive debug config directory may be explicitly relocated without falling back to product config", async (t) => {
+  const { home } = await withDebugConfig(t);
+  const customDir = join(home, "custom-debug-config");
+  await mkdir(customDir, { recursive: true });
+  await writeFile(join(customDir, "config.json"), "{}\n");
+  await writeFile(join(customDir, "auth.json"), JSON.stringify({ ownerToken: "custom-debug-password-123456" }) + "\n");
+
+  const result = createInteractiveDebugEnvironment({
+    env: { FORGERELAY_DEBUG_CONFIG_DIR: customDir },
+    home,
+  });
+
+  assert.equal(result.configDir, customDir);
+  assert.equal(result.ownerToken, "custom-debug-password-123456");
+  assert.equal(result.env.FORGERELAY_CONFIG_DIR, customDir);
+});

package/scripts/debug/serve.mjs

@@ -1,14 +1,13 @@
 import { spawn } from "node:child_process";
-import { createDebugEnvironment, debugBaseUrl, debugConfigDir, debugHookLog, debugMcpUrl, repoRoot } from "./runtime.mjs";
+import { createInteractiveDebugEnvironment, debugBaseUrl, debugMcpUrl, repoRoot } from "./runtime.mjs";
 
-const { ownerToken, env } = createDebugEnvironment();
+const { configDir, env } = createInteractiveDebugEnvironment();
 
 console.error("[forgerelay:debug] local debug server");
-console.error(`[forgerelay:debug] config: ${debugConfigDir}/config.json`);
+console.error(`[forgerelay:debug] debug config: ${configDir}/config.json`);
 console.error(`[forgerelay:debug] health: ${debugBaseUrl}/healthz`);
 console.error(`[forgerelay:debug] MCP: ${debugMcpUrl}`);
-console.error(`[forgerelay:debug] hook log: ${debugHookLog}`);
-console.error(`[forgerelay:debug] Owner password: ${ownerToken}`);
+console.error(`[forgerelay:debug] Owner password loaded from ${configDir}/auth.json`);
 console.error("[forgerelay:debug] all runtime state is under .forgerelay-debug/");
 
 const child = spawn(process.execPath, ["scripts/dev-server.mjs"], {

package/scripts/dev-server.mjs

@@ -1,10 +1,11 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { readdirSync, statSync, watch } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
 const watchRoots = ["src"].map((entry) => join(repoRoot, entry));
+const uiRoot = join(repoRoot, "src", "ui");
 const restartDelayMs = 750;
 const crashDelayMs = 1500;
 
@@ -12,11 +13,32 @@ let child;
 let restartTimer;
 let stoppingForRestart = false;
 let shuttingDown = false;
+let uiBuildDirty = false;
 
 function log(message) {
   console.error(`[forgerelay:dev] ${message}`);
 }
 
+function buildUi() {
+  log("building MCP App UI");
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  const result = spawnSync(npm, ["run", "build:app"], {
+    cwd: repoRoot,
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.status === 0) {
+    uiBuildDirty = false;
+    return true;
+  }
+  log(`MCP App UI build failed (${result.signal ?? result.status ?? "unknown"})`);
+  return false;
+}
+
+function isUiSourcePath(path) {
+  return path === uiRoot || path.startsWith(`${uiRoot}${sep}`);
+}
+
 function start() {
   stoppingForRestart = false;
   child = spawn(process.execPath, ["--import", "tsx", "src/cli.ts", "serve"], {
@@ -44,6 +66,11 @@ function restart() {
   if (shuttingDown) return;
   clearTimeout(restartTimer);
 
+  if (uiBuildDirty && !buildUi()) {
+    scheduleRestart(crashDelayMs);
+    return;
+  }
+
   if (!child) {
     start();
     return;
@@ -76,6 +103,7 @@ function watchDirectory(root) {
 
       const path = join(dir, filename.toString());
       if (event === "rename") maybeAddDirectory(path);
+      if (isUiSourcePath(path)) uiBuildDirty = true;
       scheduleRestart();
     });
     watchers.push(watcher);
@@ -116,5 +144,6 @@ for (const root of watchRoots) {
   watchDirectory(root);
 }
 
-log("watching src; server restarts on changes and after crashes");
+log("watching src; UI changes rebuild MCP App assets before server restart");
+if (!buildUi()) process.exit(1);
 start();