@logicseek/hello-cc 0.1.6 → 0.1.8

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
@@ -93,6 +93,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 +109,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`。
 
@@ -86,6 +86,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 +100,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:
 
@@ -106,6 +107,10 @@ The wrappers create or reuse local persistent tmux terminals:
 - `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

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`
 
 之后在这个项目目录中直接输入：
 
@@ -98,6 +98,9 @@ codex resume <session-id>
 - `hcc down` 只停止 Web runtime，不会杀掉这些 tmux 会话。
 - 重新运行 `hcc web` 后，只要 tmux pane 还活着，Web 会重新接管。
 
+Linux 还可以通过 `/proc` 做更完整的进程自动发现。macOS 上如果需要可靠的终端
+控制和稳定 peer 身份，建议使用 shim 启动的会话或 `hcc peer start`。
+
 如果只想初始化本地通信、不启动 Web、不安装 shim，可使用：
 
 ```bash

package/lib/cli-runtime.mjs

@@ -8,7 +8,8 @@ export function createContext(global = {}, deps = {}) {
   const detectRoot = deps.detectRoot;
   if (typeof detectRoot !== 'function') throw new TypeError('createContext requires deps.detectRoot');
   const root = detectRoot(cwd, global.root);
-  const dbPath = path.resolve(global.db || process.env.HCC_DB || projectDbPath(root));
+  const envDb = global.root ? null : process.env.HCC_DB;
+  const dbPath = path.resolve(global.db || envDb || projectDbPath(root));
   return { cwd, root, dbPath, json: global.json, explicitRoot: Boolean(global.root || process.env.HCC_ROOT) };
 }
 

package/lib/core/coordination/tasks.mjs

@@ -19,6 +19,16 @@ export function createTaskStore(deps = {}) {
   const sendMessage = typeof deps.sendMessage === 'function' ? deps.sendMessage : noopMessage;
   const activePeerTtl = Number(deps.activePeerTtl || DEFAULT_ACTIVE_PEER_TTL);
 
+  function taskOwnedError(peer, row, action) {
+    return new CliError('TASK_OWNED', `Task #${row.id} is owned by ${row.owner}`, {
+      owner: row.owner,
+      task_id: row.id,
+      attempted_by: peer,
+      action,
+      notify_owner: true
+    });
+  }
+
   function claimTaskRowsForPeer(db, peer, ids, { force = false, source = null } = {}) {
     return tx(db, () => {
       const tasks = [];
@@ -26,7 +36,7 @@ export function createTaskStore(deps = {}) {
         const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
         if (!row) throw new CliError('NOT_FOUND', `Task #${id} does not exist`);
         if (row.owner && row.owner !== peer && !force) {
-          throw new CliError('TASK_OWNED', `Task #${id} is owned by ${row.owner}`, { owner: row.owner });
+          throw taskOwnedError(peer, row, 'claim');
         }
         if (row.assignee && row.assignee !== peer && !force) {
           throw new CliError('TASK_ASSIGNED', `Task #${id} is assigned to ${row.assignee}`, { assignee: row.assignee });
@@ -211,7 +221,13 @@ export function createTaskStore(deps = {}) {
     });
   }
 
+  function assertTaskOwnerForMutation(db, peer, row, action) {
+    if (!row.owner || row.owner === peer) return;
+    throw taskOwnedError(peer, row, action);
+  }
+
   return {
+    assertTaskOwnerForMutation,
     claimNextTasksForPeer,
     claimTaskRowsForPeer,
     queryOpenTasks,

package/lib/core/coordination/timeline.mjs

@@ -25,7 +25,7 @@ export function taskParticipants(task) {
 
 export function payloadParticipants(payload) {
   const values = [];
-  for (const key of ['peer', 'from_peer', 'to_peer', 'assignee', 'owner', 'recipient', 'kept_peer', 'removed_peer', 'previous_owner']) {
+  for (const key of ['peer', 'actor_peer', 'target_peer', 'from_peer', 'to_peer', 'assignee', 'owner', 'recipient', 'kept_peer', 'removed_peer', 'previous_owner']) {
     if (payload?.[key] && payload[key] !== 'all') values.push(payload[key]);
   }
   return uniqueList(values);
@@ -53,19 +53,29 @@ const TIMELINE_EVENT_ALLOW = new Set([
   'task.done',
   'task.abandoned',
   'task.takeover',
+  'task.dispatched',
   'team.started',
   'lock.acquired',
   'lock.released',
   'peer.registered',
   'peer.joined',
   'peer.auto_joined',
+  'peer.start.requested',
+  'peer.attach.requested',
+  'peer.stop.requested',
   'peer.stopped',
+  'peer.restarted',
   'provider.session.merged',
+  'provider.session.rebound',
   'web.session.started',
   'web.session.exited',
+  'web.session.stop_requested',
   'tmux.session.attached',
   'tmux.session.detached',
   'tmux.session.exited',
+  'tmux.session.restarted',
+  'tmux.session.rebound',
+  'tmux.session.gc',
   'run.session.started',
   'run.session.exited'
 ]);

package/lib/core/peers/identity.mjs

@@ -43,8 +43,16 @@ export function autoPeerId(ctx, kindHint = 'shell', observation = {}) {
 }
 
 export function resolveCurrentPeer(ctx, opts = {}, key = 'peer', kindHint = 'shell', observation = {}) {
-  if (opts[key]) return { id: opts[key], auto: false };
-  if (observation.env?.HCC_PEER) return { id: observation.env.HCC_PEER, auto: false };
+  const explicit = opts[key] || '';
+  const envPeer = observation.env?.HCC_PEER || '';
+  if (envPeer) {
+    return {
+      id: envPeer,
+      auto: false,
+      corrected_from: explicit && explicit !== envPeer ? explicit : null
+    };
+  }
+  if (explicit) return { id: explicit, auto: false, corrected_from: null };
   return { id: autoPeerId(ctx, kindHint, observation), auto: true };
 }
 

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_SKIP_SHIM_INSTALL',
   PROVIDER_STATE_ENV,
   'HCC_SHIM_ENSURED',
   'HCC_SHIM_NO_ATTACH',

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
@@ -138,15 +145,20 @@ if detect_current_hcc_pane; then
     PEER_ID="$SESSION_PEER_ID"
   fi
   export HCC_PEER="$PEER_ID"
-  "$HCC_BIN" web >/dev/null 2>&1 || true
+  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
   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_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
 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
   printf '%s\\n' "$START_OUT" >&2
@@ -164,17 +176,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 +197,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 +332,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 +343,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
@@ -343,15 +358,20 @@ if detect_current_hcc_pane; then
     PEER_ID="$SESSION_PEER_ID"
   fi
   export HCC_PEER="$PEER_ID"
-  "$HCC_BIN" web >/dev/null 2>&1 || true
+  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
   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_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
 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
   printf '%s\\n' "$START_OUT" >&2
@@ -369,16 +389,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/setup.mjs

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

package/lib/shell-path.mjs

@@ -2,26 +2,28 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
-export function pathEntryLine(shellType) {
-  if (shellType === 'fish') return 'set -gx PATH $HOME/.hcc-shims $PATH  # hello-cc shims';
-  return '_hcc_shims="$HOME/.hcc-shims"; PATH="${PATH//:${_hcc_shims}:/:}"; PATH="${PATH#${_hcc_shims}:}"; PATH="${PATH%:${_hcc_shims}}"; export PATH="${_hcc_shims}:$PATH"; unset _hcc_shims  # hello-cc shims';
+export function pathEntryLine(shellType, position = 'final') {
+  const suffix = position === 'early' ? 'early' : 'final';
+  if (shellType === 'fish') return `set -gx PATH $HOME/.hcc-shims $PATH  # hello-cc shims (${suffix})`;
+  return `_hcc_shims="$HOME/.hcc-shims"; PATH="\${PATH//:\${_hcc_shims}:/:}"; PATH="\${PATH#\${_hcc_shims}:}"; PATH="\${PATH%:\${_hcc_shims}}"; export PATH="\${_hcc_shims}:$PATH"; unset _hcc_shims  # hello-cc shims (${suffix})`;
 }
 
 export function removePathEntryLines(content) {
   return String(content || '')
     .split('\n')
-    .filter(line => !line.includes('.hcc-shims'))
+    .filter(line => !isHelloCcShimPathLine(line))
     .join('\n')
     .replace(/\n{3,}/g, '\n\n')
     .replace(/\s+$/, '');
 }
 
 export function insertPathEntry(content, shellType) {
-  const line = pathEntryLine(shellType);
   const cleaned = removePathEntryLines(content);
-  if (shellType === 'fish') return `${cleaned}${cleaned ? '\n' : ''}${line}\n`;
+  const finalLine = pathEntryLine(shellType, 'final');
+  if (shellType === 'fish' || shellType === 'zsh') return `${cleaned}${cleaned ? '\n' : ''}${finalLine}\n`;
 
   const lines = cleaned ? cleaned.split('\n') : [];
+  const earlyLine = pathEntryLine(shellType, 'early');
   let insertAt = 0;
   if (lines[0]?.startsWith('#!')) insertAt = 1;
   for (let i = insertAt; i < lines.length; i += 1) {
@@ -30,9 +32,9 @@ export function insertPathEntry(content, shellType) {
     insertAt = i;
     break;
   }
-  lines.splice(insertAt, 0, line);
+  lines.splice(insertAt, 0, earlyLine);
   const withEarlyEntry = lines.join('\n').replace(/\s+$/, '');
-  return `${withEarlyEntry}${withEarlyEntry ? '\n' : ''}${line}\n`;
+  return `${withEarlyEntry}${withEarlyEntry ? '\n' : ''}${finalLine}\n`;
 }
 
 export function detectShellRc() {
@@ -49,21 +51,34 @@ export function installPathEntry() {
 
   const next = insertPathEntry(content, shellType);
   const alreadyPresent = next === (content.endsWith('\n') ? content : `${content}\n`);
-  if (!alreadyPresent) fs.writeFileSync(rcFile, next);
+  if (!alreadyPresent) {
+    fs.mkdirSync(path.dirname(rcFile), { recursive: true });
+    fs.writeFileSync(rcFile, next);
+  }
   return { rcFile, shellType, alreadyPresent };
 }
 
 export function uninstallPathEntry() {
   const { path: rcFile } = detectShellRc();
+  let content = '';
+  try {
+    content = fs.readFileSync(rcFile, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { rcFile, removed: false, missing: true };
+    return { rcFile, removed: false, error: 'could not read shell rc' };
+  }
+  const filtered = removePathEntryLines(content);
+  if (filtered === content.replace(/\s+$/, '')) {
+    return { rcFile, removed: false };
+  }
   try {
-    const content = fs.readFileSync(rcFile, 'utf8');
-    const filtered = content
-      .split('\n')
-      .filter(line => !line.includes('.hcc-shims'))
-      .join('\n');
     fs.writeFileSync(rcFile, filtered);
-    return { rcFile };
+    return { rcFile, removed: true };
   } catch {
-    return { rcFile, error: 'could not modify shell rc' };
+    return { rcFile, removed: false, error: 'could not modify shell rc' };
   }
 }
+
+function isHelloCcShimPathLine(line) {
+  return String(line || '').includes('# hello-cc shims');
+}