@logicseek/hello-cc 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -16,6 +16,64 @@ the release description from the current changelog section. Use
 `npm run release:github` with `GH_TOKEN` or `GITHUB_TOKEN` only for local
 backfills.
 
+## 0.1.9
+
+### Summary
+
+hello-cc 0.1.9 publishes the post-0.1.8 Web runtime and provider shim
+hardening work. It tightens Web peer action identity, makes runtime cleanup
+safer, and keeps Claude/Codex shims from attaching unrelated projects to a
+global Web runtime.
+
+### Highlights
+
+- Hardened Web runtime cleanup so starting `hcc web` from a wrapper shell does
+  not terminate the current parent process chain while still removing stale
+  orphan runtimes for the same project.
+- Returned structured `BAD_REQUEST` JSON for malformed Web API request bodies
+  instead of surfacing raw JSON parse failures.
+- Replaced Web-runtime-token reuse for mutating peer actions with independent
+  per-session action tokens.
+- Changed provider shims to fall back to the real Claude/Codex CLI when no
+  current-project Web runtime is available.
+- Made provider shims use only the current project's `.hello-cc/runtime.json`
+  during managed launches, avoiding accidental attachment through a global Web
+  runtime from another project.
+- Kept shim-only environment variables out of restarted provider sessions.
+
+### Compatibility Notes
+
+- No breaking CLI command changes are intended in this release.
+- `hcc web --local` is still Web mode; use `hcc up` when you only want local
+  coordination commands without the Web console or shims.
+- Starting `claude` or `codex` in a directory without a local
+  `.hello-cc/runtime.json` now runs the real provider CLI instead of implicitly
+  using a global hello-cc Web runtime.
+
+### Validation
+
+The 0.1.9 release should be validated with:
+
+```bash
+git diff --check
+node --check bin/hcc.mjs
+find lib -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node --check scripts/github-release.mjs
+node --check scripts/regression.mjs
+node --check scripts/release-notes.mjs
+npm run release:check
+npm run release:github:dry-run -- --version 0.1.9
+npm pack --dry-run --json
+npm publish --dry-run --registry=https://registry.npmjs.org/ --access public
+npm test
+```
+
+The expected full regression marker is:
+
+```text
+FULL_REGRESSION_OK
+```
+
 ## 0.1.8
 
 ### Summary

package/README.md

@@ -107,6 +107,9 @@ local: http://127.0.0.1:8787/?token=<saved-token>&project=/path/to/project
 Use `--local` to bind only to `127.0.0.1`, or `--port N` to request a specific
 port. `hcc web` initializes the project bus, installs Claude/Codex hooks and
 shims, starts or reuses the Web console, and returns the terminal to you.
+`hcc web --local` is still Web mode; it only limits the listener to loopback.
+Use `hcc up` when you want local coordination commands without the Web console
+or shims.
 
 After the first shim install, open a new terminal or reload the rc file for
 your shell:
@@ -125,7 +128,11 @@ codex resume <session-id>
 ```
 
 Those sessions become tmux-backed peers that can be seen and controlled from
-Web while remaining usable from the local terminal.
+Web while remaining usable from the local terminal. The shims only use the
+current project's runtime file. If you start `claude` or `codex` in a directory
+where `hcc web` has not created `.hello-cc/runtime.json`, the shim falls back to
+the real provider CLI instead of using the global Web runtime or creating a new
+project database.
 
 ## Basic Workflow
 

package/README.zh-CN.md

@@ -94,6 +94,8 @@ local: http://127.0.0.1:8787/?token=<saved-token>&project=/path/to/project
 使用 `--local` 可以只绑定 `127.0.0.1`，使用 `--port N` 可以指定请求端口。
 `hcc web` 会初始化项目总线，安装 Claude/Codex hooks 和 shims，启动或复用 Web
 控制台，然后把终端还给你。
+`hcc web --local` 仍然是 Web 模式，只是限制监听在本机 loopback。只想使用本地
+协作命令、不启动 Web 控制台、不安装 shims 时，使用 `hcc up`。
 
 第一次安装 shim 后，打开新终端，或根据当前 shell 重新加载配置：
 
@@ -111,6 +113,9 @@ codex resume <session-id>
 ```
 
 这些会话会成为 tmux-backed peer，可以继续在本地终端里使用，也可以被 Web 控制台观察和操作。
+shim 只使用当前项目自己的 runtime 文件。如果你在没有通过 `hcc web` 创建
+`.hello-cc/runtime.json` 的目录里启动 `claude` 或 `codex`，shim 会回退到真实
+provider CLI，不会使用全局 Web runtime，也不会为这个目录新建项目数据库。
 
 ## 基本流程
 

package/bin/hcc.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import process from 'node:process';
+import { randomBytes } from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { URL, fileURLToPath } from 'node:url';
@@ -1417,15 +1418,28 @@ async function cmdBroadcast(ctx, args) {
   touchCurrentPeer(db, ctx, identity, null, 'shell');
   const id = sendMessage(db, sender, 'all', taskId, kind, body);
   let injected = 0;
+  let skipped = 0;
   if (opts.inject) {
     const sessions = await runtimeRequest(ctx, 'GET', '/api/sessions', null, runtime);
     const running = (sessions.sessions || []).filter((session) => session.status === 'running');
     for (const session of running) {
-      await injectPeer(ctx, session.id, body, !opts['no-enter'], runtime, sender);
-      injected += 1;
+      try {
+        await injectPeer(ctx, session.id, body, !opts['no-enter'], runtime, sender);
+        injected += 1;
+      } catch (err) {
+        if (err instanceof CliError && ['NOT_FOUND', 'SESSION_NOT_RUNNING', 'TMUX_ERROR'].includes(err.code)) {
+          skipped += 1;
+          continue;
+        }
+        throw err;
+      }
     }
   }
-  printResult(ctx, { id, sender, recipient: 'all', task_id: taskId, kind, body, injected }, (data) => `broadcast message #${data.id}${data.injected ? ` and injected ${data.injected} terminal(s)` : ''}`);
+  printResult(ctx, { id, sender, recipient: 'all', task_id: taskId, kind, body, injected, skipped }, (data) => {
+    const injectedText = data.injected ? ` and injected ${data.injected} terminal(s)` : '';
+    const skippedText = data.skipped ? `, skipped ${data.skipped} stale terminal(s)` : '';
+    return `broadcast message #${data.id}${injectedText}${skippedText}`;
+  });
 }
 
 async function injectPeer(ctx, peer, text, enter = true, runtime = null, auditActor = null) {
@@ -2044,11 +2058,21 @@ function hccWebProcessMatches(line, ctx) {
     sameResolvedPath(global.db, ctx.dbPath);
 }
 
+function currentProcessAncestorPids(ppidByPid) {
+  const ancestors = new Set();
+  let pid = process.ppid;
+  while (Number.isFinite(pid) && pid > 0 && !ancestors.has(pid)) {
+    ancestors.add(pid);
+    pid = ppidByPid.get(pid);
+  }
+  return ancestors;
+}
+
 async function stopOrphanWebRuntimes(ctx, keepPid = null) {
   if (process.platform === 'win32') return;
   let output = '';
   try {
-    output = spawnSync('ps', ['-eo', 'pid=,args='], {
+    output = spawnSync('ps', ['-eo', 'pid=,ppid=,args='], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore']
     }).stdout || '';
@@ -2056,15 +2080,25 @@ async function stopOrphanWebRuntimes(ctx, keepPid = null) {
     return;
   }
 
-  const pids = [];
+  const rows = [];
+  const ppidByPid = new Map();
   for (const line of output.split('\n')) {
     const trimmed = line.trim();
     if (!trimmed) continue;
-    const match = trimmed.match(/^(\d+)\s+(.*)$/);
+    const match = trimmed.match(/^(\d+)\s+(\d+)\s+(.*)$/);
     if (!match) continue;
     const pid = Number.parseInt(match[1], 10);
-    if (!Number.isFinite(pid) || pid === process.pid || pid === keepPid) continue;
-    if (hccWebProcessMatches(match[2], ctx)) pids.push(pid);
+    const ppid = Number.parseInt(match[2], 10);
+    if (!Number.isFinite(pid)) continue;
+    if (Number.isFinite(ppid)) ppidByPid.set(pid, ppid);
+    rows.push({ pid, args: match[3] });
+  }
+
+  const ancestorPids = currentProcessAncestorPids(ppidByPid);
+  const pids = [];
+  for (const row of rows) {
+    if (row.pid === process.pid || row.pid === keepPid || ancestorPids.has(row.pid)) continue;
+    if (hccWebProcessMatches(row.args, ctx)) pids.push(row.pid);
   }
   if (!pids.length) return;
 
@@ -2250,7 +2284,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   const prepared = await prepareLocalBus(ctx, opts);
 
   function newSessionActionToken() {
-    return makeWebToken({ token: null });
+    return randomBytes(32).toString('base64url');
   }
 
   function rememberProject(projectCtx) {

package/docs/commands.md

@@ -29,7 +29,9 @@ shims, starts or reuses the Web console, and returns the terminal to you. Bare
 first use. Use `--local` to bind only `127.0.0.1`, `--token` or `HCC_WEB_TOKEN`
 to replace the saved token, and
 `--no-token` only in trusted local/test environments. Use `hcc up` only when you
-want coordination without the Web console or shims.
+want coordination without the Web console or shims. Provider shims only join
+projects with a local `.hello-cc/runtime.json` from `hcc web`; they do not use a
+global runtime to manage arbitrary directories.
 
 ## Peers And Status
 

package/docs/commands.zh-CN.md

@@ -26,7 +26,9 @@ hcc up [--no-discover] [--no-guidance]
 Web 控制台，然后把终端还给你。裸 `hcc web` 会监听 `0.0.0.0` 并使用固定
 URL token；首次使用时自动生成并保存。用 `--local` 可只绑定 `127.0.0.1`，
 用 `--token` 或 `HCC_WEB_TOKEN` 可替换保存的 token，只有在可信本地/测试环境才使用 `--no-token`。
-只想使用本地协作、不需要 Web 或 shims 时，再使用 `hcc up`。
+只想使用本地协作、不需要 Web 或 shims 时，再使用 `hcc up`。provider shim 只会加入
+已经由 `hcc web` 生成本地 `.hello-cc/runtime.json` 的项目，不会使用全局 runtime
+去管理任意目录。
 
 ## Peers 和状态
 

package/docs/guide.md

@@ -104,6 +104,10 @@ The wrappers create or reuse local persistent tmux terminals:
 - The local terminal attaches to the same tmux session and remains usable.
 - The web console controls the same tmux pane, not a temporary browser-only
   terminal.
+- Shims only use the current project's `.hello-cc/runtime.json`. A global Web
+  runtime does not make arbitrary directories managed; if the current project
+  has not run `hcc web`, `claude` and `codex` fall back to the real provider CLI
+  without creating `.hello-cc/mesh.db`.
 - `hcc down` stops only the web runtime. It does not kill tmux sessions.
 - Running `hcc web` again reattaches live recorded tmux panes.
 
@@ -118,11 +122,14 @@ hcc up
 ```
 
 Most users should start with `hcc web`.
+`hcc web --local` is still Web mode; it binds the Web runtime only to
+`127.0.0.1`.
 
 ## Project Boundary
 
-By default, the project boundary is the current working directory. If the
-current directory has no `.hello-cc/mesh.db`, hello-cc creates one on first use:
+By default, the project boundary is the current working directory. Explicit
+`hcc` commands such as `hcc web`, `hcc up`, `hcc task`, or `hcc peer start`
+create the project database on first use:
 
 ```text
 /repo-a/.hello-cc/mesh.db
@@ -132,6 +139,11 @@ current directory has no `.hello-cc/mesh.db`, hello-cc creates one on first use:
 Those are two different projects by default. Sessions communicate naturally
 when they start from the same project path.
 
+Provider shims are stricter: direct `claude` and `codex` commands only join
+hello-cc when the current project already has a local `.hello-cc/runtime.json`
+from `hcc web`. They do not use `~/.hello-cc/runtime.json` to auto-register or
+create databases for unrelated directories.
+
 To share one bus across paths or worktrees, opt in explicitly:
 
 ```bash

package/docs/guide.zh-CN.md

@@ -95,6 +95,9 @@ codex resume <session-id>
 
 - 本地终端会 attach 到同一个 tmux 会话，仍然可以像普通 Claude/Codex 一样交互。
 - Web 控制台看到并操作的是同一个 tmux pane，不是浏览器里临时创建的假终端。
+- shim 只使用当前项目的 `.hello-cc/runtime.json`。全局 Web runtime 不会让任意
+  目录自动进入管理；如果当前项目没有运行过 `hcc web`，`claude` 和 `codex`
+  会回退到真实 provider CLI，不会创建 `.hello-cc/mesh.db`。
 - `hcc down` 只停止 Web runtime，不会杀掉这些 tmux 会话。
 - 重新运行 `hcc web` 后，只要 tmux pane 还活着，Web 会重新接管。
 
@@ -108,10 +111,14 @@ hcc up
 ```
 
 普通用户优先使用 `hcc web`。
+`hcc web --local` 仍然是 Web 模式，只是把 Web runtime 限制为监听
+`127.0.0.1`。
 
 ## 项目边界
 
-默认项目边界就是当前工作目录。如果当前目录没有 `.hello-cc/mesh.db`，hello-cc 会在首次使用时创建：
+默认项目边界就是当前工作目录。显式运行 `hcc web`、`hcc up`、`hcc task` 或
+`hcc peer start` 这类 `hcc` 命令时，如果当前目录没有 `.hello-cc/mesh.db`，
+hello-cc 会在首次使用时创建：
 
 ```text
 /repo-a/.hello-cc/mesh.db
@@ -120,6 +127,10 @@ hcc up
 
 这两个目录默认是两个不同项目，不会互相看到任务和消息。想让多个终端自然通信，就在同一个项目目录启动它们。
 
+provider shim 更严格：直接运行 `claude` 和 `codex` 时，只有当前项目已经通过
+`hcc web` 生成本地 `.hello-cc/runtime.json` 才会加入 hello-cc。它们不会使用
+`~/.hello-cc/runtime.json` 去自动注册无关目录，也不会为这些目录创建数据库。
+
 如果确实要让多个路径或 worktree 共用一个总线，需要显式指定：
 
 ```bash

package/lib/core/sessions/launch.mjs

@@ -14,6 +14,7 @@ const LAUNCH_ENV_IGNORED_KEYS = new Set([
   'HCC_NO_AUTO_INSTALL_TMUX',
   'HCC_PEER',
   'HCC_ROOT',
+  'HCC_RUNTIME_LOCAL_ONLY',
   'HCC_SKIP_SHIM_INSTALL',
   PROVIDER_STATE_ENV,
   'HCC_SHIM_ENSURED',
@@ -38,6 +39,7 @@ const LAUNCH_ENV_IGNORED_KEYS = new Set([
 export function childSessionEnv(extra = {}, baseEnv = process.env) {
   const env = { ...(baseEnv || {}), ...extra };
   delete env[WEB_CHILD_ENV];
+  delete env.HCC_RUNTIME_LOCAL_ONLY;
   return env;
 }
 

package/lib/integrations/shims/script.mjs

@@ -139,14 +139,22 @@ detect_current_hcc_pane() {
   return 1
 }
 
+hcc_runtime_unavailable_start_failure() {
+  case "$1" in
+    *"No running web runtime found"*|*"No running hello-cc web runtime found"*|*"Runtime is not reachable"*|*"RUNTIME_NOT_RUNNING"*|*"RUNTIME_UNREACHABLE"*|*"RUNTIME_START_FAILED"*|*"RUNTIME_START_TIMEOUT"*)
+      return 0
+      ;;
+  esac
+  return 1
+}
+
 if detect_current_hcc_pane; then
   SESSION_PEER_ID=$(printf '%s' "$CURRENT_HCC_SESSION" | sed 's/^hcc-[^-]*-//')
   if [ -n "$SESSION_PEER_ID" ] && [ "$SESSION_PEER_ID" != "$CURRENT_HCC_SESSION" ]; then
     PEER_ID="$SESSION_PEER_ID"
   fi
   export HCC_PEER="$PEER_ID"
-  HCC_SKIP_SHIM_INSTALL=1 "$HCC_BIN" web >/dev/null 2>&1 || true
-  "$HCC_BIN" peer attach "$PEER_ID" --kind "${tool.kind}" --pane "$CURRENT_HCC_PANE" --cwd "$PWD" --force >/dev/null 2>&1 || true
+  HCC_RUNTIME_LOCAL_ONLY=1 "$HCC_BIN" peer attach "$PEER_ID" --kind "${tool.kind}" --pane "$CURRENT_HCC_PANE" --cwd "$PWD" --force >/dev/null 2>&1 || true
   exec "$REAL_BIN" "$@"
 fi
 
@@ -155,12 +163,15 @@ HCC_PROVIDER_LAUNCH_SCRIPT='REAL_BIN="$1"; shift; HCC_TMUX_BIN="\${HCC_TMUX_BIN:
 set +e
 # Wrap in shell so pane_pid stays as bash; Ctrl+C drops back to bash
 START_OUT_FILE=$(mktemp "\${TMPDIR:-/tmp}/hcc-shim-start.XXXXXX")
-(HCC_SKIP_SHIM_INSTALL=1 "$HCC_BIN" web >/dev/null 2>&1 || true; "$HCC_BIN" peer start "$PEER_ID" --kind "${tool.kind}" --restart-env -- bash -lc "$HCC_PROVIDER_LAUNCH_SCRIPT" _ "$REAL_BIN" "$@") >"$START_OUT_FILE" 2>&1
+(HCC_RUNTIME_LOCAL_ONLY=1 "$HCC_BIN" peer start "$PEER_ID" --kind "${tool.kind}" --restart-env -- bash -lc "$HCC_PROVIDER_LAUNCH_SCRIPT" _ "$REAL_BIN" "$@") >"$START_OUT_FILE" 2>&1
 START_STATUS=$?
 START_OUT=$(cat "$START_OUT_FILE" 2>/dev/null || true)
 rm -f "$START_OUT_FILE"
 set -e
 if [ "$START_STATUS" -ne 0 ]; then
+  if hcc_runtime_unavailable_start_failure "$START_OUT"; then
+    exec "$REAL_BIN" "$@"
+  fi
   printf '%s\\n' "$START_OUT" >&2
   exit "$START_STATUS"
 fi
@@ -352,14 +363,22 @@ detect_current_hcc_pane() {
   return 1
 }
 
+hcc_runtime_unavailable_start_failure() {
+  case "$1" in
+    *"No running web runtime found"*|*"No running hello-cc web runtime found"*|*"Runtime is not reachable"*|*"RUNTIME_NOT_RUNNING"*|*"RUNTIME_UNREACHABLE"*|*"RUNTIME_START_FAILED"*|*"RUNTIME_START_TIMEOUT"*)
+      return 0
+      ;;
+  esac
+  return 1
+}
+
 if detect_current_hcc_pane; then
   SESSION_PEER_ID=$(printf '%s' "$CURRENT_HCC_SESSION" | sed 's/^hcc-[^-]*-//')
   if [ -n "$SESSION_PEER_ID" ] && [ "$SESSION_PEER_ID" != "$CURRENT_HCC_SESSION" ]; then
     PEER_ID="$SESSION_PEER_ID"
   fi
   export HCC_PEER="$PEER_ID"
-  HCC_SKIP_SHIM_INSTALL=1 "$HCC_BIN" web >/dev/null 2>&1 || true
-  "$HCC_BIN" peer attach "$PEER_ID" --kind "${tool.kind}" --pane "$CURRENT_HCC_PANE" --cwd "$PWD" --force >/dev/null 2>&1 || true
+  HCC_RUNTIME_LOCAL_ONLY=1 "$HCC_BIN" peer attach "$PEER_ID" --kind "${tool.kind}" --pane "$CURRENT_HCC_PANE" --cwd "$PWD" --force >/dev/null 2>&1 || true
   exec "$REAL_BIN" "$@"
 fi
 
@@ -368,12 +387,15 @@ HCC_PROVIDER_LAUNCH_SCRIPT='REAL_BIN="$1"; shift; HCC_TMUX_BIN="\${HCC_TMUX_BIN:
 set +e
 # Wrap in shell so pane_pid stays as bash; Ctrl+C drops back to bash
 START_OUT_FILE=$(mktemp "\${TMPDIR:-/tmp}/hcc-shim-start.XXXXXX")
-(HCC_SKIP_SHIM_INSTALL=1 "$HCC_BIN" web >/dev/null 2>&1 || true; "$HCC_BIN" peer start "$PEER_ID" --kind "${tool.kind}" --restart-env -- bash -lc "$HCC_PROVIDER_LAUNCH_SCRIPT" _ "$REAL_BIN" "$@") >"$START_OUT_FILE" 2>&1
+(HCC_RUNTIME_LOCAL_ONLY=1 "$HCC_BIN" peer start "$PEER_ID" --kind "${tool.kind}" --restart-env -- bash -lc "$HCC_PROVIDER_LAUNCH_SCRIPT" _ "$REAL_BIN" "$@") >"$START_OUT_FILE" 2>&1
 START_STATUS=$?
 START_OUT=$(cat "$START_OUT_FILE" 2>/dev/null || true)
 rm -f "$START_OUT_FILE"
 set -e
 if [ "$START_STATUS" -ne 0 ]; then
+  if hcc_runtime_unavailable_start_failure "$START_OUT"; then
+    exec "$REAL_BIN" "$@"
+  fi
   printf '%s\\n' "$START_OUT" >&2
   exit "$START_STATUS"
 fi

package/lib/runtime/client.mjs

@@ -6,7 +6,7 @@ const DEFAULT_CLI_NAME = 'hcc';
 
 export async function runtimeRequest(ctx, method, route, body = null, runtime = null, opts = {}) {
   const cliName = opts.cliName || DEFAULT_CLI_NAME;
-  const rt = runtime || readRuntime(ctx, { cliName });
+  const rt = runtime || readRuntime(ctx, { cliName, localOnly: Boolean(opts.localOnly) });
   const url = runtimeApiUrl(rt, route);
   const headers = { 'Content-Type': 'application/json' };
   headers['X-HCC-Root'] = ctx.root;

package/lib/runtime/state.mjs

@@ -39,6 +39,7 @@ export function writeRuntime(ctx, runtime) {
 }
 
 export function readRuntime(ctx, opts = {}) {
+  const localOnly = Boolean(opts.localOnly || process.env.HCC_RUNTIME_LOCAL_ONLY === '1');
   if (process.env.HCC_RUNTIME_URL) {
     return {
       base_url: process.env.HCC_RUNTIME_URL,
@@ -56,9 +57,11 @@ export function readRuntime(ctx, opts = {}) {
       try { fs.rmSync(file, { force: true }); } catch {}
     }
   }
-  const global = readGlobalRuntimeFile();
-  if (global?.base_url) {
-    return { ...global, source: globalRuntimePath(), global: true };
+  if (!localOnly) {
+    const global = readGlobalRuntimeFile();
+    if (global?.base_url) {
+      return { ...global, source: globalRuntimePath(), global: true };
+    }
   }
   const productName = opts.productName || DEFAULT_PRODUCT_NAME;
   const cliName = opts.cliName || DEFAULT_CLI_NAME;

package/lib/web/http.mjs

@@ -19,7 +19,14 @@ function readRequestBody(req, limit = 1024 * 1024) {
 export async function readJsonRequest(req) {
   const body = await readRequestBody(req);
   if (!body.trim()) return {};
-  return JSON.parse(body);
+  try {
+    return JSON.parse(body);
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new CliError('BAD_REQUEST', 'Invalid JSON request body');
+    }
+    throw err;
+  }
 }
 
 export function sendHttp(res, status, contentType, body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicseek/hello-cc",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Local control plane for coordinating Claude Code, Codex, and other coding CLI sessions.",
   "type": "module",
   "bin": {

package/scripts/regression.mjs

@@ -1216,6 +1216,197 @@ function libModuleFiles() {
     .map((name) => path.join('lib', name));
 }
 
+function assertShimRuntimeUnavailableFallback(generateShim) {
+  const fallbackDir = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-shim-fallback-${testId}-`));
+  try {
+    const fakeHcc = path.join(fallbackDir, 'hcc');
+    fs.writeFileSync(fakeHcc, `#!/usr/bin/env bash
+case "\${1:-}" in
+  shim)
+    exit 64
+    ;;
+  find-root)
+    if [ -n "\${HCC_FAKE_ROOT:-}" ]; then
+      printf '%s\\n' "$HCC_FAKE_ROOT"
+      exit 0
+    fi
+    exit 1
+    ;;
+  web)
+    exit 1
+    ;;
+  peer)
+    if [ "\${2:-}" = "start" ]; then
+      printf '%s\\n' "hcc: No running web runtime found. Start hcc web first, then hcc peer start \${3:-peer}" >&2
+      exit 1
+    fi
+    exit 1
+    ;;
+esac
+exit 1
+`, { mode: 0o755 });
+
+    const cases = [
+      {
+        tool: { name: 'claude', kind: 'claude', resumeFlag: '--resume' },
+        args: ['--resume', 'missing-web-session'],
+        expected: 'real-claude --resume missing-web-session'
+      },
+      {
+        tool: { name: 'codex', kind: 'codex' },
+        args: ['resume', 'missing-web-session'],
+        expected: 'real-codex resume missing-web-session'
+      }
+    ];
+
+    for (const entry of cases) {
+      const realBin = path.join(fallbackDir, `real-${entry.tool.name}`);
+      const shimBin = path.join(fallbackDir, entry.tool.name);
+      const logFile = path.join(fallbackDir, `${entry.tool.name}.log`);
+      fs.writeFileSync(realBin, `#!/usr/bin/env bash
+printf 'real-${entry.tool.name}'
+for arg in "$@"; do printf ' %s' "$arg"; done
+printf '\\n'
+if [ -n "\${HCC_FAKE_LOG:-}" ]; then
+  printf 'real-${entry.tool.name}' >> "$HCC_FAKE_LOG"
+  for arg in "$@"; do printf ' %s' "$arg" >> "$HCC_FAKE_LOG"; done
+  printf '\\n' >> "$HCC_FAKE_LOG"
+fi
+`, { mode: 0o755 });
+      fs.writeFileSync(shimBin, generateShim(fakeHcc, realBin, entry.tool), { mode: 0o755 });
+
+      const result = runMaybe(shimBin, entry.args, {
+        cwd: fallbackDir,
+        env: {
+          ...env,
+          HCC_FAKE_ROOT: fallbackDir,
+          HCC_FAKE_LOG: logFile
+        }
+      });
+      if (result.status !== 0) {
+        fail(`${entry.tool.name} shim did not fall back when runtime was unavailable:\nstdout=${result.stdout}\nstderr=${result.stderr}`);
+      }
+      if (!String(result.stdout || '').includes(entry.expected)) {
+        fail(`${entry.tool.name} shim fallback did not launch the real provider:\nstdout=${result.stdout}\nstderr=${result.stderr}`);
+      }
+      const logOutput = fs.existsSync(logFile) ? fs.readFileSync(logFile, 'utf8') : '';
+      if (!logOutput.includes(entry.expected)) {
+        fail(`${entry.tool.name} shim fallback did not preserve provider argv:\n${logOutput}`);
+      }
+      if (String(result.stderr || '').includes('No running web runtime found')) {
+        fail(`${entry.tool.name} shim leaked hcc runtime failure instead of transparent fallback:\n${result.stderr}`);
+      }
+    }
+  } finally {
+    try { fs.rmSync(fallbackDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+async function assertShimIgnoresGlobalRuntime(generateShim) {
+  const testDir = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-shim-global-runtime-${testId}-`));
+  const fakeHome = path.join(testDir, 'home');
+  const projectRoot = path.join(testDir, 'project-without-runtime');
+  const requests = [];
+  let server = null;
+  try {
+    fs.mkdirSync(path.join(fakeHome, '.hello-cc'), { recursive: true });
+    fs.mkdirSync(projectRoot, { recursive: true });
+
+    server = http.createServer((req, res) => {
+      requests.push({ method: req.method, url: req.url });
+      res.setHeader('Content-Type', 'application/json');
+      if (req.method === 'GET' && req.url.startsWith('/api/runtime')) {
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+      if (req.method === 'POST' && req.url.startsWith('/api/sessions')) {
+        res.end(JSON.stringify({ session: {
+          id: 'global-runtime-session',
+          kind: 'claude',
+          role: 'peer',
+          status: 'running',
+          pane: '%900'
+        } }));
+        return;
+      }
+      res.statusCode = 404;
+      res.end(JSON.stringify({ error: { code: 'NOT_FOUND', message: 'not found' } }));
+    });
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    const globalRuntime = {
+      product: 'hello-cc',
+      version: 'regression',
+      pid: process.pid,
+      root: testDir,
+      db: path.join(testDir, '.hello-cc', 'mesh.db'),
+      host: '127.0.0.1',
+      port: address.port,
+      base_url: `http://127.0.0.1:${address.port}`,
+      token: '',
+      started_at: Math.floor(Date.now() / 1000),
+      global_runtime: true
+    };
+    fs.writeFileSync(path.join(fakeHome, '.hello-cc', 'runtime.json'), JSON.stringify(globalRuntime, null, 2));
+
+    const hccWrapper = path.join(testDir, 'hcc-wrapper');
+    fs.writeFileSync(hccWrapper, `#!/usr/bin/env bash\nexec ${sh(process.execPath)} ${sh(hccBin)} "$@"\n`, { mode: 0o755 });
+
+    const cases = [
+      {
+        tool: { name: 'claude', kind: 'claude', resumeFlag: '--resume' },
+        args: ['--resume', 'global-runtime-session'],
+        expected: 'real-claude --resume global-runtime-session'
+      },
+      {
+        tool: { name: 'codex', kind: 'codex' },
+        args: ['resume', 'global-runtime-session'],
+        expected: 'real-codex resume global-runtime-session'
+      }
+    ];
+
+    for (const entry of cases) {
+      requests.length = 0;
+      fs.rmSync(path.join(projectRoot, '.hello-cc'), { recursive: true, force: true });
+      const realBin = path.join(testDir, `real-${entry.tool.name}`);
+      const shimBin = path.join(testDir, entry.tool.name);
+      fs.writeFileSync(realBin, `#!/usr/bin/env bash
+printf 'real-${entry.tool.name}'
+for arg in "$@"; do printf ' %s' "$arg"; done
+printf '\\n'
+`, { mode: 0o755 });
+      fs.writeFileSync(shimBin, generateShim(hccWrapper, realBin, entry.tool), { mode: 0o755 });
+      const result = runMaybe(shimBin, entry.args, {
+        cwd: projectRoot,
+        env: {
+          ...env,
+          HOME: fakeHome,
+          HCC_SHIM_ENSURED: '1',
+          HCC_SHIM_NO_ATTACH: '1'
+        }
+      });
+      if (result.status !== 0) {
+        fail(`${entry.tool.name} shim failed while ignoring global runtime:\nstdout=${result.stdout}\nstderr=${result.stderr}`);
+      }
+      if (!String(result.stdout || '').includes(entry.expected)) {
+        fail(`${entry.tool.name} shim used global runtime instead of falling back:\nstdout=${result.stdout}\nstderr=${result.stderr}`);
+      }
+      if (requests.length) {
+        fail(`${entry.tool.name} shim contacted global runtime despite project-local restriction:\n${JSON.stringify(requests, null, 2)}`);
+      }
+      if (fs.existsSync(path.join(projectRoot, '.hello-cc', 'mesh.db'))) {
+        fail(`${entry.tool.name} shim created a project database while only a global runtime existed`);
+      }
+    }
+  } finally {
+    if (server?.listening) await new Promise((resolve) => server.close(resolve));
+    try { fs.rmSync(testDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
 async function expectBoundedTmuxStream(label) {
   let nodes = [];
   await waitFor(() => {
@@ -1260,6 +1451,38 @@ function startRuntime(options = {}) {
   if (!output.includes('web started in background')) fail(`hcc web did not report background start:\n${output}`);
 }
 
+async function assertWebWrapperParentSurvives() {
+  const wrapperRoot = fs.mkdtempSync(path.join(os.tmpdir(), `hcc-reg-wrapper-root-${testId}-`));
+  const wrapperPort = port + 101;
+  let wrapperPid = null;
+  try {
+    const script = [
+      'set -e',
+      `out=$(${sh(process.execPath)} ${sh(hccBin)} --root ${sh(wrapperRoot)} web --local --port ${wrapperPort} --no-discover --no-guidance)`,
+      `printf '%s\\n' "$out"`
+    ].join('\n');
+    const result = runMaybe('bash', ['-lc', script], { env });
+    if (result.status !== 0) {
+      fail(`hcc web killed or failed inside a wrapper shell:\nstdout=${result.stdout}\nstderr=${result.stderr}\nstatus=${result.status}\nsignal=${result.signal}`);
+    }
+    const match = String(result.stdout || '').match(/^pid:\s*(\d+)/m);
+    if (!match) fail(`wrapper hcc web did not print background pid:\n${result.stdout}`);
+    wrapperPid = Number.parseInt(match[1], 10);
+    ensureFile(path.join(wrapperRoot, '.hello-cc', 'runtime.json'));
+  } finally {
+    runMaybe(process.execPath, [hccBin, '--root', wrapperRoot, 'down'], { env });
+    if (wrapperPid) {
+      try {
+        await waitForProcessExit(wrapperPid, 'wrapper runtime process exit', 5000);
+      } catch {
+        try { process.kill(wrapperPid, 'SIGTERM'); } catch {}
+        try { await waitForProcessExit(wrapperPid, 'wrapper runtime process exit after SIGTERM', 2000); } catch {}
+      }
+    }
+    try { fs.rmSync(wrapperRoot, { recursive: true, force: true }); } catch {}
+  }
+}
+
 async function stopRuntime() {
   if (!runtimePid) return;
   const pid = runtimePid;
@@ -1420,6 +1643,7 @@ async function setupRegression() {
     fail(`shim ensure preserved stale real binary instead of rediscovering PATH binary:\n${rediscoveredShim}`);
   }
   await stopRuntime();
+  await assertWebWrapperParentSurvives();
   assertPeerBindingUniqueConstraints();
   assertLegacySchemaMigration();
   assertRegisteredProjectDbMigration();
@@ -1442,6 +1666,18 @@ async function setupRegression() {
   if (unauthorizedResponse.status !== 401) fail(`default web API allowed missing token: ${unauthorizedResponse.status}`);
   const tokenResponse = await runtimeFetch('/api/runtime');
   if (!tokenResponse.ok) fail(`default web API rejected runtime token: ${tokenResponse.status}`);
+  const badJsonResponse = await runtimeFetch('/api/projects', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: '{bad json'
+  });
+  if (badJsonResponse.status !== 400) {
+    fail(`bad JSON request returned ${badJsonResponse.status}, expected 400:\n${await badJsonResponse.text()}`);
+  }
+  const badJsonBody = await badJsonResponse.json();
+  if (badJsonBody?.error?.code !== 'BAD_REQUEST') {
+    fail(`bad JSON request did not return BAD_REQUEST:\n${JSON.stringify(badJsonBody, null, 2)}`);
+  }
   const tokenFile = path.join(home, '.hello-cc', 'web-token');
   ensureFile(tokenFile, tokenRuntime.token);
   fs.rmSync(tokenFile, { force: true });
@@ -2251,6 +2487,10 @@ async function multiProjectWebWorkflow() {
   if (!managedActionSession.action_token) {
     fail(`managed web session did not include action token:\n${JSON.stringify(managedActionSession, null, 2)}`);
   }
+  const runtimeActionToken = currentRuntime().token || '';
+  if (managedActionSession.action_token === runtimeActionToken || managedActionSession.action_token.length < 32) {
+    fail(`managed web session action token is not an independent session token:\n${JSON.stringify({ runtimeActionToken, managedActionSession }, null, 2)}`);
+  }
   const actionNext = await (await runtimeFetch(`/api/peers/${encodeURIComponent(managedActionSession.peer_id || managedActionSession.id)}/actions/task-next`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
@@ -2537,6 +2777,10 @@ async function shimTmuxWorkflow() {
   }
 
   log('[6/13] shim tmux-backed launch');
+  if (!fs.existsSync(path.join(root, '.hello-cc', 'runtime.json'))) {
+    startRuntime();
+  }
+  await waitRuntime();
   const shim = path.join(home, '.hcc-shims', 'claude');
   const codexShim = path.join(home, '.hcc-shims', 'codex');
   const claudeVersion = run(shim, ['--version'], { cwd: root, env });
@@ -2608,8 +2852,8 @@ async function shimTmuxWorkflow() {
   hcc(['inject', peer, `printf '%s\\n' "$HCC_REG_VALUE" > ${firstEnvFile}`]);
   await waitForFile(firstEnvFile, 'shim-first', 'shim first env');
   const shimInternalEnvFile = path.join(outDir, 'shim-internal-env');
-  hcc(['inject', peer, `printf '%s|%s\\n' "\${HCC_SHIM_ENSURED-unset}" "\${HCC_SKIP_SHIM_INSTALL-unset}" > ${shimInternalEnvFile}`]);
-  await waitForFile(shimInternalEnvFile, 'unset|unset', 'shim internal env cleanup');
+  hcc(['inject', peer, `printf '%s|%s|%s\\n' "\${HCC_SHIM_ENSURED-unset}" "\${HCC_SKIP_SHIM_INSTALL-unset}" "\${HCC_RUNTIME_LOCAL_ONLY-unset}" > ${shimInternalEnvFile}`]);
+  await waitForFile(shimInternalEnvFile, 'unset|unset|unset', 'shim internal env cleanup');
 
   const restarted = run(shim, ['--resume', 'shim-regression-session'], {
     cwd: root,
@@ -3339,9 +3583,13 @@ async function syntaxAndHelp() {
   if (!integrationShimScriptSource.includes('function generateShim') ||
       !integrationShimScriptSource.includes('hello-cc shim for ${tool.name}') ||
       !integrationShimScriptSource.includes('HCC_SHIM_ENSURED') ||
-      !integrationShimScriptSource.includes('HCC_SKIP_SHIM_INSTALL')) {
+      !integrationShimScriptSource.includes('HCC_RUNTIME_LOCAL_ONLY') ||
+      !integrationShimScriptSource.includes('hcc_runtime_unavailable_start_failure')) {
     fail('integrations shim script module is missing expected generateShim wiring');
   }
+  if (integrationShimScriptSource.includes('HCC_SKIP_SHIM_INSTALL=1 "$HCC_BIN" web')) {
+    fail('integration shim script still auto-starts hcc web instead of falling back to the real provider');
+  }
   if (!shellPathSource.includes('function installPathEntry') ||
       !shellPathSource.includes('function uninstallPathEntry') ||
       !shellPathSource.includes('.hcc-shims')) {
@@ -3374,6 +3622,8 @@ async function syntaxAndHelp() {
   if (setupModule.SHIM_DIR !== integrationShims.SHIM_DIR) fail('setup shim dir export mismatch');
   if (typeof integrationShimScript.generateShim !== 'function') fail('integrations shim script module missing generateShim export');
   if (shimScriptCompat.generateShim !== integrationShimScript.generateShim) fail('shim script compatibility export mismatch');
+  assertShimRuntimeUnavailableFallback(integrationShimScript.generateShim);
+  await assertShimIgnoresGlobalRuntime(integrationShimScript.generateShim);
   for (const name of ['installPathEntry', 'uninstallPathEntry']) {
     if (typeof shellPath[name] !== 'function') fail(`shell path module missing export: ${name}`);
     if (setupModule[name] !== shellPath[name]) fail(`setup shell path export mismatch: ${name}`);