@logicseek/hello-cc 0.1.9 → 1.0.1

package/lib/cli/commands/up.mjs

@@ -0,0 +1,135 @@
+// Up command extracted from bin/hcc.mjs.
+// hcc up bootstraps the local coordination bus: guidance, provider hooks,
+// optional shims, and provider-session discovery.
+
+import { parseOpts, validateOpts } from '../../cli-args.mjs';
+import { printResult } from '../../format.mjs';
+import { commandPath } from '../../cli-runtime.mjs';
+import { detectBranch } from '../../project-context.mjs';
+import { bindingFromDetected } from '../../core/peers/bindings.mjs';
+
+export function createUpCommand(deps) {
+  const {
+    connect, helpUp, PRODUCT_NAME,
+    loadSetup, loadDiscover,
+    writeGuidance, sameResolvedPath,
+    upsertPeer, upsertCanonicalPeerBinding
+  } = deps;
+
+async function cmdUp(ctx, args) {
+  if (args[0] === '--help' || args[0] === '-h') return helpUp();
+  const opts = parseOpts(args, { booleans: ['no-guidance', 'no-discover'] });
+  validateOpts('up', opts, ['no-guidance', 'no-discover']);
+  const result = await prepareLocalBus(ctx, opts);
+  return printResult(ctx, result, (r) => {
+    const lines = [
+      `${PRODUCT_NAME} local coordination ready`,
+      `project: ${r.root}`,
+      `database: ${r.db}`
+    ];
+    if (r.guidance) lines.push(`guidance: ${r.guidance}`);
+    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');
+  });
+}
+
+async function prepareLocalBus(ctx, opts = {}) {
+  let guidance = null;
+  const db = connect(ctx);
+  try {
+    guidance = opts['no-guidance'] ? null : writeGuidance(ctx);
+  } finally {
+    db.close();
+  }
+
+  const hooks = { claudeInstalled: false, codexInstalled: false };
+  const shims = { installed: [], skipped: [], pathUpdated: false, rcFile: null };
+  const warnings = [];
+  try {
+    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 (err) {
+      warnings.push(`Codex hooks installation failed: ${err.message}`);
+    }
+    if (opts.installShims) {
+      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 (err) {
+    warnings.push(`local integration setup failed: ${err.message}`);
+  }
+
+  const detected = [];
+  if (!opts['no-discover']) {
+    try {
+      const { scanClaudeSessions, scanCodexSessions, scanProcesses } = await loadDiscover();
+      const found = [
+        ...scanClaudeSessions(),
+        ...scanCodexSessions(),
+        ...scanProcesses(),
+      ].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);
+      }
+      if (byId.size > 0) {
+        const db2 = connect(ctx);
+        try {
+          for (const s of byId.values()) {
+            detected.push(s);
+            upsertPeer(db2, {
+              id: s.peerId, kind: s.kind, role: 'peer',
+              worktree: s.cwd,
+              branch: detectBranch(s.cwd),
+              pid: s.pid,
+              status: 'running',
+              capabilities: 'detected'
+            });
+            upsertCanonicalPeerBinding(db2, bindingFromDetected(s, s.transport || 'detected'), true);
+          }
+        } finally {
+          db2.close();
+        }
+      }
+    } catch {}
+  }
+
+  return {
+    root: ctx.root,
+    db: ctx.dbPath,
+    guidance,
+    hooks,
+    shims,
+    detected,
+    warnings
+  };
+}
+
+  return { cmdUp, prepareLocalBus };
+}

package/lib/cli-args.mjs

@@ -83,7 +83,21 @@ export function required(opts, key, envName = null) {
 
 export function intOpt(opts, key, fallback = null) {
   if (opts[key] === undefined || opts[key] === null || opts[key] === '') return fallback;
-  const value = Number.parseInt(String(opts[key]), 10);
-  if (!Number.isFinite(value)) throw new CliError('BAD_ARGS', `--${key} must be an integer`);
+  const text = String(opts[key]);
+  if (!/^-?[0-9]+$/.test(text)) {
+    throw new CliError('BAD_ARGS', `--${key} must be a safe integer`);
+  }
+  const value = Number(text);
+  if (!Number.isSafeInteger(value)) {
+    throw new CliError('BAD_ARGS', `--${key} must be a safe integer`);
+  }
+  return value;
+}
+
+export function positiveSafeIntOpt(opts, key, fallback = null) {
+  const value = intOpt(opts, key, fallback);
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new CliError('BAD_ARGS', `--${key} must be a positive safe integer`);
+  }
   return value;
 }

package/lib/coordination-state.mjs

@@ -8,6 +8,9 @@ import {
 } from './core/peers/liveness.mjs';
 import { lockLabel } from './core/coordination/locks.mjs';
 import { timelineFromRows } from './core/coordination/timeline.mjs';
+import { readTx } from './db/schema.mjs';
+import { clockGraceSuppressed, readClockGraceUntil } from './shared/clock-grace.mjs';
+import { classifyPeerActivity } from './core/peers/evidence.mjs';
 
 const DEFAULT_ACTIVE_PEER_TTL = 600;
 const DEFAULT_LOCK_TTL = 900;
@@ -28,57 +31,97 @@ export function createCoordinationState(deps = {}) {
   const connect = requireFn(deps.connect, 'connect');
   const defaultLockTtl = Number(deps.defaultLockTtl ?? DEFAULT_LOCK_TTL);
   const now = typeof deps.now === 'function' ? deps.now : defaultNow;
+  const observePeerEvidence = requireFn(deps.observePeerEvidence, 'observePeerEvidence');
   const queryInbox = requireFn(deps.queryInbox, 'queryInbox');
   const queryOpenTasks = requireFn(deps.queryOpenTasks, 'queryOpenTasks');
   const queryTimelineMessages = requireFn(deps.queryTimelineMessages, 'queryTimelineMessages');
-  const touchCurrentPeer = typeof deps.touchCurrentPeer === 'function'
-    ? deps.touchCurrentPeer
-    : () => {};
+  function annotatePeerEvidence(ctx, peers, bindings, graceActive = false) {
+    const bindingByPeer = new Map();
+    for (const binding of bindings || []) {
+      if (!bindingByPeer.has(binding.peer)) bindingByPeer.set(binding.peer, binding);
+    }
+    return (peers || []).map((peer) => {
+      const evidence = observePeerEvidence(ctx, peer, bindingByPeer.get(peer.id) || null);
+      const { pid_start_token: _startToken, pid_command_hash: _commandHash, ...publicPeer } = peer;
+      const observed = {
+        ...publicPeer,
+        evidence_state: evidence.state,
+        evidence_reason: evidence.reason
+      };
+      return {
+        ...observed,
+        ...classifyPeerActivity(observed, { activePeerTtl, graceActive })
+      };
+    });
+  }
+
+  function visibleLocks(allLocks, peers, t, graceActive) {
+    if (graceActive) return allLocks;
+    const peerById = new Map((peers || []).map((peer) => [peer.id, peer]));
+    return (allLocks || []).filter((lock) =>
+      Number(lock.expires_at) > t || peerById.get(lock.owner)?.evidence_state === 'live'
+    );
+  }
 
   function collectStateSnapshot(db, ctx, peer = null, opts = {}) {
     const t = now();
-    const peers = db.prepare(`
-      SELECT id, kind, role, status, worktree, branch, pid, capabilities,
-             created_at, last_seen_at, (? - last_seen_at) AS age_sec
-      FROM peers
-      ORDER BY last_seen_at DESC, id ASC
-      LIMIT 200
-    `).all(t);
-    const taskRows = queryOpenTasks(db, 200);
-    const locks = db.prepare(`
-      SELECT resource, base_resource, scope, owner, task_id, reason, expires_at, created_at
-      FROM locks
-      WHERE expires_at > ?
-      ORDER BY resource ASC
-      LIMIT 200
-    `).all(t);
-    const tasks = annotateTasksWithLiveness(taskRows, peers, locks, t, activePeerTtl);
-    const messages = peer
-      ? queryInbox(db, peer, false, 50)
-      : db.prepare(`
-          SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
-          FROM messages
-          ORDER BY id DESC
-          LIMIT 50
-        `).all().reverse();
-    const timelineMessages = queryTimelineMessages(db, peer, 80);
-    const handoffs = db.prepare(`
-      SELECT id, task_id, from_peer, to_peer, summary, changed_files, tests, risks, created_at
-      FROM handoffs
-      ORDER BY id DESC
-      LIMIT 50
-    `).all().reverse();
-    const events = db.prepare(`
-      SELECT id, type, actor, task_id, payload, created_at
-      FROM events
-      ORDER BY id DESC
-      LIMIT 80
-    `).all().reverse();
+    // Read every table inside one deferred transaction for a consistent
+    // snapshot (conc-06): without this, a heartbeat between reads can make
+    // counts drift and produce a transiently wrong takeover_ready.
+    const { peerRows, bindings, taskRows, allLocks, messages, timelineMessages, handoffs, events, graceUntil } = readTx(db, () => {
+      const peers = db.prepare(`
+        SELECT id, kind, role, status, worktree, branch, pid,
+               pid_start_token, pid_command_hash, capabilities,
+               created_at, last_seen_at, (? - last_seen_at) AS age_sec
+        FROM peers
+        ORDER BY last_seen_at DESC, id ASC
+      `).all(t);
+      const bindings = db.prepare(`
+        SELECT peer, transport, runtime_target, updated_at, created_at
+        FROM peer_bindings
+        ORDER BY updated_at DESC, created_at DESC
+      `).all();
+      const taskRows = queryOpenTasks(db, 200);
+      const graceUntil = readClockGraceUntil(db);
+      const allLocks = db.prepare(`
+        SELECT resource, base_resource, scope, owner, task_id, reason, expires_at, created_at, ttl_sec
+        FROM locks
+        ORDER BY resource ASC
+      `).all();
+      const messages = peer
+        ? queryInbox(db, peer, false, 50)
+        : db.prepare(`
+            SELECT id, sender, recipient, task_id, kind, body, reply_to, thread_id, created_at
+            FROM messages
+            ORDER BY id DESC
+            LIMIT 50
+          `).all().reverse();
+      const timelineMessages = queryTimelineMessages(db, peer, 80);
+      const handoffs = db.prepare(`
+        SELECT id, task_id, from_peer, to_peer, summary, changed_files, tests, risks, created_at
+        FROM handoffs
+        ORDER BY id DESC
+        LIMIT 50
+      `).all().reverse();
+      const events = db.prepare(`
+        SELECT id, type, actor, task_id, payload, created_at
+        FROM events
+        ORDER BY id DESC
+        LIMIT 80
+      `).all().reverse();
+      return { peerRows: peers, bindings, taskRows, allLocks, messages, timelineMessages, handoffs, events, graceUntil };
+    });
+    const graceActive = clockGraceSuppressed(t, graceUntil);
+    const peers = annotatePeerEvidence(ctx, peerRows, bindings, graceActive);
+    const locks = visibleLocks(allLocks, peers, t, graceActive);
+    const tasks = annotateTasksWithLiveness(taskRows, peers, locks, t, activePeerTtl, graceUntil);
     const snapshot = {
       root: ctx.root,
       db: ctx.dbPath,
       now: t,
       active_peer_ttl: activePeerTtl,
+      clock_grace_active: graceActive,
+      clock_grace_until: graceUntil || null,
       peers,
       tasks,
       locks,
@@ -114,8 +157,7 @@ export function createCoordinationState(deps = {}) {
     if (peers.length > 0) {
       parts.push('[hello-cc known peers]');
       parts.push(...peers.map((peer) => {
-        const age = Math.max(0, snapshot.now - Number(peer.last_seen_at || 0));
-        const active = age <= activePeerTtl ? 'active' : 'stale';
+        const active = peer.active ? 'active' : 'stale';
         return `- ${peer.id} ${peer.kind || 'other'} ${peer.status || 'idle'} ${active}`;
       }));
     } else {
@@ -169,24 +211,43 @@ export function createCoordinationState(deps = {}) {
     }
   }
 
-  function statusSummary(ctx, peer = null, identity = null) {
+  function statusSummary(ctx, peer = null, _identity = null) {
     const db = connect(ctx);
     try {
-      if (identity) touchCurrentPeer(db, ctx, identity, null, 'shell');
       const t = now();
-      const activePeers = db.prepare('SELECT COUNT(*) AS n FROM peers WHERE last_seen_at >= ?').get(t - activePeerTtl).n;
-      const stalePeers = db.prepare('SELECT COUNT(*) AS n FROM peers WHERE last_seen_at < ?').get(t - activePeerTtl).n;
-      const taskRows = db.prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status ORDER BY status').all();
-      const locks = db.prepare('SELECT COUNT(*) AS n FROM locks WHERE expires_at > ?').get(t).n;
-      const unread = peer ? queryInbox(db, peer, false, 1000).length : null;
-      const recent = db.prepare('SELECT * FROM events ORDER BY id DESC LIMIT 8').all().reverse();
+      const { peerRows, bindings, taskRows, allLocks, unread, recent, graceUntil } = readTx(db, () => ({
+        peerRows: db.prepare(`
+          SELECT id, kind, role, status, worktree, branch, pid,
+                 pid_start_token, pid_command_hash, capabilities,
+                 created_at, last_seen_at, (? - last_seen_at) AS age_sec
+          FROM peers
+          ORDER BY last_seen_at DESC, id ASC
+        `).all(t),
+        bindings: db.prepare(`
+          SELECT peer, transport, runtime_target, updated_at, created_at
+          FROM peer_bindings
+          ORDER BY updated_at DESC, created_at DESC
+        `).all(),
+        taskRows: db.prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status ORDER BY status').all(),
+        allLocks: db.prepare('SELECT * FROM locks').all(),
+        unread: peer ? queryInbox(db, peer, false, 1000).length : null,
+        recent: db.prepare('SELECT * FROM events ORDER BY id DESC LIMIT 8').all().reverse(),
+        graceUntil: readClockGraceUntil(db)
+      }));
+      const graceActive = clockGraceSuppressed(t, graceUntil);
+      const peers = annotatePeerEvidence(ctx, peerRows, bindings, graceActive);
+      const activePeers = peers.filter((row) => row.active).length;
+      const stalePeers = peers.length - activePeers;
+      const locks = visibleLocks(allLocks, peers, t, graceActive);
       return {
         root: ctx.root,
         db: ctx.dbPath,
         active_peers: activePeers,
         stale_peers: stalePeers,
+        clock_grace_active: graceActive,
+        clock_grace_until: graceUntil || null,
         tasks: taskRows,
-        active_locks: locks,
+        active_locks: locks.length,
         unread,
         recent_events: recent
       };

package/lib/core/coordination/automation.mjs

@@ -13,15 +13,12 @@ import {
   uniqueList
 } from './timeline.mjs';
 import { summarizeTask } from '../peers/liveness.mjs';
+import { classifyPeerActivity } from '../peers/evidence.mjs';
 
 const DEFAULT_CLI_NAME = 'hcc';
 const DEFAULT_ACTIVE_PEER_TTL = 600;
 const DEFAULT_LOCK_TTL = 900;
 
-function nowSec() {
-  return Math.floor(Date.now() / 1000);
-}
-
 export function actionCommand(argv, cliName = DEFAULT_CLI_NAME) {
   if (!argv?.length) return '';
   return [cliName, ...argv].map(shellQuoteArg).join(' ');
@@ -67,7 +64,7 @@ export function deriveAutomation(snapshot, peer = null, opts = {}, config = {})
     makeAction(kind, argv, reason, mutates, extra, { cliName });
 
   const peerId = peer || '';
-  const t = Number(snapshot.now || nowSec());
+  const graceActive = Boolean(snapshot.clock_grace_active);
   const peerRow = peerId ? snapshot.peers.find((row) => row.id === peerId) : null;
   const openTasks = (snapshot.tasks || []).filter((task) => !['done', 'abandoned'].includes(task.status));
   const assignedTasks = peerId ? openTasks.filter((task) => !task.owner && task.assignee === peerId) : [];
@@ -82,8 +79,8 @@ export function deriveAutomation(snapshot, peer = null, opts = {}, config = {})
   const ownLocks = peerId ? (snapshot.locks || []).filter((lock) => lock.owner === peerId) : [];
   const requestedLocks = resources.map((resource) => {
     const requested = scopedLockResource(resource, scope);
-    const lock = (snapshot.locks || []).find((row) => Number(row.expires_at || 0) > t && locksConflict(row, requested));
-    const exact = (snapshot.locks || []).find((row) => Number(row.expires_at || 0) > t && lockBaseResource(row) === requested.base_resource && lockScope(row) === requested.scope);
+    const lock = (snapshot.locks || []).find((row) => locksConflict(row, requested));
+    const exact = (snapshot.locks || []).find((row) => lockBaseResource(row) === requested.base_resource && lockScope(row) === requested.scope);
     return { ...requested, lock, exact };
   });
   const conflict = requestedLocks.find((entry) => entry.lock && entry.lock.owner !== peerId);
@@ -100,7 +97,7 @@ export function deriveAutomation(snapshot, peer = null, opts = {}, config = {})
     peer: peerId ? {
       id: peerId,
       known: Boolean(peerRow),
-      active: Boolean(peerRow && Number(peerRow.age_sec || 0) <= activePeerTtl),
+      active: Boolean(peerRow && classifyPeerActivity(peerRow, { activePeerTtl, graceActive }).active),
       age_sec: peerRow ? Number(peerRow.age_sec || 0) : null
     } : null,
     current_task: summarizeTask(ownedTask),