@logicseek/hello-cc 0.1.7 → 0.1.8

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/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,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');
+}

package/lib/ui/help.mjs

@@ -60,6 +60,8 @@ Environment:
 
 Usage:
   ${cliName} task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
+  ${cliName} task dispatch --to ID --title TEXT [--body TEXT] [--from ID] [--message TEXT] [--no-inject] [--force]
+  ${cliName} task dispatch --to ID --id N [--from ID] [--message TEXT] [--no-inject] [--force]
   ${cliName} task create --title TEXT --parent N [--team-role ROLE]
   ${cliName} task list [--status pending|claimed|running|review|blocked|done|abandoned] [--peer ID] [--all]
   ${cliName} task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
@@ -74,6 +76,11 @@ Messages use per-peer unread ack state; tasks do not.
 task next returns your existing claimed/running/review/blocked task before
 claiming another pending task. Use --force when intentionally taking additional
 pending tasks; combine it with --count N for explicit batch claims.
+task dispatch explicitly assigns a new or existing task to one peer, sends a
+durable task message, and injects the startup prompt only when the peer has a
+running managed Claude/Codex terminal. Use --no-inject for message-only
+dispatch; use --force only when intentionally injecting while the target already
+owns another active task.
 Use task takeover when explicitly taking over a non-complete task from another
 owner; it records the previous owner, requires a reason, and notifies them.
 Use --policy blocked, stale, or blocked-or-stale to require an auditable
@@ -380,7 +387,7 @@ Usage:
   ${cliName} uninstall [--purge --yes]
 
 Stops the current project runtime and removes user-level hello-cc integrations:
-Claude/Codex hooks and claude/codex shims.
+Claude/Codex hooks, claude/codex shims, and the shell PATH entry for shims.
 
 With --purge --yes, also removes current project data:
   .hello-cc/
@@ -388,6 +395,34 @@ With --purge --yes, also removes current project data:
 `);
     },
 
+    helpInstallHooks() {
+      console.log(`${cliName} install-hooks
+
+Usage:
+  ${cliName} install-hooks
+  ${cliName} install-hooks --status
+  ${cliName} install-hooks --uninstall
+
+Installs, checks, or removes Claude Code and Codex hook entries used by
+hello-cc. This is a maintenance command; hcc up, hcc web, and hcc setup install
+hooks automatically when needed.
+`);
+    },
+
+    helpShim() {
+      console.log(`${cliName} shim
+
+Usage:
+  ${cliName} shim install
+  ${cliName} shim status
+  ${cliName} shim uninstall
+
+Installs, checks, or removes claude/codex shims in ~/.hcc-shims and manages the
+shell PATH entry for that directory. hcc web and hcc setup install shims
+automatically when provider CLIs are available on PATH.
+`);
+    },
+
     helpWeb() {
       console.log(`${cliName} web
 

package/package.json

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