@logicseek/hello-cc 0.1.7 → 0.1.9

package/docs/commands.md

@@ -12,7 +12,7 @@ hcc uninstall [--purge --yes]
 ```
 
 `hcc update` updates the global npm install. `hcc uninstall` removes local
-hooks and shims; add `--purge --yes` only when you also want to remove the
+hooks, shims, and the shell PATH entry; add `--purge --yes` only when you also want to remove the
 current project's `.hello-cc` data and guidance blocks.
 
 ## Start And Stop
@@ -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
 
@@ -93,6 +95,8 @@ sender by default. Use `msg thread` to inspect the full thread for one message.
 
 ```text
 hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+hcc task dispatch --to ID --title TEXT [--body TEXT] [--from ID] [--message TEXT] [--no-inject] [--force]
+hcc task dispatch --to ID --id N [--from ID] [--message TEXT] [--no-inject] [--force]
 hcc task list [--status S] [--peer ID] [--all]
 hcc task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
 hcc task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--stale-after SECONDS]
@@ -107,11 +111,16 @@ Tasks are shared project facts. They remain visible until marked `done` or
 task before claiming a new pending task; use `--force` only when intentionally
 taking additional pending tasks, and combine it with `--count N` for explicit
 batch claims. `task claim` also accepts repeated `--id` values and comma-separated
-`--id` or `--ids` lists. Use `task takeover` when explicitly taking a
-non-complete task from another owner; it records the previous owner, requires a
-reason, and notifies them. Add `--policy blocked`, `stale`, or `blocked-or-stale`
-when takeover should only proceed under that auditable precondition. The default
-policy is `any` for compatibility.
+`--id` or `--ids` lists. `task dispatch` is the explicit one-step form for
+assigning a new or existing task to one peer, sending the durable task message,
+and injecting the startup prompt only when that peer has a running managed
+Claude/Codex terminal. Use `--no-inject` for message-only dispatch, and use
+`--force` only when intentionally injecting while the target already owns another
+active task. Use `task takeover` when explicitly taking a non-complete task from
+another owner; it records the previous owner, requires a reason, and notifies
+them. Add `--policy blocked`, `stale`, or `blocked-or-stale` when takeover
+should only proceed under that auditable precondition. The default policy is
+`any` for compatibility.
 
 ## Teams
 

package/docs/commands.zh-CN.md

@@ -10,7 +10,7 @@ hcc update [--tag TAG] [--registry URL] [--dry-run]
 hcc uninstall [--purge --yes]
 ```
 
-`hcc update` 更新全局 npm 安装。`hcc uninstall` 移除本机 hooks 和 shims；
+`hcc update` 更新全局 npm 安装。`hcc uninstall` 移除本机 hooks、shims 和 shell PATH 配置；
 只有在确定也要删除当前项目的 `.hello-cc` 数据和指导块时，才加
 `--purge --yes`。
 
@@ -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 和状态
 
@@ -86,6 +88,8 @@ hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
 
 ```text
 hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+hcc task dispatch --to ID --title TEXT [--body TEXT] [--from ID] [--message TEXT] [--no-inject] [--force]
+hcc task dispatch --to ID --id N [--from ID] [--message TEXT] [--no-inject] [--force]
 hcc task list [--status S] [--peer ID] [--all]
 hcc task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
 hcc task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--stale-after SECONDS]
@@ -98,11 +102,14 @@ hcc task done [--peer ID] --id N --summary TEXT
 任务是项目共享事实。任务会一直可见，直到被标记为 `done` 或 `abandoned`。
 `task next` 会优先返回当前 peer 已经认领、运行、审查或阻塞中的任务；只有明确
 要再接 pending 任务时才使用 `--force`，并可结合 `--count N` 做显式批量认领。
-`task claim` 也支持重复 `--id`、逗号分隔的 `--id` 或 `--ids` 列表。明确要从
-其他 owner 手里接管未完成任务时，使用 `task takeover`；它要求填写 reason，会
-记录原 owner 并通知对方。需要更保守时，可加 `--policy blocked`、`stale` 或
-`blocked-or-stale`，要求任务符合可审计的阻塞/陈旧条件后才允许接管。默认 policy
-仍是 `any`，以保持兼容。
+`task claim` 也支持重复 `--id`、逗号分隔的 `--id` 或 `--ids` 列表。`task
+dispatch` 是显式的一步分发：创建或指定已有任务并分配给目标 peer、发送持久任务
+消息，并且只在目标 peer 有正在运行的托管 Claude/Codex 终端时注入启动提示。只想
+发消息时使用 `--no-inject`；目标已经拥有其他活动任务但仍要注入时，才使用
+`--force`。明确要从其他 owner 手里接管未完成任务时，使用 `task takeover`；它要求
+填写 reason，会记录原 owner 并通知对方。需要更保守时，可加 `--policy blocked`、
+`stale` 或 `blocked-or-stale`，要求任务符合可审计的阻塞/陈旧条件后才允许接管。
+默认 policy 仍是 `any`，以保持兼容。
 
 ## 团队
 

package/docs/guide.md

@@ -21,7 +21,7 @@ hcc update
 `hcc update --help` to see the available update options. `hcc task update`
 updates a coordination task, not the installed package.
 
-Remove hooks and shims from this machine:
+Remove hooks, shims, and the shell PATH entry from this machine:
 
 ```bash
 hcc uninstall
@@ -83,11 +83,12 @@ with the same web console. The frontend Project selector switches between
 registered roots. Each project still keeps its own `.hello-cc/mesh.db`, so
 tasks, messages, locks, and peers stay isolated.
 
-After the first shim install, open a new terminal or run:
+After the first shim install, open a new terminal or reload the rc file for
+your shell:
 
-```bash
-source ~/.bashrc
-```
+- bash: `source ~/.bashrc`
+- zsh: `source ~/.zshrc`
+- fish: `source ~/.config/fish/config.fish`
 
 Then direct project-local commands are wrapped automatically:
 
@@ -103,9 +104,17 @@ 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.
 
+Linux also has richer process auto-discovery through `/proc`. On macOS, prefer
+shim-launched or `hcc peer start` sessions when you want reliable terminal
+control and stable peer identity.
+
 For local coordination without Web or shims, use:
 
 ```bash
@@ -113,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
@@ -127,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

@@ -20,7 +20,7 @@ hcc update
 `hcc update` 会执行 `npm install -g @logicseek/hello-cc@latest`。使用
 `hcc update --help` 可以查看更新选项。`hcc task update` 更新的是协作任务状态，不是安装包版本。
 
-移除本机 hooks 和 shims：
+移除本机 hooks、shims 和 shell PATH 配置：
 
 ```bash
 hcc uninstall
@@ -76,11 +76,11 @@ stop: hcc down
 
 `hcc web` 使用单个全局 Web runtime。你在另一个项目目录再次运行 `hcc web` 时，不会再开一个端口，而是把那个项目注册到同一个 Web 控制台。前端 Project 下拉框可以在不同项目 root 之间切换；每个项目仍然使用自己的 `.hello-cc/mesh.db`，任务、消息、锁和 peers 不会混在一起。
 
-第一次安装 shim 后，需要打开一个新终端，或执行：
+第一次安装 shim 后，打开新终端，或根据当前 shell 重新加载配置：
 
-```bash
-source ~/.bashrc
-```
+- bash: `source ~/.bashrc`
+- zsh: `source ~/.zshrc`
+- fish: `source ~/.config/fish/config.fish`
 
 之后在这个项目目录中直接输入：
 
@@ -95,9 +95,15 @@ 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 会重新接管。
 
+Linux 还可以通过 `/proc` 做更完整的进程自动发现。macOS 上如果需要可靠的终端
+控制和稳定 peer 身份，建议使用 shim 启动的会话或 `hcc peer start`。
+
 如果只想初始化本地通信、不启动 Web、不安装 shim，可使用：
 
 ```bash
@@ -105,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
@@ -117,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/coordination/timeline.mjs

@@ -53,6 +53,7 @@ const TIMELINE_EVENT_ALLOW = new Set([
   'task.done',
   'task.abandoned',
   'task.takeover',
+  'task.dispatched',
   'team.started',
   'lock.acquired',
   'lock.released',

package/lib/core/sessions/launch.mjs

@@ -14,6 +14,8 @@ 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',
   'HCC_SHIM_NO_ATTACH',
@@ -37,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

@@ -1,4 +1,8 @@
+import { shellQuoteArg } from '../../format.mjs';
+
 export function generateShim(hccBin, realBin, tool) {
+  const hccBinLiteral = shellQuoteArg(hccBin);
+  const realBinLiteral = shellQuoteArg(realBin);
   if (tool.resumeFlag) {
     // Claude: --resume/--continue/--session-id/--fork-session aware wrapper.
     return `#!/usr/bin/env bash
@@ -7,19 +11,22 @@ export function generateShim(hccBin, realBin, tool) {
 # Real binary: ${realBin}
 
 set -e
-REAL_BIN="${realBin}"
-HCC_BIN="${hccBin}"
+REAL_BIN=${realBinLiteral}
+HCC_BIN=${hccBinLiteral}
+HCC_TMUX_BIN="\${HCC_TMUX_BIN:-$(command -v tmux 2>/dev/null || printf 'tmux')}"
+export HCC_TMUX_BIN
 
 if [ "\${HCC_SHIM_ENSURED:-}" != "1" ]; then
   set +e
-  "$HCC_BIN" shim ensure "${tool.name}" "$0" >/dev/null 2>&1
+  "$HCC_BIN" shim ensure "${tool.name}" "$0" "$REAL_BIN" >/dev/null 2>&1
   ENSURE_STATUS=$?
   set -e
-  if [ "$ENSURE_STATUS" = "75" ]; then
+  if [ "$ENSURE_STATUS" = "0" ] || [ "$ENSURE_STATUS" = "75" ]; then
     export HCC_SHIM_ENSURED=1
     exec "$0" "$@"
   fi
 fi
+unset HCC_SHIM_ENSURED
 
 should_passthrough() {
   for arg in "$@"; do
@@ -112,7 +119,7 @@ current_tmux_pane() {
   if [ -z "$TTY_PATH" ] || [ "$TTY_PATH" = "not a tty" ]; then
     return 1
   fi
-  tmux list-panes -a -F '#{pane_id} #{pane_tty}' 2>/dev/null | awk -v tty="$TTY_PATH" '$2 == tty { print $1; found = 1; exit } END { exit found ? 0 : 1 }'
+  "$HCC_TMUX_BIN" list-panes -a -F '#{pane_id} #{pane_tty}' 2>/dev/null | awk -v tty="$TTY_PATH" '$2 == tty { print $1; found = 1; exit } END { exit found ? 0 : 1 }'
 }
 
 CURRENT_HCC_PANE=""
@@ -123,7 +130,7 @@ detect_current_hcc_pane() {
   if [ -z "$CURRENT_HCC_PANE" ]; then
     return 1
   fi
-  CURRENT_HCC_SESSION=$(tmux display-message -p -t "$CURRENT_HCC_PANE" '#S' 2>/dev/null || true)
+  CURRENT_HCC_SESSION=$(command "$HCC_TMUX_BIN" display-message -p -t "$CURRENT_HCC_PANE" '#S' 2>/dev/null || true)
   case "$CURRENT_HCC_SESSION" in
     hcc-*-*) return 0 ;;
   esac
@@ -132,23 +139,39 @@ 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_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
 
+HCC_PROVIDER_LAUNCH_SCRIPT='REAL_BIN="$1"; shift; HCC_TMUX_BIN="\${HCC_TMUX_BIN:-tmux}"; command "$HCC_TMUX_BIN" set-environment HCC_PROVIDER_STATE running >/dev/null 2>&1 || true; "$REAL_BIN" "$@"; command "$HCC_TMUX_BIN" set-environment HCC_PROVIDER_STATE exited >/dev/null 2>&1 || true; exec bash --noprofile --norc'
+
 set +e
 # Wrap in shell so pane_pid stays as bash; Ctrl+C drops back to bash
-START_OUT=$("$HCC_BIN" web >/dev/null 2>&1 || true; "$HCC_BIN" peer start "$PEER_ID" --kind "${tool.kind}" --restart-env -- bash -lc 'REAL_BIN="$1"; shift; hcc_provider_state() { HCC_TMUX_SESSION=$(tmux display-message -p "#S" 2>/dev/null || true); if [ -n "$HCC_TMUX_SESSION" ]; then tmux set-environment -t "$HCC_TMUX_SESSION" HCC_PROVIDER_STATE "$1" >/dev/null 2>&1 || true; fi; }; hcc_provider_state running; "$REAL_BIN" "$@"; hcc_provider_state exited; exec bash' _ "$REAL_BIN" "$@" 2>&1)
+START_OUT_FILE=$(mktemp "\${TMPDIR:-/tmp}/hcc-shim-start.XXXXXX")
+(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
@@ -164,17 +187,17 @@ if [ "$HCC_SHIM_NO_ATTACH" = "1" ] || [ ! -t 0 ]; then
   exit 0
 fi
 
-SESSION=$(tmux display-message -p -t "$PANE" '#S' 2>/dev/null || true)
+SESSION=$(command "$HCC_TMUX_BIN" display-message -p -t "$PANE" '#S' 2>/dev/null || true)
 if [ -z "$SESSION" ]; then
   printf '%s\\n' "$START_OUT"
   exit 0
 fi
 
 if [ -n "$TMUX" ]; then
-  exec tmux switch-client -t "$SESSION"
+  exec "$HCC_TMUX_BIN" switch-client -t "$SESSION"
 fi
 
-exec tmux attach-session -t "$SESSION"
+exec "$HCC_TMUX_BIN" attach-session -t "$SESSION"
 `;
   }
 
@@ -185,19 +208,22 @@ exec tmux attach-session -t "$SESSION"
 # Real binary: ${realBin}
 
 set -e
-REAL_BIN="${realBin}"
-HCC_BIN="${hccBin}"
+REAL_BIN=${realBinLiteral}
+HCC_BIN=${hccBinLiteral}
+HCC_TMUX_BIN="\${HCC_TMUX_BIN:-$(command -v tmux 2>/dev/null || printf 'tmux')}"
+export HCC_TMUX_BIN
 
 if [ "\${HCC_SHIM_ENSURED:-}" != "1" ]; then
   set +e
-  "$HCC_BIN" shim ensure "${tool.name}" "$0" >/dev/null 2>&1
+  "$HCC_BIN" shim ensure "${tool.name}" "$0" "$REAL_BIN" >/dev/null 2>&1
   ENSURE_STATUS=$?
   set -e
-  if [ "$ENSURE_STATUS" = "75" ]; then
+  if [ "$ENSURE_STATUS" = "0" ] || [ "$ENSURE_STATUS" = "75" ]; then
     export HCC_SHIM_ENSURED=1
     exec "$0" "$@"
   fi
 fi
+unset HCC_SHIM_ENSURED
 
 first_non_option() {
   EXPECT_VALUE=0
@@ -317,7 +343,7 @@ current_tmux_pane() {
   if [ -z "$TTY_PATH" ] || [ "$TTY_PATH" = "not a tty" ]; then
     return 1
   fi
-  tmux list-panes -a -F '#{pane_id} #{pane_tty}' 2>/dev/null | awk -v tty="$TTY_PATH" '$2 == tty { print $1; found = 1; exit } END { exit found ? 0 : 1 }'
+  "$HCC_TMUX_BIN" list-panes -a -F '#{pane_id} #{pane_tty}' 2>/dev/null | awk -v tty="$TTY_PATH" '$2 == tty { print $1; found = 1; exit } END { exit found ? 0 : 1 }'
 }
 
 CURRENT_HCC_PANE=""
@@ -328,7 +354,7 @@ detect_current_hcc_pane() {
   if [ -z "$CURRENT_HCC_PANE" ]; then
     return 1
   fi
-  CURRENT_HCC_SESSION=$(tmux display-message -p -t "$CURRENT_HCC_PANE" '#S' 2>/dev/null || true)
+  CURRENT_HCC_SESSION=$(command "$HCC_TMUX_BIN" display-message -p -t "$CURRENT_HCC_PANE" '#S' 2>/dev/null || true)
   case "$CURRENT_HCC_SESSION" in
     hcc-*-*) return 0 ;;
   esac
@@ -337,23 +363,39 @@ 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_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
 
+HCC_PROVIDER_LAUNCH_SCRIPT='REAL_BIN="$1"; shift; HCC_TMUX_BIN="\${HCC_TMUX_BIN:-tmux}"; command "$HCC_TMUX_BIN" set-environment HCC_PROVIDER_STATE running >/dev/null 2>&1 || true; "$REAL_BIN" "$@"; command "$HCC_TMUX_BIN" set-environment HCC_PROVIDER_STATE exited >/dev/null 2>&1 || true; exec bash --noprofile --norc'
+
 set +e
 # Wrap in shell so pane_pid stays as bash; Ctrl+C drops back to bash
-START_OUT=$("$HCC_BIN" web >/dev/null 2>&1 || true; "$HCC_BIN" peer start "$PEER_ID" --kind "${tool.kind}" --restart-env -- bash -lc 'REAL_BIN="$1"; shift; hcc_provider_state() { HCC_TMUX_SESSION=$(tmux display-message -p "#S" 2>/dev/null || true); if [ -n "$HCC_TMUX_SESSION" ]; then tmux set-environment -t "$HCC_TMUX_SESSION" HCC_PROVIDER_STATE "$1" >/dev/null 2>&1 || true; fi; }; hcc_provider_state running; "$REAL_BIN" "$@"; hcc_provider_state exited; exec bash' _ "$REAL_BIN" "$@" 2>&1)
+START_OUT_FILE=$(mktemp "\${TMPDIR:-/tmp}/hcc-shim-start.XXXXXX")
+(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
@@ -369,16 +411,16 @@ if [ "$HCC_SHIM_NO_ATTACH" = "1" ] || [ ! -t 0 ]; then
   exit 0
 fi
 
-SESSION=$(tmux display-message -p -t "$PANE" '#S' 2>/dev/null || true)
+SESSION=$(command "$HCC_TMUX_BIN" display-message -p -t "$PANE" '#S' 2>/dev/null || true)
 if [ -z "$SESSION" ]; then
   printf '%s\\n' "$START_OUT"
   exit 0
 fi
 
 if [ -n "$TMUX" ]; then
-  exec tmux switch-client -t "$SESSION"
+  exec "$HCC_TMUX_BIN" switch-client -t "$SESSION"
 fi
 
-exec tmux attach-session -t "$SESSION"
+exec "$HCC_TMUX_BIN" attach-session -t "$SESSION"
 `;
 }

package/lib/integrations/shims.mjs

@@ -10,8 +10,9 @@ export const SHIM_DIR = path.join(os.homedir(), '.hcc-shims');
  * Install shim scripts for `claude` and `codex` into SHIM_DIR.
  * Returns { shimDir, installed: [paths], changed: [paths], skipped: [names] }.
  */
-export function installShims(hccBin) {
+export function installShims(hccBin, opts = {}) {
   fs.mkdirSync(SHIM_DIR, { recursive: true });
+  const realBins = opts.realBins && typeof opts.realBins === 'object' ? opts.realBins : {};
 
   const tools = [
     { name: 'claude', kind: 'claude', resumeFlag: '--resume' },
@@ -23,17 +24,23 @@ export function installShims(hccBin) {
   const skipped = [];
 
   for (const tool of tools) {
-    const realBin = findRealBinary(tool.name);
+    const shimPath = path.join(SHIM_DIR, tool.name);
+    let previous = null;
+    try { previous = fs.readFileSync(shimPath, 'utf8'); } catch {}
+    const requestedRealBin = realBins[tool.name] || null;
+    const existingRealBin = previous ? shimRealBinFromContent(previous) : null;
+    const realBin = existingRealBin && fsExists(existingRealBin)
+      ? existingRealBin
+      : requestedRealBin && fsExists(requestedRealBin)
+        ? requestedRealBin
+        : findRealBinary(tool.name);
     if (!realBin) {
       skipped.push(`${tool.name} (not found on PATH)`);
       continue;
     }
-    const shimPath = path.join(SHIM_DIR, tool.name);
     const content = generateShim(hccBin, realBin, tool);
-    let previous = null;
-    try { previous = fs.readFileSync(shimPath, 'utf8'); } catch {}
     if (previous !== content) {
-      fs.writeFileSync(shimPath, content, { mode: 0o755 });
+      writeExecutableAtomic(shimPath, content);
       changed.push(shimPath);
     } else {
       try { fs.chmodSync(shimPath, 0o755); } catch {}
@@ -66,6 +73,20 @@ export function verifyShims() {
   );
 }
 
+export function shimStatus() {
+  const tools = {};
+  for (const name of ['claude', 'codex']) {
+    const shimPath = path.join(SHIM_DIR, name);
+    tools[name] = { installed: fsExists(shimPath), path: shimPath };
+  }
+  return {
+    shimDir: SHIM_DIR,
+    tools,
+    installed: Object.values(tools).some((tool) => tool.installed),
+    complete: Object.values(tools).every((tool) => tool.installed)
+  };
+}
+
 /**
  * Find the real binary for `name`, skipping the SHIM_DIR.
  * Checks PATH, then npm global bin, then common install locations.
@@ -104,3 +125,21 @@ export function findRealBinary(name) {
 function fsExists(p) {
   try { fs.accessSync(p); return true; } catch { return false; }
 }
+
+function shimRealBinFromContent(content) {
+  const match = String(content || '').match(/^# Real binary: ([^\r\n]+)$/m);
+  return match ? match[1] : null;
+}
+
+function writeExecutableAtomic(file, content) {
+  const dir = path.dirname(file);
+  const base = path.basename(file);
+  const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+  try {
+    fs.writeFileSync(tmp, content, { mode: 0o755 });
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw err;
+  }
+}

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/setup.mjs

@@ -13,6 +13,7 @@ export {
   findRealBinary,
   installShims,
   SHIM_DIR,
+  shimStatus,
   uninstallShims,
   verifyShims
 } from './integrations/shims.mjs';