@logicseek/hello-cc 0.1.6 → 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 {
@@ -291,6 +297,7 @@ const {
   sendMessage
 } = createMessageStore({ now, addEvent });
 const {
+  assertTaskOwnerForMutation,
   claimNextTasksForPeer,
   claimTaskRowsForPeer,
   queryOpenTasks,
@@ -325,6 +332,7 @@ const {
 } = createWebPeerActions({
   activePeerTtl: ACTIVE_PEER_TTL,
   addEvent,
+  assertTaskOwnerForMutation,
   claimNextTasksForPeer,
   connect,
   defaultLockTtl: DEFAULT_LOCK_TTL,
@@ -351,6 +359,15 @@ function iso(ts) {
   return new Date(ts * 1000).toISOString();
 }
 
+function webErrorStatus(err) {
+  if (!(err instanceof CliError)) return 500;
+  if (['BAD_ARGS', 'BAD_REQUEST', 'PEER_IDENTITY_REQUIRED', 'REQUEST_TOO_LARGE'].includes(err.code)) return 400;
+  if (['PEER_IDENTITY_MISMATCH', 'TASK_OWNED', 'LOCK_OWNED'].includes(err.code)) return 403;
+  if (['NOT_FOUND'].includes(err.code)) return 404;
+  if (['LOCK_HELD', 'SESSION_NOT_RUNNING'].includes(err.code)) return 409;
+  return 500;
+}
+
 function autoPeerDefaults(ctx, kindHint = 'shell', status = 'working') {
   const kind = autoPeerKind(kindHint);
   const ancestor = readAncestorCliInfo();
@@ -369,6 +386,11 @@ function shellCommand(args) {
   return shellCommandWithQuote(args, shellQuoteArg);
 }
 
+function resolveTargetPeer(ctx, opts = {}, key = 'peer', kindHint = 'shell') {
+  if (opts[key]) return { id: opts[key], auto: false, target: true };
+  return resolveCurrentPeer(ctx, opts, key, kindHint);
+}
+
 let projectMigrationFanoutDepth = 0;
 const migratedRegisteredProjectDbs = new Set();
 
@@ -426,6 +448,22 @@ function addEvent(db, type, actor, taskId, payload) {
   `).run(type, actor || null, taskId || null, JSON.stringify(payload || {}), now());
 }
 
+function auditPayload({ actor = null, target = null, source = 'cli', admin = false, ...extra } = {}) {
+  const payload = { ...extra, source };
+  if (actor) payload.actor_peer = actor;
+  if (target) payload.target_peer = target;
+  if (admin) payload.admin = true;
+  return payload;
+}
+
+function requestActorPeer(input = {}, fallback = 'web') {
+  return String(input.auditActorPeer || fallback || 'web').trim() || 'web';
+}
+
+function requestSource(input = {}, fallback = 'web') {
+  return String(input.auditSource || fallback || 'web').trim() || fallback;
+}
+
 function latestHookProviderSession(db, peer) {
   if (!peer) return null;
   try {
@@ -583,7 +621,8 @@ async function cmdInit(ctx, args) {
 async function cmdRegister(ctx, args) {
   registerProjectActivity(ctx);
   const opts = parseOpts(args, { arrays: ['cap'] });
-  const id = required(opts, 'peer', 'HCC_PEER');
+  const identity = resolveCurrentPeer(ctx, opts, 'peer', opts.kind || 'shell');
+  const id = identity.id;
   const db = connect(ctx);
   const peer = {
     id,
@@ -603,7 +642,7 @@ async function cmdRegister(ctx, args) {
 async function cmdEnv(ctx, args) {
   if (args[0] === '--help' || args[0] === '-h') return helpEnv();
   const opts = parseOpts(args);
-  const peer = required(opts, 'peer', 'HCC_PEER');
+  const peer = resolveTargetPeer(ctx, opts, 'peer', 'shell').id;
   const values = {
     HCC_PEER: peer,
     HCC_ROOT: ctx.root,
@@ -616,7 +655,8 @@ async function cmdJoin(ctx, args) {
   if (args[0] === '--help' || args[0] === '-h') return helpJoin();
   registerProjectActivity(ctx);
   const opts = parseOpts(args, { arrays: ['cap'] });
-  const id = required(opts, 'peer', 'HCC_PEER');
+  const identity = resolveCurrentPeer(ctx, opts, 'peer', opts.kind || 'shell');
+  const id = identity.id;
   const peer = {
     id,
     kind: opts.kind || 'other',
@@ -697,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));
@@ -738,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;
@@ -794,10 +1030,39 @@ async function taskClaim(ctx, args) {
   const ids = parseTaskIds(opts);
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, 'working', 'shell');
-  const tasks = claimTaskRowsForPeer(db, peer, ids, { force: Boolean(opts.force) });
+  let tasks;
+  try {
+    tasks = claimTaskRowsForPeer(db, peer, ids, { force: Boolean(opts.force) });
+  } catch (err) {
+    notifyTaskOwnerConflict(ctx, err);
+    throw err;
+  }
   printResult(ctx, ids.length === 1 ? tasks[0] : tasks, (data) => taskRowsText(Array.isArray(data) ? data : [data], 'claimed'));
 }
 
+function notifyTaskOwnerConflict(ctx, err) {
+  if (err?.code !== 'TASK_OWNED' || !err.extra?.notify_owner) return;
+  const { owner, task_id: taskId, attempted_by: attemptedBy, action } = err.extra;
+  if (!owner || !attemptedBy || owner === attemptedBy) return;
+  let db = null;
+  try {
+    db = connect(ctx);
+    sendMessage(
+      db,
+      attemptedBy,
+      owner,
+      taskId || null,
+      'task.owner-conflict',
+      `Task #${taskId} is owned by ${owner}; ${attemptedBy} attempted ${action || 'modify'} and hello-cc left ownership unchanged.`
+    );
+    err.extra.notified = true;
+  } catch {
+    err.extra.notified = false;
+  } finally {
+    try { db?.close(); } catch {}
+  }
+}
+
 async function taskTakeover(ctx, args) {
   const opts = parseOpts(args);
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
@@ -842,25 +1107,29 @@ async function taskUpdate(ctx, args) {
   if (!id) throw new CliError('BAD_ARGS', 'Missing --id');
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, status === 'done' ? 'idle' : 'working', 'shell');
-  const task = tx(db, () => {
-    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 && !opts.force) {
-      throw new CliError('TASK_OWNED', `Task #${id} is owned by ${row.owner}`, { owner: row.owner });
-    }
-    const t = now();
-    const completedAt = status === 'done' ? t : row.completed_at;
-    db.prepare(`
-      UPDATE tasks
-      SET status = ?, completed_at = ?, updated_at = ?
-      WHERE id = ?
-    `).run(status, completedAt, t, id);
-    addEvent(db, `task.${status}`, peer, id, { summary: opts.summary || opts.reason || '' });
-    if (opts.body) {
-      sendMessage(db, peer, opts.to || 'all', id, 'task.update', opts.body);
-    }
-    return db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
-  });
+  let task;
+  try {
+    task = tx(db, () => {
+      const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+      if (!row) throw new CliError('NOT_FOUND', `Task #${id} does not exist`);
+      assertTaskOwnerForMutation(db, peer, row, `update:${status}`);
+      const t = now();
+      const completedAt = status === 'done' ? t : row.completed_at;
+      db.prepare(`
+        UPDATE tasks
+        SET status = ?, completed_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(status, completedAt, t, id);
+      addEvent(db, `task.${status}`, peer, id, { summary: opts.summary || opts.reason || '' });
+      if (opts.body) {
+        sendMessage(db, peer, opts.to || 'all', id, 'task.update', opts.body);
+      }
+      return db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+    });
+  } catch (err) {
+    notifyTaskOwnerConflict(ctx, err);
+    throw err;
+  }
   printResult(ctx, task, (data) => `task #${data.id} -> ${data.status}`);
 }
 
@@ -1128,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' : ''}`);
@@ -1152,15 +1421,33 @@ 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) {
-  return runtimeRequest(ctx, 'POST', `/api/sessions/${encodeURIComponent(peer)}/input`, { text, enter }, runtime);
+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({
+      actor,
+      target: peer,
+      peer,
+      source: 'cli',
+      admin: actor !== peer,
+      bytes: text.length,
+      enter
+    }));
+  } finally {
+    db.close();
+  }
+  return runtimeRequest(ctx, 'POST', `/api/sessions/${encodeURIComponent(peer)}/input`, {
+    text,
+    enter
+  }, runtime);
 }
 
 async function cmdInject(ctx, args) {
@@ -1227,6 +1514,7 @@ async function peerStart(ctx, args) {
   const optArgs = sep >= 0 ? args.slice(0, sep) : args;
   const cmdArgs = sep >= 0 ? args.slice(sep + 1) : [];
   const opts = parseOpts(optArgs, { booleans: ['last', 'continue', 'fork', 'force', 'restart-env'] });
+  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
   const id = opts.peer || opts._[0];
   if (!id) throw new CliError('BAD_ARGS', 'Missing peer');
   const firstCommand = cmdArgs[0] || '';
@@ -1269,6 +1557,17 @@ async function peerStart(ctx, args) {
         status: 'starting',
         capabilities: 'tmux'
       });
+      addEvent(db, 'peer.start.requested', actor, null, auditPayload({
+        actor,
+        target: id,
+        peer: id,
+        source: 'cli',
+        admin: actor !== id,
+        kind,
+        role,
+        command,
+        cwd
+      }));
     });
   } finally {
     db.close();
@@ -1290,6 +1589,7 @@ async function peerStart(ctx, args) {
 
 async function peerAttach(ctx, args) {
   const opts = parseOpts(args, { booleans: ['force'] });
+  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
   const id = opts.peer || opts._[0];
   if (!id) throw new CliError('BAD_ARGS', 'Missing peer');
   const pane = opts.pane || process.env.TMUX_PANE || null;
@@ -1306,6 +1606,22 @@ async function peerAttach(ctx, args) {
     throw e;
   }
   await runtimeRequest(ctx, 'GET', '/api/runtime', null, runtime);
+  const db = connect(ctx);
+  try {
+    addEvent(db, 'peer.attach.requested', actor, null, auditPayload({
+      actor,
+      target: id,
+      peer: id,
+      source: 'cli',
+      admin: actor !== id,
+      pane,
+      kind,
+      role,
+      cwd
+    }));
+  } finally {
+    db.close();
+  }
   const data = await runtimeRequest(ctx, 'POST', '/api/sessions/attach', {
     id,
     kind,
@@ -1319,10 +1635,23 @@ async function peerAttach(ctx, args) {
 
 async function peerStop(ctx, args) {
   const opts = parseOpts(args);
+  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
   const id = opts.peer || opts._[0];
   if (!id) throw new CliError('BAD_ARGS', 'Missing peer');
   let data;
   try {
+    const db = connect(ctx);
+    try {
+      addEvent(db, 'peer.stop.requested', actor, null, auditPayload({
+        actor,
+        target: id,
+        peer: id,
+        source: 'cli',
+        admin: actor !== id
+      }));
+    } finally {
+      db.close();
+    }
     data = await runtimeRequest(ctx, 'POST', `/api/sessions/${encodeURIComponent(id)}/stop`, {});
   } catch (err) {
     if (err instanceof CliError && err.code === 'RUNTIME_NOT_RUNNING') {
@@ -1330,7 +1659,12 @@ async function peerStop(ctx, args) {
       const db = connect(ctx);
       try {
         db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now(), id);
-        addEvent(db, 'peer.stopped', process.env.HCC_PEER || 'human', null, { peer: id });
+        addEvent(db, 'peer.stopped', actor, null, auditPayload({
+          actor,
+          target: id,
+          peer: id,
+          admin: actor !== id
+        }));
       } finally { db.close(); }
       printResult(ctx, { id, status: 'exited' }, (s) => `stopped ${s.id} (no server running — DB marked exited)`);
       return;
@@ -1360,35 +1694,46 @@ async function lockAcquire(ctx, args) {
   const reason = opts.reason || '';
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, 'working', 'shell');
-  const lock = tx(db, () => {
-    const t = now();
-    const activeLocks = db.prepare('SELECT * FROM locks WHERE expires_at > ?').all(t);
-    const conflict = activeLocks.find((row) => locksConflict(row, requested) && row.owner !== peer);
-    if (conflict) {
-      throw new CliError('LOCK_HELD', `Resource ${lockLabel(requested)} conflicts with lock ${lockLabel(conflict)} held by ${conflict.owner}`, {
-        resource: requested.base_resource,
-        scope: requested.scope,
-        lock_resource: conflict.resource,
-        lock_scope: lockScope(conflict),
-        owner: conflict.owner,
-        expires_at: iso(conflict.expires_at)
-      });
-    }
-    const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
-    db.prepare(`
-      INSERT INTO locks(resource, base_resource, scope, owner, task_id, reason, expires_at, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-      ON CONFLICT(resource) DO UPDATE SET
-        base_resource = excluded.base_resource,
-        scope = excluded.scope,
-        owner = excluded.owner,
-        task_id = excluded.task_id,
-        reason = excluded.reason,
-        expires_at = excluded.expires_at
-    `).run(requested.resource, requested.base_resource, requested.scope, peer, taskId, reason, t + ttl, existing ? existing.created_at : t);
-    addEvent(db, 'lock.acquired', peer, taskId, { resource: requested.base_resource, lock_resource: requested.resource, scope: requested.scope, ttl, previous_owner: existing ? existing.owner : null });
-    return db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
-  });
+  let lock;
+  try {
+    lock = tx(db, () => {
+      const t = now();
+      if (taskId) {
+        const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(taskId);
+        if (!task) throw new CliError('NOT_FOUND', `Task #${taskId} does not exist`);
+        assertTaskOwnerForMutation(db, peer, task, 'lock-acquire');
+      }
+      const activeLocks = db.prepare('SELECT * FROM locks WHERE expires_at > ?').all(t);
+      const conflict = activeLocks.find((row) => locksConflict(row, requested) && row.owner !== peer);
+      if (conflict) {
+        throw new CliError('LOCK_HELD', `Resource ${lockLabel(requested)} conflicts with lock ${lockLabel(conflict)} held by ${conflict.owner}`, {
+          resource: requested.base_resource,
+          scope: requested.scope,
+          lock_resource: conflict.resource,
+          lock_scope: lockScope(conflict),
+          owner: conflict.owner,
+          expires_at: iso(conflict.expires_at)
+        });
+      }
+      const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+      db.prepare(`
+        INSERT INTO locks(resource, base_resource, scope, owner, task_id, reason, expires_at, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(resource) DO UPDATE SET
+          base_resource = excluded.base_resource,
+          scope = excluded.scope,
+          owner = excluded.owner,
+          task_id = excluded.task_id,
+          reason = excluded.reason,
+          expires_at = excluded.expires_at
+      `).run(requested.resource, requested.base_resource, requested.scope, peer, taskId, reason, t + ttl, existing ? existing.created_at : t);
+      addEvent(db, 'lock.acquired', peer, taskId, { resource: requested.base_resource, lock_resource: requested.resource, scope: requested.scope, ttl, previous_owner: existing ? existing.owner : null });
+      return db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+    });
+  } catch (err) {
+    notifyTaskOwnerConflict(ctx, err);
+    throw err;
+  }
   printResult(ctx, lock, (data) => `locked ${lockLabel(data)} by ${data.owner} until ${iso(data.expires_at)}`);
 }
 
@@ -1523,7 +1868,7 @@ async function eventTail(ctx, args) {
 
 async function cmdStatus(ctx, args) {
   const opts = parseOpts(args);
-  const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
+  const identity = resolveTargetPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
   const data = statusSummary(ctx, peer, identity);
   printResult(ctx, data, (s) => renderStatusSummary(s, peer));
@@ -1532,7 +1877,7 @@ async function cmdStatus(ctx, args) {
 async function cmdState(ctx, args) {
   if (wantsHelp(args)) return helpState();
   const opts = parseOpts(args, { arrays: ['resource'] });
-  const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
+  const identity = resolveTargetPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
   const resources = normalizeStateResources(opts.resource || opts.resources || []);
   const snapshot = statusSnapshot(ctx, peer, { resources, intent: opts.intent || null, scope: opts.scope || null });
@@ -1588,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');
   });
@@ -1604,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']) {
@@ -1638,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);
@@ -1671,7 +2028,8 @@ async function prepareLocalBus(ctx, opts = {}) {
     guidance,
     hooks,
     shims,
-    detected
+    detected,
+    warnings
   };
 }
 
@@ -1727,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();
@@ -1851,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');
   });
@@ -1885,6 +2249,10 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   const projectContexts = new Map();
   const prepared = await prepareLocalBus(ctx, opts);
 
+  function newSessionActionToken() {
+    return makeWebToken({ token: null });
+  }
+
   function rememberProject(projectCtx) {
     const normalized = contextForProject(projectCtx.root, projectCtx.dbPath, { cwd: projectCtx.cwd, json: ctx.json });
     projectContexts.set(normalized.root, normalized);
@@ -1894,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 }));
@@ -1919,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) {
@@ -1936,6 +2304,38 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     return null;
   }
 
+  function readActionToken(input, req) {
+    const headerToken = req.headers['x-hcc-session-token'];
+    return String(input.action_token || input.actionToken || headerToken || '').trim();
+  }
+
+  function resolveWebActionSession(projectCtx, peer, input, req) {
+    const db = connect(projectCtx);
+    let session;
+    try {
+      session = getSession(projectCtx, peer, db);
+    } finally {
+      db.close();
+    }
+    if (!session || session.status !== 'running') {
+      throw new CliError('PEER_IDENTITY_REQUIRED', `Web peer action requires a running managed session for ${peer}`, { peer });
+    }
+    const actorPeer = session.peerId || peer;
+    if (actorPeer !== peer && session.id !== peer) {
+      throw new CliError('PEER_IDENTITY_MISMATCH', `Web peer action target ${peer} does not match managed session ${actorPeer}`, {
+        peer,
+        actor_peer: actorPeer,
+        session_id: session.id
+      });
+    }
+    const expected = session.actionToken || '';
+    const provided = readActionToken(input, req);
+    if (!expected || provided !== expected) {
+      throw new CliError('PEER_IDENTITY_REQUIRED', `Web peer action for ${peer} requires the managed session action token`, { peer });
+    }
+    return actorPeer;
+  }
+
   function knownPeerIds(projectCtx) {
     const db = connect(projectCtx);
     try {
@@ -1977,6 +2377,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const session = {
       id,
       peerId: id,
+      actionToken: newSessionActionToken(),
       root: pctx.root,
       ctx: pctx,
       kind: meta.kind || 'external',
@@ -2187,7 +2588,9 @@ async function cmdWeb(ctx, args, startMeta = {}) {
             force: false,
             projectCtx: ctx,
             binding,
-            autoAttach: true
+            autoAttach: true,
+            auditActorPeer: 'web-runtime',
+            auditSource: 'runtime'
           });
           attached.peers.add(row.id);
           if (session.peerId) attached.peers.add(session.peerId);
@@ -2331,6 +2734,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       binding,
       provider_session_known: Boolean(providerSessionLabel),
       provider_session_label: providerSessionLabel,
+      action_token: session.actionToken || null,
       warning: session.warning || null
     };
   }
@@ -2355,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; }
@@ -2376,10 +2792,13 @@ async function cmdWeb(ctx, args, startMeta = {}) {
            OR runtime_session_id = ?
            OR (? IS NOT NULL AND runtime_target = ?)
       `).run(t, session.id, peerId, session.id, session.pane || null, session.pane || null);
-      addEvent(db, status === 'exited' ? 'tmux.session.exited' : 'tmux.session.detached', peerId, null, {
+      addEvent(db, status === 'exited' ? 'tmux.session.exited' : 'tmux.session.detached', peerId, null, auditPayload({
+        actor: peerId,
+        target: peerId,
+        source: session.auditSource || 'runtime',
         runtime_session_id: session.id,
         pane: session.pane
-      });
+      }));
     } finally {
       db.close();
     }
@@ -2552,7 +2971,12 @@ async function cmdWeb(ctx, args, startMeta = {}) {
 
   function addRebindCleanupFailedEvent(db, actor, payload) {
     if (!db) return;
-    addEvent(db, 'tmux.session.rebind_cleanup_failed', actor, null, payload);
+    addEvent(db, 'tmux.session.rebind_cleanup_failed', actor, null, auditPayload({
+      actor,
+      target: payload.old_peer || payload.target_peer || null,
+      admin: true,
+      ...payload
+    }));
   }
 
   function oldTmuxRebindTarget(projectCtx, oldTarget, newTarget) {
@@ -2732,7 +3156,10 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         });
     }
     if (db) {
-      addEvent(db, 'tmux.session.rebind_cleanup_pending', actor, null, {
+      addEvent(db, 'tmux.session.rebind_cleanup_pending', actor, null, auditPayload({
+        actor,
+        target: oldPeer,
+        admin: true,
         old_peer: oldPeer,
         old_runtime_target: oldTarget,
         new_runtime_target: newTarget,
@@ -2741,7 +3168,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         expected_tmux_session: expectedSession,
         allowed_tmux_session: allowedSession,
         hcc_root: hccRoot || null
-      });
+      }));
     }
     return {
       oldPeer,
@@ -2829,13 +3256,16 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       throw err;
     }
     if (db) {
-      addEvent(db, 'tmux.session.rebound', actor, null, {
+      addEvent(db, 'tmux.session.rebound', actor, null, auditPayload({
+        actor,
+        target: oldPeer,
+        admin: true,
         old_peer: oldPeer,
         old_runtime_target: oldTarget,
         new_runtime_target: newTarget,
         old_tmux_session: oldSessionName,
         new_tmux_session: newSessionName || null
-      });
+      }));
     }
     return true;
   }
@@ -2851,6 +3281,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const pctx = input.projectCtx || ctx;
     const id = input.id;
     if (!id) throw new CliError('BAD_REQUEST', 'id required');
+    const actorPeer = requestActorPeer(input, id);
+    const auditSource = requestSource(input, input.autoAttach ? 'runtime' : 'web');
     const info = tmuxPaneInfo(input.pane || null);
     if (info.dead) throw new CliError('TMUX_PANE_DEAD', `tmux pane is not running: ${info.pane}`);
 
@@ -2882,6 +3314,9 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const session = {
       id,
       peerId: id,
+      actorPeer,
+      auditSource,
+      actionToken: newSessionActionToken(),
       root: pctx.root,
       ctx: pctx,
       kind,
@@ -2968,7 +3403,16 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       });
       session.peerId = canonical.peer;
       session.binding = { ...canonical.binding };
-      addEvent(db, 'tmux.session.attached', id, null, { pane: info.pane, command, cwd, pid: info.pid });
+      addEvent(db, 'tmux.session.attached', actorPeer, null, auditPayload({
+        actor: actorPeer,
+        target: session.peerId || id,
+        source: auditSource,
+        admin: actorPeer !== (session.peerId || id),
+        pane: info.pane,
+        command,
+        cwd,
+        pid: info.pid
+      }));
     } catch (err) {
       stopTmuxStream(session);
       if (session.exitPoller) { clearInterval(session.exitPoller); session.exitPoller = null; }
@@ -2983,12 +3427,17 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         try {
           killOldTmuxForRebind(pctx, rebindOldPlan, session.peerId || id, eventDb);
           if (rebindOldPeer && rebindOldPeer !== id) {
-            addEvent(eventDb, 'provider.session.rebound', session.peerId || id, null, {
+            const actor = actorPeer || session.peerId || id;
+            addEvent(eventDb, 'provider.session.rebound', actor, null, auditPayload({
+              actor,
+              target: rebindOldPeer,
+              source: auditSource,
+              admin: true,
               from_peer: rebindOldPeer,
               to_peer: id,
               old_runtime_target: rebindOldTarget,
               new_runtime_target: info.pane
-            });
+            }));
           }
         } finally {
           eventDb.close();
@@ -3053,6 +3502,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const pctx = input.projectCtx || ctx;
     const kind = input.kind || 'shell';
     const id = input.id || nextProjectSessionId(pctx, kind);
+    const actorPeer = requestActorPeer(input, id);
+    const auditSource = requestSource(input, 'web');
     const role = input.role || 'peer';
     const command = input.command || defaultSessionCommand(kind);
     const cwd = path.resolve(input.cwd || pctx.root);
@@ -3124,11 +3575,15 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       hasSession = false;
       const db = connect(pctx);
       try {
-        addEvent(db, 'tmux.session.restarted', id, null, {
+        addEvent(db, 'tmux.session.restarted', actorPeer, null, auditPayload({
+          actor: actorPeer,
+          target: id,
+          source: auditSource,
+          admin: true,
           reason,
           old_runtime_target: oldTarget,
           old_tmux_session: parkedName
-        });
+        }));
       } finally {
         db.close();
       }
@@ -3213,7 +3668,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       try {
         const eventDb = connect(pctx);
         try {
-          killOldTmuxForRebind(pctx, oldInfo.plan, session.peerId || id, eventDb);
+          killOldTmuxForRebind(pctx, oldInfo.plan, actorPeer, eventDb);
         } finally {
           eventDb.close();
         }
@@ -3257,6 +3712,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
           pane: row.runtime_target,
           projectCtx,
           force: true,
+          auditActorPeer: 'web-runtime',
+          auditSource: 'runtime',
           binding: {
             provider: row.provider,
             provider_session_id: row.provider_session_id,
@@ -3277,6 +3734,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const pctx = input.projectCtx || ctx;
     const kind = input.kind || 'shell';
     const id = input.id || nextProjectSessionId(pctx, kind);
+    const actorPeer = requestActorPeer(input, id);
+    const auditSource = requestSource(input, 'web');
     const key = sessionKey(pctx, id);
     if (sessions.has(key) && sessions.get(key).status === 'running') {
       return sessions.get(key);
@@ -3303,6 +3762,9 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const session = {
       id,
       peerId: id,
+      actorPeer,
+      auditSource,
+      actionToken: newSessionActionToken(),
       root: pctx.root,
       ctx: pctx,
       kind,
@@ -3343,7 +3805,15 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       }, Boolean(input.force));
       session.peerId = canonical.peer;
       session.binding = { ...canonical.binding };
-      addEvent(db, 'web.session.started', id, null, { command, cwd, pid: child.pid });
+      addEvent(db, 'web.session.started', actorPeer, null, auditPayload({
+        actor: actorPeer,
+        target: session.peerId || id,
+        source: auditSource,
+        admin: actorPeer !== (session.peerId || id),
+        command,
+        cwd,
+        pid: child.pid
+      }));
     } finally {
       db.close();
     }
@@ -3358,7 +3828,12 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       const db = connect(pctx);
       try {
         db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now(), id);
-        addEvent(db, 'web.session.exited', id, null, event);
+        addEvent(db, 'web.session.exited', session.actorPeer || id, null, auditPayload({
+          actor: session.actorPeer || id,
+          target: session.peerId || id,
+          source: session.auditSource || 'web',
+          ...event
+        }));
       } finally {
         db.close();
       }
@@ -3508,7 +3983,10 @@ async function cmdWeb(ctx, args, startMeta = {}) {
               resource: url.searchParams.getAll('resource')
             }
           : await readJsonRequest(req);
-        sendJson(res, 200, webPeerAction(reqCtx, peer, action, input));
+        const actionInput = readOnly
+          ? input
+          : { ...input, actorPeer: resolveWebActionSession(reqCtx, peer, input, req) };
+        sendJson(res, 200, webPeerAction(reqCtx, peer, action, actionInput));
         return;
       }
       // Detected sessions: peers registered via hooks/watcher but without PTY
@@ -3610,13 +4088,13 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       }
       if (req.method === 'POST' && url.pathname === '/api/sessions') {
         const input = await readJsonRequest(req);
-        const session = startSession({ ...input, projectCtx: reqCtx });
+        const session = startSession({ ...input, projectCtx: reqCtx, auditActorPeer: 'web', auditSource: 'web' });
         sendJson(res, 200, { session: serializeSession(session) });
         return;
       }
       if (req.method === 'POST' && url.pathname === '/api/sessions/attach') {
         const input = await readJsonRequest(req);
-        const session = attachTmuxSession({ ...input, projectCtx: reqCtx });
+        const session = attachTmuxSession({ ...input, projectCtx: reqCtx, auditActorPeer: 'web', auditSource: 'web' });
         sendJson(res, 200, { session: serializeSession(session) });
         return;
       }
@@ -3644,7 +4122,16 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         writeSessionInput(session, data);
         const db = connect(session.ctx || reqCtx);
         try {
-          addEvent(db, 'web.session.input', id, null, { bytes: data.length, enter: input.enter !== false });
+          addEvent(db, 'web.session.input', 'web', null, auditPayload({
+            actor: 'web',
+            target: session.peerId || id,
+            source: 'web',
+            admin: true,
+            peer: session.peerId || id,
+            runtime_session_id: session.id,
+            bytes: data.length,
+            enter: input.enter !== false
+          }));
         } finally {
           db.close();
         }
@@ -3654,6 +4141,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       const stopMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/stop$/);
       if (req.method === 'POST' && stopMatch) {
         const id = decodeURIComponent(stopMatch[1]);
+        let stopInput = {};
+        try { stopInput = await readJsonRequest(req); } catch {}
         const lookupDb = connect(reqCtx);
         let session;
         try {
@@ -3672,13 +4161,11 @@ async function cmdWeb(ctx, args, startMeta = {}) {
             if (session.wrapperPid) { try { process.kill(session.wrapperPid, 'SIGTERM'); } catch {} }
             if (session.pid && session.pid !== session.wrapperPid) { try { process.kill(session.pid, 'SIGTERM'); } catch {} }
           } else if (session.type === 'tmux') {
-            let input = {};
-            try { input = await readJsonRequest(req); } catch {}
             let killPlan = null;
             const stopDb = connect(reqCtx);
             try {
               const peerId = resolveSessionPeerId(stopDb, session) || session.peerId || session.id;
-              if (input.kill_tmux) {
+              if (stopInput.kill_tmux) {
                 killPlan = safeTmuxKillPlan(reqCtx, stopDb, peerId, session.pane || null);
               }
             } finally {
@@ -3690,6 +4177,21 @@ async function cmdWeb(ctx, args, startMeta = {}) {
             session.pty.kill();
           }
         }
+        const eventDb = connect(reqCtx);
+        try {
+          const peerId = resolveSessionPeerId(eventDb, session) || session.peerId || id;
+          addEvent(eventDb, 'web.session.stop_requested', 'web', null, auditPayload({
+            actor: 'web',
+            target: peerId,
+            source: 'web',
+            admin: true,
+            peer: peerId,
+            runtime_session_id: session.id,
+            kill_tmux: Boolean(stopInput.kill_tmux)
+          }));
+        } finally {
+          eventDb.close();
+        }
         sendJson(res, 200, { session: serializeSession(session) });
         return;
       }
@@ -3699,7 +4201,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         const peerId = decodeURIComponent(detectedMsgMatch[1]);
         const input = await readJsonRequest(req);
         const body = String(input.body || '');
-        const sender = String(input.from || 'web');
+        const sender = 'web';
         const taskId = input.task ? Number(input.task) : null;
         if (!body) { sendJson(res, 400, { ok: false, error: { code: 'BAD_REQUEST', message: 'body required' } }); return; }
         const db = connect(reqCtx);
@@ -3726,12 +4228,16 @@ async function cmdWeb(ctx, args, startMeta = {}) {
           }
           db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now_, peerId);
           db.prepare('UPDATE peer_bindings SET runtime_target = NULL, updated_at = ? WHERE peer = ?').run(now_, peerId);
-          addEvent(db, 'peer.stopped', 'web', null, {
+          addEvent(db, 'peer.stopped', 'web', null, auditPayload({
+            actor: 'web',
+            target: peerId,
+            source: 'web',
+            admin: true,
             peer: peerId,
             kill_tmux: Boolean(killPlan),
             tmux_session: killPlan?.session || null,
             runtime_target: killPlan?.runtime_target || null
-          });
+          }));
         } finally {
           db.close();
         }
@@ -3745,7 +4251,13 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         try {
           const now_ = now();
           db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('running', now_, peerId);
-          addEvent(db, 'peer.restarted', 'web', null, { peer: peerId });
+          addEvent(db, 'peer.restarted', 'web', null, auditPayload({
+            actor: 'web',
+            target: peerId,
+            source: 'web',
+            admin: true,
+            peer: peerId
+          }));
         } finally {
           db.close();
         }
@@ -3755,7 +4267,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: 'Route not found' } });
     } catch (err) {
       const detail = err instanceof CliError || process.env.HCC_DEBUG ? err.message : 'internal server error';
-      sendJson(res, 500, { ok: false, error: { code: err.code || 'SERVER_ERROR', message: detail } });
+      sendJson(res, webErrorStatus(err), { ok: false, error: { code: err.code || 'SERVER_ERROR', message: detail } });
     }
   });
 
@@ -3810,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 {}
@@ -3827,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);
@@ -3850,7 +4387,9 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   registerProject(ctx);
   const db = connect(ctx);
   try {
-    addEvent(db, startMeta.eventType || 'web.started', 'human', null, {
+    addEvent(db, startMeta.eventType || 'web.started', 'human', null, auditPayload({
+      actor: 'human',
+      source: 'cli',
       root: ctx.root,
       db: ctx.dbPath,
       host,
@@ -3858,7 +4397,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       requested_port: port,
       guidance: startMeta.guidance || prepared.guidance || null,
       runtime: runtimeFile
-    });
+    }));
   } finally {
     db.close();
   }
@@ -3876,8 +4415,9 @@ async function cmdRun(ctx, args) {
   const cmdArgs = sep >= 0 ? args.slice(sep + 1) : [];
   const opts = parseOpts(optArgs, { booleans: ['force', 'web-managed'] });
   validateOpts('run', opts, ['peer', 'kind', 'role', 'cwd', 'force']);
-  const id = required(opts, 'peer', 'HCC_PEER');
   const kind = opts.kind || 'other';
+  const identity = resolveCurrentPeer(ctx, opts, 'peer', kind);
+  const id = identity.id;
   const role = opts.role || 'peer';
   const cwd = path.resolve(opts.cwd || ctx.cwd);
   const command = cmdArgs.length ? cmdArgs[0] : defaultSessionCommand(kind);
@@ -3895,7 +4435,12 @@ async function cmdRun(ctx, args) {
       capabilities: 'run-wrapper'
     });
     upsertCanonicalPeerBinding(db, binding, Boolean(opts.force));
-    addEvent(db, 'run.session.started', id, null, { command: [command, ...commandArgs].join(' '), cwd });
+    addEvent(db, 'run.session.started', id, null, auditPayload({
+      actor: id,
+      target: id,
+      command: [command, ...commandArgs].join(' '),
+      cwd
+    }));
   } finally {
     db.close();
   }
@@ -3915,7 +4460,11 @@ async function cmdRun(ctx, args) {
   const db2 = connect(ctx);
   try {
     db2.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now(), id);
-    addEvent(db2, 'run.session.exited', id, null, exitCode);
+    addEvent(db2, 'run.session.exited', id, null, auditPayload({
+      actor: id,
+      target: id,
+      ...exitCode
+    }));
   } finally {
     db2.close();
   }
@@ -3958,7 +4507,13 @@ async function cmdRunWebManaged(ctx, { id, kind, role, cwd, command, commandArgs
       capabilities: 'run-pty'
     });
     upsertCanonicalPeerBinding(db, binding, force);
-    addEvent(db, 'run.session.started', id, null, { command: [command, ...commandArgs].join(' '), cwd, webManaged: true });
+    addEvent(db, 'run.session.started', id, null, auditPayload({
+      actor: id,
+      target: id,
+      command: [command, ...commandArgs].join(' '),
+      cwd,
+      webManaged: true
+    }));
   } finally {
     db.close();
   }
@@ -4075,7 +4630,11 @@ async function cmdRunWebManaged(ctx, { id, kind, role, cwd, command, commandArgs
   const db2 = connect(ctx);
   try {
     db2.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now(), id);
-    addEvent(db2, 'run.session.exited', id, null, exitCode);
+    addEvent(db2, 'run.session.exited', id, null, auditPayload({
+      actor: id,
+      target: id,
+      ...exitCode
+    }));
   } finally {
     db2.close();
   }
@@ -4200,13 +4759,22 @@ async function cmdHook(ctx, args) {
         SET last_seen_at = ?, status = COALESCE(?, status)
         WHERE id = ?
       `).run(now(), status, peerId);
-      addEvent(db, 'provider.session.merged', peerId, null, {
+      addEvent(db, 'provider.session.merged', peerId, null, auditPayload({
+        actor: peerId,
+        target: peerId,
+        source: 'hook',
         from_peer: previousPeer,
         provider: kind,
         session_id: sessionId || resumeId || null
-      });
+      }));
     }
-    addEvent(db, `hook.${hookKey}`, peerId, null, { session_id: sessionId, cwd: hookCwd });
+    addEvent(db, `hook.${hookKey}`, peerId, null, auditPayload({
+      actor: peerId,
+      target: peerId,
+      source: 'hook',
+      session_id: sessionId,
+      cwd: hookCwd
+    }));
     try {
       reconcileRunningPeerBindings(db, hookCtx, {
         inspectProcess: inspectProviderProcess,
@@ -4246,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();
@@ -4275,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];
@@ -4287,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;
     }
@@ -4299,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}`);
@@ -4350,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()) {
@@ -4368,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.');
@@ -4461,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;
@@ -4485,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 ────────────────────────────────────────────────────────────────
@@ -4498,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();
@@ -4830,13 +5427,16 @@ async function cmdTmux(ctx, args) {
             `).run(t, candidate.peer, candidate.runtime_target);
             db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('detached', t, candidate.peer);
           }
-          addEvent(db, 'tmux.session.gc', actor, null, {
+          addEvent(db, 'tmux.session.gc', actor, null, auditPayload({
+            actor,
+            target: candidate.peer,
+            admin: true,
             peer: candidate.peer,
             tmux_session: candidate.session,
             runtime_target: candidate.runtime_target,
             reason: candidate.reason,
             older_than_days: plan.older_than_days
-          });
+          }));
           removed.push(candidate);
         });
       }