@logicseek/hello-cc 0.1.7 → 0.1.8

package/bin/hcc.mjs

@@ -227,6 +227,8 @@ const {
   helpDown,
   helpUpdate,
   helpUninstall,
+  helpInstallHooks,
+  helpShim,
   helpWeb
 } = createHelpFunctions({
   productName: PRODUCT_NAME,
@@ -279,7 +281,11 @@ function splitProcessArgs(line) {
 
 function sameResolvedPath(a, b) {
   if (!a || !b) return false;
-  return path.resolve(a) === path.resolve(b);
+  function key(value) {
+    try { return fs.realpathSync(value); }
+    catch { return path.resolve(value); }
+  }
+  return key(a) === key(b);
 }
 
 const {
@@ -731,6 +737,7 @@ async function cmdTask(ctx, args) {
   const sub = args[0];
   if (!sub || wantsHelp(args)) return helpTask();
   if (sub === 'create') return taskCreate(ctx, args.slice(1));
+  if (sub === 'dispatch') return taskDispatch(ctx, args.slice(1));
   if (sub === 'list') return taskList(ctx, args.slice(1));
   if (sub === 'claim') return taskClaim(ctx, args.slice(1));
   if (sub === 'takeover') return taskTakeover(ctx, args.slice(1));
@@ -772,6 +779,201 @@ async function taskCreate(ctx, args) {
     (data) => `created task #${data.id}: ${data.title}${data.assignee ? ` -> ${data.assignee}` : ''}${data.parent_id ? ` (child of #${data.parent_id})` : ''}`);
 }
 
+function dispatchPromptText(task, customMessage = null) {
+  if (customMessage) return customMessage;
+  return [
+    `Please pick up hello-cc task #${task.id}: ${task.title}.`,
+    `Run hcc task claim --id ${task.id}, then follow project coordination rules, create a handoff, and mark the task done when finished.`
+  ].join(' ');
+}
+
+function currentOwnedTaskForPeer(db, peer) {
+  return db.prepare(`
+    SELECT *
+    FROM tasks
+    WHERE owner = ?
+      AND status IN ('claimed', 'running', 'review', 'blocked')
+    ORDER BY
+      CASE status
+        WHEN 'running' THEN 0
+        WHEN 'claimed' THEN 1
+        WHEN 'review' THEN 2
+        WHEN 'blocked' THEN 3
+        ELSE 4
+      END,
+      priority ASC,
+      id ASC
+    LIMIT 1
+  `).get(peer);
+}
+
+function findRuntimeSessionForPeer(runtimeData, peer) {
+  return (runtimeData?.sessions || []).find((session) => {
+    const sessionPeer = session.peer_id || session.id;
+    return session.status === 'running' && (session.id === peer || sessionPeer === peer);
+  }) || null;
+}
+
+function sessionLooksProviderInteractive(session) {
+  if (!['claude', 'codex'].includes(session?.kind)) return false;
+  if (session.provider_session_known) return true;
+  const command = String(session.command || '');
+  if (/^tmux\s+%/.test(command)) return false;
+  return /\b(?:claude|codex)(?:\s|$)/.test(command);
+}
+
+async function taskDispatch(ctx, args) {
+  const opts = parseOpts(args, { booleans: ['force', 'no-inject'] });
+  const identity = resolveCurrentPeer(ctx, opts, 'from', 'shell');
+  const actor = identity.id;
+  const target = required(opts, 'to');
+  const requestedTaskId = intOpt(opts, 'id', intOpt({ id: opts._[0] }, 'id'));
+  const title = requestedTaskId ? (opts.title || null) : required(opts, 'title');
+  const body = opts.body || '';
+  const priority = intOpt(opts, 'priority', 100);
+  const customMessage = opts.message ? String(opts.message) : null;
+  const injectAllowed = !Boolean(opts['no-inject']);
+
+  let task = null;
+  let messageId = null;
+  let currentTask = null;
+  let previousAssignee = null;
+  const db = connect(ctx);
+  try {
+    touchCurrentPeer(db, ctx, identity, null, 'shell');
+    const t = now();
+    task = tx(db, () => {
+      if (requestedTaskId) {
+        const existing = db.prepare('SELECT * FROM tasks WHERE id = ?').get(requestedTaskId);
+        if (!existing) throw new CliError('NOT_FOUND', `Task #${requestedTaskId} does not exist`);
+        if (['done', 'abandoned'].includes(existing.status)) {
+          throw new CliError('BAD_STATE', `Task #${requestedTaskId} is ${existing.status}`);
+        }
+        if (existing.owner && existing.owner !== target) {
+          throw new CliError('TASK_OWNED', `Task #${requestedTaskId} is owned by ${existing.owner}`, {
+            owner: existing.owner,
+            task_id: requestedTaskId,
+            attempted_by: actor,
+            target
+          });
+        }
+        previousAssignee = existing.assignee || null;
+        db.prepare('UPDATE tasks SET assignee = ?, updated_at = ? WHERE id = ?').run(target, t, requestedTaskId);
+        return db.prepare('SELECT * FROM tasks WHERE id = ?').get(requestedTaskId);
+      }
+      const info = db.prepare(`
+        INSERT INTO tasks(title, body, status, assignee, owner, parent_id, team_role, priority, created_by, created_at, updated_at)
+        VALUES (?, ?, 'pending', ?, NULL, NULL, NULL, ?, ?, ?, ?)
+      `).run(title, body, target, priority, actor, t, t);
+      const taskId = Number(info.lastInsertRowid);
+      addEvent(db, 'task.created', actor, taskId, { title, assignee: target, priority, parent_id: null, team_role: null });
+      return db.prepare('SELECT * FROM tasks WHERE id = ?').get(taskId);
+    });
+    const durableMessage = dispatchPromptText(task, customMessage);
+    messageId = sendMessage(db, actor, target, task.id, 'task', durableMessage);
+    currentTask = currentOwnedTaskForPeer(db, target);
+  } finally {
+    db.close();
+  }
+
+  const durableMessage = dispatchPromptText(task, customMessage);
+  let session = null;
+  let injected = false;
+  let injectionReason = injectAllowed ? 'runtime_unavailable' : 'no_inject';
+  const busyTask = currentTask && Number(currentTask.id) !== Number(task.id) ? currentTask : null;
+  if (injectAllowed) {
+    let runtime = null;
+    let runtimeData = null;
+    try {
+      runtime = readRuntime(ctx);
+      runtimeData = await runtimeRequest(ctx, 'GET', '/api/sessions', null, runtime);
+    } catch (err) {
+      if (!(err instanceof CliError) || !['RUNTIME_NOT_RUNNING', 'RUNTIME_UNREACHABLE'].includes(err.code)) throw err;
+    }
+    session = runtimeData ? findRuntimeSessionForPeer(runtimeData, target) : null;
+    if (!session) {
+      injectionReason = runtimeData ? 'session_not_running' : 'runtime_unavailable';
+    } else if (!customMessage && !sessionLooksProviderInteractive(session)) {
+      injectionReason = 'unsupported_session_kind';
+    } else if (busyTask && !Boolean(opts.force)) {
+      injectionReason = 'target_busy';
+    } else {
+      try {
+        await injectPeer(ctx, target, durableMessage, true, runtime, actor);
+        injected = true;
+        injectionReason = 'injected';
+      } catch (err) {
+        if (!(err instanceof CliError)) throw err;
+        if (['RUNTIME_NOT_RUNNING', 'RUNTIME_UNREACHABLE'].includes(err.code)) {
+          injectionReason = 'runtime_unavailable';
+        } else if (['NOT_FOUND', 'SESSION_NOT_RUNNING'].includes(err.code)) {
+          injectionReason = 'session_not_running';
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+
+  const eventDb = connect(ctx);
+  try {
+    addEvent(eventDb, 'task.dispatched', actor, task.id, auditPayload({
+      actor,
+      target,
+      source: 'cli',
+      admin: actor !== target,
+      peer: target,
+      title: task.title,
+      message_id: messageId,
+      injected,
+      delivery: injected ? 'message+inject' : 'message-only',
+      injection_reason: injectionReason,
+      session_id: session?.id || null,
+      session_kind: session?.kind || null,
+      previous_assignee: previousAssignee,
+      blocked_by_task_id: busyTask?.id || null
+    }));
+  } finally {
+    eventDb.close();
+  }
+
+  const result = {
+    task,
+    target,
+    message_id: messageId,
+    message: durableMessage,
+    injected,
+    delivery: injected ? 'message+inject' : 'message-only',
+    injection_reason: injectionReason,
+    session: session ? {
+      id: session.id,
+      peer_id: session.peer_id || session.id,
+      kind: session.kind,
+      status: session.status
+    } : null,
+    previous_assignee: previousAssignee,
+    blocked_by_task: busyTask ? {
+      id: busyTask.id,
+      status: busyTask.status,
+      title: busyTask.title
+    } : null
+  };
+  printResult(ctx, result, (data) => {
+    const base = `dispatched task #${data.task.id} to ${data.target} with message #${data.message_id}`;
+    if (data.injected) return `${base} and injected live input`;
+    if (data.injection_reason === 'target_busy' && data.blocked_by_task) {
+      return `${base} (not injected: ${data.target} already owns task #${data.blocked_by_task.id})`;
+    }
+    if (data.injection_reason === 'unsupported_session_kind' && data.session) {
+      return `${base} (not injected: managed ${data.session.kind} session needs an explicit shell-safe message)`;
+    }
+    if (data.injection_reason === 'session_not_running') return `${base} (not injected: target is not a running managed session)`;
+    if (data.injection_reason === 'runtime_unavailable') return `${base} (not injected: web runtime is unavailable)`;
+    if (data.injection_reason === 'no_inject') return `${base} (message only)`;
+    return `${base} (not injected: ${data.injection_reason})`;
+  });
+}
+
 async function taskList(ctx, args) {
   const opts = parseOpts(args, { booleans: ['all'] });
   const status = opts.status || null;
@@ -1195,7 +1397,7 @@ async function cmdAsk(ctx, args) {
   const id = sendMessage(db, sender, recipient, taskId, kind, body);
   let injected = false;
   if (opts.inject) {
-    await injectPeer(ctx, recipient, body, !opts['no-enter'], runtime);
+    await injectPeer(ctx, recipient, body, !opts['no-enter'], runtime, sender);
     injected = true;
   }
   printResult(ctx, { id, sender, recipient, task_id: taskId, kind, body, injected }, (data) => `asked ${data.recipient} with message #${data.id}${data.injected ? ' and injected terminal input' : ''}`);
@@ -1219,15 +1421,15 @@ async function cmdBroadcast(ctx, args) {
     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);
+      await injectPeer(ctx, session.id, body, !opts['no-enter'], runtime, sender);
       injected += 1;
     }
   }
   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)` : ''}`);
 }
 
-async function injectPeer(ctx, peer, text, enter = true, runtime = null) {
-  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
+async function injectPeer(ctx, peer, text, enter = true, runtime = null, auditActor = null) {
+  const actor = auditActor || resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
   const db = connect(ctx);
   try {
     addEvent(db, 'web.session.input.requested', actor, null, auditPayload({
@@ -1731,6 +1933,7 @@ async function cmdUp(ctx, args) {
     if (r.hooks.claudeInstalled) lines.push('Claude Code hooks installed');
     if (r.hooks.codexInstalled) lines.push('Codex hooks installed');
     if (r.detected.length) lines.push(`detected: ${r.detected.map((s) => s.peerId).join(', ')}`);
+    if (r.warnings?.length) lines.push(...r.warnings.map((warning) => `warning: ${warning}`));
     lines.push('web: run hcc web when you need browser terminal control');
     return lines.join('\n');
   });
@@ -1747,31 +1950,42 @@ async function prepareLocalBus(ctx, opts = {}) {
 
   const hooks = { claudeInstalled: false, codexInstalled: false };
   const shims = { installed: [], skipped: [], pathUpdated: false, rcFile: null };
+  const warnings = [];
   try {
-    const { verifyClaudeHooks, installClaudeHooks,
-            verifyCodexHooks, installCodexHooks,
-            installShims, installPathEntry } = await loadSetup();
-    if (!verifyClaudeHooks()) {
-      installClaudeHooks(commandPath());
-      hooks.claudeInstalled = true;
-    }
-    if (!verifyCodexHooks()) {
-      try {
-        installCodexHooks(commandPath());
+    const setup = await loadSetup();
+    try {
+      if (!setup.verifyClaudeHooks()) {
+        setup.installClaudeHooks(commandPath());
+        hooks.claudeInstalled = true;
+      }
+    } catch (err) {
+      warnings.push(`Claude Code hooks installation failed: ${err.message}`);
+    }
+    try {
+      if (!setup.verifyCodexHooks()) {
+        setup.installCodexHooks(commandPath());
         hooks.codexInstalled = true;
-      } catch {}
+      }
+    } catch (err) {
+      warnings.push(`Codex hooks installation failed: ${err.message}`);
     }
     if (opts.installShims) {
-      const result = installShims(commandPath());
-      shims.installed = result.installed;
-      shims.skipped = result.skipped;
-      if (result.installed.length) {
-        const pathResult = installPathEntry();
-        shims.pathUpdated = !pathResult.alreadyPresent;
-        shims.rcFile = pathResult.rcFile;
+      try {
+        const result = setup.installShims(commandPath());
+        shims.installed = result.installed;
+        shims.skipped = result.skipped;
+        if (result.installed.length) {
+          const pathResult = setup.installPathEntry();
+          shims.pathUpdated = !pathResult.alreadyPresent;
+          shims.rcFile = pathResult.rcFile;
+        }
+      } catch (err) {
+        warnings.push(`shim installation failed: ${err.message}`);
       }
     }
-  } catch {}
+  } catch (err) {
+    warnings.push(`local integration setup failed: ${err.message}`);
+  }
 
   const detected = [];
   if (!opts['no-discover']) {
@@ -1781,7 +1995,7 @@ async function prepareLocalBus(ctx, opts = {}) {
         ...scanClaudeSessions(),
         ...scanCodexSessions(),
         ...scanProcesses(),
-      ].filter((s) => s.hccRoot === ctx.root);
+      ].filter((s) => sameResolvedPath(s.hccRoot, ctx.root));
       const byId = new Map();
       for (const s of found) {
         if (!byId.has(s.peerId)) byId.set(s.peerId, s);
@@ -1814,7 +2028,8 @@ async function prepareLocalBus(ctx, opts = {}) {
     guidance,
     hooks,
     shims,
-    detected
+    detected,
+    warnings
   };
 }
 
@@ -1870,7 +2085,10 @@ async function startWebBackground(ctx, args) {
   validateOpts('web', opts, ['host', 'port', 'token', 'local', 'no-token', 'no-guidance', 'no-discover']);
   validateWebTokenOpts(opts);
   ensureTmuxAvailable({ autoInstall: true });
-  const setup = await prepareLocalBus(ctx, { ...opts, installShims: true });
+  const setup = await prepareLocalBus(ctx, {
+    ...opts,
+    installShims: process.env.HCC_SKIP_SHIM_INSTALL === '1' ? false : true
+  });
   registerProject(ctx);
 
   const existing = await readHealthyGlobalRuntime();
@@ -1994,6 +2212,9 @@ function printWebRuntime(ctx, runtime, opts = {}) {
         lines.push(`PATH updated in ${opts.setup.shims.rcFile}; open a new terminal or source it`);
       }
     }
+    if (opts.setup?.warnings?.length) {
+      lines.push(...opts.setup.warnings.map((warning) => `warning: ${warning}`));
+    }
     lines.push(`stop: ${r.stop}`);
     return lines.join('\n');
   });
@@ -2041,7 +2262,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
 
   function knownProjects() {
     const rows = readProjectRegistry();
-    if (!rows.some((p) => p.root === ctx.root)) rows.unshift(projectRecord(ctx));
+    if (!rows.some((p) => sameResolvedPath(p.root, ctx.root))) rows.unshift(projectRecord(ctx));
     for (const project of rows) {
       if (!projectContexts.has(project.root)) {
         projectContexts.set(project.root, contextForProject(project.root, project.db, { json: ctx.json }));
@@ -2066,7 +2287,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   }
 
   function sessionsForProject(projectCtx) {
-    return [...sessions.values()].filter((session) => session.root === projectCtx.root);
+    return [...sessions.values()].filter((session) => sameResolvedPath(session.root, projectCtx.root));
   }
 
   function getSession(projectCtx, id, db = null) {
@@ -2538,6 +2759,18 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     return open;
   }
 
+  function closeSessionClients(session) {
+    if (!session?.clients?.size) return;
+    for (const client of [...session.clients]) {
+      try {
+        if (client.readyState === client.OPEN || client.readyState === 1) client.close(1001, 'runtime stopping');
+        else if (typeof client.terminate === 'function') client.terminate();
+      } catch {
+        try { if (typeof client.terminate === 'function') client.terminate(); } catch {}
+      }
+    }
+  }
+
   function detachTmuxSession(session, status = 'detached') {
     stopTmuxStream(session);
     if (session.exitPoller) { clearInterval(session.exitPoller); session.exitPoller = null; }
@@ -4089,11 +4322,15 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     });
   });
 
+  let shuttingDown = false;
   function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
     clearRuntime(ctx);
     clearInterval(externalScanPoller);
     clearInterval(autoAttachPoller);
     for (const session of sessions.values()) {
+      closeSessionClients(session);
       if (session.status !== 'running') continue;
       if (session.type === 'external') {
         try { if (session.outputFd) fs.closeSync(session.outputFd); } catch {}
@@ -4106,7 +4343,28 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         try { session.pty.kill(); } catch {}
       }
     }
-    server.close(() => process.exit(0));
+    try { wss.close(); } catch {}
+    const terminateClients = setTimeout(() => {
+      for (const session of sessions.values()) {
+        for (const client of [...(session.clients || [])]) {
+          try { if (typeof client.terminate === 'function') client.terminate(); } catch {}
+        }
+      }
+      try { server.closeAllConnections?.(); } catch {}
+    }, 250);
+    const forceExit = setTimeout(() => process.exit(0), 1500);
+    try {
+      server.close(() => {
+        clearTimeout(terminateClients);
+        clearTimeout(forceExit);
+        process.exit(0);
+      });
+      try { server.closeIdleConnections?.(); } catch {}
+    } catch {
+      clearTimeout(terminateClients);
+      clearTimeout(forceExit);
+      process.exit(0);
+    }
   }
   process.once('SIGINT', shutdown);
   process.once('SIGTERM', shutdown);
@@ -4556,6 +4814,7 @@ async function cmdHook(ctx, args) {
 // ─── hcc install-hooks ───────────────────────────────────────────────────────
 
 async function cmdInstallHooks(ctx, args) {
+  if (wantsHelp(args)) return helpInstallHooks();
   const opts = parseOpts(args, { booleans: ['uninstall', 'status'] });
   const { installClaudeHooks, uninstallClaudeHooks, verifyClaudeHooks,
           installCodexHooks, uninstallCodexHooks, verifyCodexHooks } = await loadSetup();
@@ -4585,11 +4844,20 @@ async function cmdInstallHooks(ctx, args) {
     `hooks installed: claude → ${cp}${cxp ? `, codex → ${cxp}` : ''}`);
 }
 
+function pathEntryRemovalMessage(pathEntry) {
+  if (pathEntry.error) return `PATH entry not removed: ${pathEntry.error}`;
+  if (pathEntry.missing) return `PATH entry not present (${pathEntry.rcFile} not found)`;
+  if (pathEntry.removed === false) return `PATH entry not present in ${pathEntry.rcFile}`;
+  return `PATH entry removed from ${pathEntry.rcFile}`;
+}
+
 // ─── hcc shim ────────────────────────────────────────────────────────────────
 
 async function cmdShim(ctx, args) {
   const sub = args[0];
-  const { installShims, uninstallShims, verifyShims, installPathEntry, SHIM_DIR } = await loadSetup();
+  const { installShims, uninstallShims, shimStatus, installPathEntry, uninstallPathEntry, SHIM_DIR } = await loadSetup();
+
+  if (wantsHelp(args)) return helpShim();
 
   if (sub === 'ensure') {
     const name = args[1];
@@ -4597,9 +4865,10 @@ async function cmdShim(ctx, args) {
     if (!['claude', 'codex'].includes(name) || !target) {
       throw new CliError('BAD_ARGS', 'Usage: hcc shim ensure claude|codex PATH');
     }
-    const result = installShims(commandPath());
+    const realBin = args[3] || null;
+    const result = installShims(commandPath(), realBin ? { realBins: { [name]: realBin } } : {});
     const changed = (result.changed || []).map((p) => path.resolve(p));
-    if (changed.includes(target)) {
+    if (changed.some((p) => sameResolvedPath(p, target))) {
       process.exitCode = 75;
       return;
     }
@@ -4609,32 +4878,45 @@ async function cmdShim(ctx, args) {
   if (!sub || sub === 'install') {
     const hccBin = commandPath();
     const result = installShims(hccBin);
-    const { alreadyPresent, rcFile } = installPathEntry();
     const lines = [
       result.installed.length
         ? `shims installed:\n${result.installed.map((p) => `  ${p}`).join('\n')}`
         : 'no shims installed (claude/codex not found on PATH)',
     ];
     if (result.skipped.length) lines.push(`skipped: ${result.skipped.join(', ')}`);
-    if (!alreadyPresent) {
-      lines.push(`PATH updated in ${rcFile}`);
-      lines.push(`run: source ${rcFile}  (or open a new terminal)`);
-    } else {
-      lines.push(`PATH entry already present in ${rcFile}`);
+    if (result.installed.length) {
+      const { alreadyPresent, rcFile } = installPathEntry();
+      if (!alreadyPresent) {
+        lines.push(`PATH updated in ${rcFile}`);
+        lines.push(`run: source ${rcFile}  (or open a new terminal)`);
+      } else {
+        lines.push(`PATH entry already present in ${rcFile}`);
+      }
     }
     printResult(ctx, result, () => lines.join('\n'));
     return;
   }
   if (sub === 'uninstall') {
     const removed = uninstallShims();
-    printResult(ctx, { removed }, () => removed.length ? `removed: ${removed.join(', ')}` : 'no shims to remove');
+    const pathEntry = uninstallPathEntry();
+    printResult(ctx, { removed, path_entry: pathEntry }, () => [
+      removed.length ? `removed: ${removed.join(', ')}` : 'no shims to remove',
+      pathEntryRemovalMessage(pathEntry)
+    ].join('\n'));
     return;
   }
   if (sub === 'status') {
-    const installed = verifyShims();
-    printResult(ctx, { installed, shim_dir: SHIM_DIR }, () =>
-      installed ? `shims installed in ${SHIM_DIR} ✓` : `shims not installed (run: hcc web)`
-    );
+    const status = shimStatus();
+    printResult(ctx, status, (r) => [
+      `shim dir: ${r.shimDir}`,
+      `claude: ${r.tools.claude.installed ? 'installed' : 'missing'} (${r.tools.claude.path})`,
+      `codex: ${r.tools.codex.installed ? 'installed' : 'missing'} (${r.tools.codex.path})`,
+      r.complete
+        ? 'status: complete'
+        : r.installed
+          ? 'status: partial (run: hcc shim install)'
+          : 'status: not installed (run: hcc shim install)'
+    ].join('\n'));
     return;
   }
   throw new CliError('BAD_ARGS', `Unknown shim subcommand: ${sub}`);
@@ -4660,7 +4942,7 @@ async function cmdSetup(ctx, args) {
 
   // 2. Install Claude Code + Codex hooks
   const { installClaudeHooks, verifyClaudeHooks, installCodexHooks, verifyCodexHooks,
-          installShims, verifyShims, installPathEntry } = await loadSetup();
+          installShims, installPathEntry } = await loadSetup();
   const hccBin = commandPath();
 
   if (!verifyClaudeHooks()) {
@@ -4678,20 +4960,23 @@ async function cmdSetup(ctx, args) {
   }
 
   // 3. Install shims
-  if (!verifyShims()) {
-    const result = installShims(hccBin);
-    if (result.installed.length) {
-      log(`✓  shims installed → ${result.installed.join(', ')}`);
+  const result = installShims(hccBin);
+  if (result.installed.length) {
+    if (result.changed.length) {
+      log(`✓  shims installed → ${result.changed.join(', ')}`);
     } else {
-      log('⚠  shims: claude/codex not found on PATH — skipped');
+      log(`✓  shims already installed → ${result.installed.join(', ')}`);
     }
+    if (result.skipped.length) log(`⚠  shims skipped: ${result.skipped.join(', ')}`);
     const { alreadyPresent, rcFile } = installPathEntry();
     if (!alreadyPresent) {
       log(`✓  PATH updated in ${rcFile}`);
       log(`   run: source ${rcFile}  (or open a new terminal)`);
+    } else {
+      log(`✓  PATH entry already present in ${rcFile}`);
     }
   } else {
-    log('✓  shims already installed');
+    log('⚠  shims: claude/codex not found on PATH — skipped');
   }
 
   log('\nDone. Run `hcc web` for the default coordinated terminal experience.');
@@ -4771,13 +5056,15 @@ async function cmdUninstall(ctx, args) {
     lines.push('runtime not running');
   }
 
-  const { uninstallClaudeHooks, uninstallCodexHooks, uninstallShims } = await loadSetup();
+  const { uninstallClaudeHooks, uninstallCodexHooks, uninstallShims, uninstallPathEntry } = await loadSetup();
   const claude = uninstallClaudeHooks();
   const codex = uninstallCodexHooks();
   const shims = uninstallShims();
+  const pathEntry = uninstallPathEntry();
   lines.push(claude ? 'Claude Code hooks removed' : 'Claude Code hooks not found');
   lines.push(codex ? 'Codex hooks removed' : 'Codex hooks not found');
   lines.push(shims.length ? `shims removed: ${shims.join(', ')}` : 'shims not found');
+  lines.push(pathEntryRemovalMessage(pathEntry));
 
   let guidance = [];
   let purged = false;
@@ -4795,7 +5082,7 @@ async function cmdUninstall(ctx, args) {
     lines.push('project data kept; run hcc uninstall --purge --yes to remove .hello-cc and guidance blocks');
   }
 
-  printResult(ctx, { runtime: Boolean(runtime), claude, codex, shims, purge: purged, guidance }, () => lines.join('\n'));
+  printResult(ctx, { runtime: Boolean(runtime), claude, codex, shims, path_entry: pathEntry, purge: purged, guidance }, () => lines.join('\n'));
 }
 
 // ─── hcc scan ────────────────────────────────────────────────────────────────
@@ -4808,7 +5095,7 @@ async function cmdScan(ctx, args) {
     ...scanClaudeSessions(),
     ...scanCodexSessions(),
     ...scanProcesses(),
-  ].filter((s) => s.hccRoot === ctx.root);
+  ].filter((s) => sameResolvedPath(s.hccRoot, ctx.root));
 
   // Deduplicate by peerId
   const byId = new Map();

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