@logicseek/hello-cc 0.1.3 → 0.1.5

package/bin/hcc.mjs

@@ -4,37 +4,84 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import process from 'node:process';
-import os from 'node:os';
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { URL, fileURLToPath } from 'node:url';
 import { DatabaseSync } from 'node:sqlite';
+import { CliError } from '../lib/errors.mjs';
+import {
+  DB_SCHEMA_VERSION,
+  execWithBusyRetry,
+  initSchema,
+  tx
+} from '../lib/db-schema.mjs';
+import {
+  intOpt,
+  parseOpts,
+  required,
+  splitGlobalArgs,
+  validateOpts,
+  wantsHelp
+} from '../lib/cli-args.mjs';
+import {
+  compactText,
+  formatJson,
+  printResult,
+  shellExports,
+  shellQuoteArg,
+  table
+} from '../lib/format.mjs';
+import { readPackageMeta } from '../lib/package-meta.mjs';
+import {
+  removeGuidanceBlocks as removeGuidanceBlocksForRoot,
+  writeGuidance as writeGuidanceForRoot
+} from '../lib/guidance.mjs';
+import {
+  contextForProject,
+  globalRuntimePath,
+  projectDbPath,
+  projectRegistryPath,
+  runtimePath,
+  webLogPath
+} from '../lib/runtime-paths.mjs';
+import {
+  expectedWebHost,
+  localRuntimeUrl,
+  makeWebToken,
+  publicRuntimeUrl,
+  rememberRuntimeToken,
+  requestUrl,
+  runtimeApiUrl,
+  runtimeBaseUrl,
+  validateWebTokenOpts,
+  webRuntimeMatchesRequest
+} from '../lib/web-runtime.mjs';
+import {
+  authOk,
+  readJsonRequest,
+  sendFile,
+  sendHttp,
+  sendJson
+} from '../lib/web-http.mjs';
+import { webIndexHtml } from '../lib/web-ui-template.mjs';
 
 // Lazy-load lib modules (they may import node-pty which needs to be optional)
 const _libDir = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'lib');
 async function loadDiscover() { return import(path.join(_libDir, 'discover.mjs')); }
 async function loadSetup()    { return import(path.join(_libDir, 'setup.mjs')); }
 
-const VERSION = '0.1.2';
+const PACKAGE_META = readPackageMeta(path.resolve(fileURLToPath(import.meta.url), '..', '..'));
+const VERSION = PACKAGE_META.version;
 const PRODUCT_NAME = 'hello-cc';
 const CLI_NAME = 'hcc';
-const NPM_PACKAGE_NAME = '@logicseek/hello-cc';
+const NPM_PACKAGE_NAME = PACKAGE_META.name;
 const DEFAULT_LOCK_TTL = 900;
 const ACTIVE_PEER_TTL = 600;
-const DB_SCHEMA_VERSION = 4;
 // Directory under .hello-cc/ for optional external PTY buffer files.
 const BUFS_DIR_NAME = 'bufs';
 const WEB_CHILD_ENV = 'HCC_WEB_CHILD';
 
-class CliError extends Error {
-  constructor(code, message, extra = {}) {
-    super(message);
-    this.code = code;
-    this.extra = extra;
-  }
-}
-
 function now() {
   return Math.floor(Date.now() / 1000);
 }
@@ -72,86 +119,6 @@ function detectBranch(cwd) {
   return runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd) || '';
 }
 
-function splitGlobalArgs(argv) {
-  const global = { json: false, root: null, db: null };
-  const rest = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--json') {
-      global.json = true;
-    } else if (arg === '--root') {
-      global.root = argv[++i];
-    } else if (arg.startsWith('--root=')) {
-      global.root = arg.slice('--root='.length);
-    } else if (arg === '--db') {
-      global.db = argv[++i];
-    } else if (arg.startsWith('--db=')) {
-      global.db = arg.slice('--db='.length);
-    } else {
-      rest.push(arg);
-    }
-  }
-  return { global, rest };
-}
-
-function parseOpts(args, spec = {}) {
-  const booleans = new Set(spec.booleans || []);
-  const arrays = new Set(spec.arrays || []);
-  const opts = { _: [] };
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (!arg.startsWith('--') || arg === '--') {
-      opts._.push(arg);
-      continue;
-    }
-    let key;
-    let value;
-    const eq = arg.indexOf('=');
-    if (eq >= 0) {
-      key = arg.slice(2, eq);
-      value = arg.slice(eq + 1);
-    } else {
-      key = arg.slice(2);
-      if (booleans.has(key)) {
-        value = true;
-      } else {
-        value = args[++i];
-      }
-    }
-    if (!key) throw new CliError('BAD_ARGS', `Invalid option: ${arg}`);
-    if (value === undefined) throw new CliError('BAD_ARGS', `Missing value for --${key}`);
-    if (arrays.has(key)) {
-      if (!opts[key]) opts[key] = [];
-      opts[key].push(value);
-    } else {
-      opts[key] = value;
-    }
-  }
-  return opts;
-}
-
-function wantsHelp(args) {
-  const stop = args.indexOf('--');
-  const scan = stop >= 0 ? args.slice(0, stop) : args;
-  const index = scan.findIndex((arg) => arg === '--help' || arg === '-h');
-  if (index < 0) return false;
-  return index <= 1 || !String(scan[index - 1] || '').startsWith('--');
-}
-
-function validateOpts(command, opts, allowed = []) {
-  const allowedSet = new Set(['_', ...allowed]);
-  for (const key of Object.keys(opts)) {
-    if (!allowedSet.has(key)) throw new CliError('BAD_ARGS', `${command}: unknown option --${key}`);
-  }
-  if (opts._?.length) throw new CliError('BAD_ARGS', `${command}: unexpected argument ${opts._[0]}`);
-}
-
-function required(opts, key, envName = null) {
-  const value = opts[key] || (envName ? process.env[envName] : null);
-  if (!value) throw new CliError('BAD_ARGS', `Missing --${key}${envName ? ` or $${envName}` : ''}`);
-  return value;
-}
-
 function sanitizePeerPart(value, fallback = 'peer') {
   const text = String(value || '').toLowerCase()
     .replace(/[^a-z0-9._-]/g, '-')
@@ -360,55 +327,13 @@ function autoPeerDefaults(ctx, kindHint = 'shell', status = 'working') {
   };
 }
 
-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`);
-  return value;
-}
-
 function createContext(global) {
   const cwd = process.cwd();
   const root = detectRoot(cwd, global.root);
-  const dbPath = path.resolve(global.db || process.env.HCC_DB || path.join(root, '.hello-cc', 'mesh.db'));
+  const dbPath = path.resolve(global.db || process.env.HCC_DB || projectDbPath(root));
   return { cwd, root, dbPath, json: global.json, explicitRoot: Boolean(global.root || process.env.HCC_ROOT) };
 }
 
-function runtimePath(ctx) {
-  return path.join(ctx.root, '.hello-cc', 'runtime.json');
-}
-
-function webLogPath(ctx) {
-  return path.join(ctx.root, '.hello-cc', 'web.log');
-}
-
-function globalStateDir() {
-  return path.join(os.homedir(), '.hello-cc');
-}
-
-function globalRuntimePath() {
-  return path.join(globalStateDir(), 'runtime.json');
-}
-
-function globalWebTokenPath() {
-  return path.join(globalStateDir(), 'web-token');
-}
-
-function projectRegistryPath() {
-  return path.join(globalStateDir(), 'projects.json');
-}
-
-function contextForProject(root, dbPath = null, base = {}) {
-  const resolvedRoot = path.resolve(root);
-  return {
-    cwd: base.cwd || resolvedRoot,
-    root: resolvedRoot,
-    dbPath: path.resolve(dbPath || path.join(resolvedRoot, '.hello-cc', 'mesh.db')),
-    json: Boolean(base.json),
-    explicitRoot: true
-  };
-}
-
 function projectRecord(ctx) {
   return {
     root: ctx.root,
@@ -428,7 +353,7 @@ function readProjectRegistry() {
       .filter((p) => p && typeof p.root === 'string')
       .map((p) => ({
         root: path.resolve(p.root),
-        db: path.resolve(p.db || path.join(p.root, '.hello-cc', 'mesh.db')),
+        db: path.resolve(p.db || projectDbPath(p.root)),
         name: String(p.name || path.basename(p.root) || p.root),
         last_seen_at: Number.parseInt(p.last_seen_at || '0', 10) || 0
       }));
@@ -445,7 +370,7 @@ function writeProjectRegistry(projects) {
     if (!project?.root) continue;
     unique.set(path.resolve(project.root), {
       root: path.resolve(project.root),
-      db: path.resolve(project.db || path.join(project.root, '.hello-cc', 'mesh.db')),
+      db: path.resolve(project.db || projectDbPath(project.root)),
       name: String(project.name || path.basename(project.root) || project.root),
       last_seen_at: Number.parseInt(project.last_seen_at || '0', 10) || 0
     });
@@ -485,15 +410,6 @@ function writeGlobalRuntime(runtime) {
   return file;
 }
 
-function runtimeConnectHost(host) {
-  if (host === '0.0.0.0' || host === '::') return '127.0.0.1';
-  return host;
-}
-
-function runtimeBaseUrl(host, port) {
-  return `http://${runtimeConnectHost(host)}:${port}`;
-}
-
 function writeRuntime(ctx, runtime) {
   const file = runtimePath(ctx);
   fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -536,7 +452,7 @@ function readRuntimeFile(ctx) {
 
 async function probeRuntime(runtime) {
   if (!runtime?.base_url) return false;
-  const url = new URL('/api/runtime', runtime.base_url);
+  const url = runtimeApiUrl(runtime, '/api/runtime');
   const headers = {};
   if (runtime.token) headers.Authorization = `Bearer ${runtime.token}`;
   try {
@@ -589,99 +505,10 @@ function clearRuntime(ctx, pid = process.pid) {
   }
 }
 
-function shellQuoteArg(value) {
-  const text = String(value);
-  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(text)) return text;
-  return `'${text.replace(/'/g, `'\\''`)}'`;
-}
-
 function shellCommand(args) {
   return args.map(shellQuoteArg).join(' ');
 }
 
-function runtimeUrlQuery(runtime, projectRoot = null) {
-  const parts = [];
-  if (runtime.token) parts.push(`token=${encodeURIComponent(runtime.token)}`);
-  if (projectRoot) parts.push(`project=${encodeURIComponent(projectRoot)}`);
-  return parts.length ? `?${parts.join('&')}` : '';
-}
-
-function readStoredWebToken() {
-  const file = globalWebTokenPath();
-  if (!fs.existsSync(file)) return '';
-  try {
-    return fs.readFileSync(file, 'utf8').trim();
-  } catch {
-    return '';
-  }
-}
-
-function writeStoredWebToken(token) {
-  if (!token) return '';
-  const file = globalWebTokenPath();
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${token}\n`, { mode: 0o600 });
-  fs.chmodSync(file, 0o600);
-  return file;
-}
-
-function makeWebToken(opts) {
-  validateWebTokenOpts(opts);
-  if (opts['no-token']) return '';
-  const explicitToken = opts.token || process.env.HCC_WEB_TOKEN || '';
-  if (explicitToken) {
-    writeStoredWebToken(explicitToken);
-    return explicitToken;
-  }
-  const stored = readStoredWebToken();
-  if (stored) return stored;
-  const generated = randomBytes(24).toString('base64url');
-  writeStoredWebToken(generated);
-  return generated;
-}
-
-function validateWebTokenOpts(opts) {
-  if (opts['no-token'] && (opts.token || process.env.HCC_WEB_TOKEN)) {
-    throw new CliError('BAD_ARGS', '--no-token cannot be combined with --token or HCC_WEB_TOKEN');
-  }
-}
-
-function expectedWebHost(opts) {
-  return opts.host || (opts.local ? '127.0.0.1' : '0.0.0.0');
-}
-
-function webRuntimeMatchesRequest(runtime, opts) {
-  if (!runtime) return false;
-  if (opts['no-token'] && (opts.token || process.env.HCC_WEB_TOKEN)) return false;
-  const expectedHost = expectedWebHost(opts);
-  if (runtime.host !== expectedHost) return false;
-  const expectedPort = intOpt(opts, 'port', 8787);
-  if (opts.port !== undefined && runtime.port !== expectedPort) return false;
-  const explicitToken = opts.token || process.env.HCC_WEB_TOKEN || '';
-  if (opts['no-token']) return !runtime.token;
-  if (explicitToken) return runtime.token === explicitToken;
-  return Boolean(runtime.token);
-}
-
-function rememberRuntimeToken(runtime, opts) {
-  if (!runtime?.token || opts['no-token']) return;
-  const explicitToken = opts.token || process.env.HCC_WEB_TOKEN || '';
-  if (explicitToken && runtime.token !== explicitToken) return;
-  writeStoredWebToken(runtime.token);
-}
-
-function publicRuntimeUrl(runtime, projectRoot = null) {
-  const host = runtime.host === '0.0.0.0' || runtime.host === '::'
-    ? '<machine-ip>'
-    : runtime.host || runtimeConnectHost(runtime.host || '127.0.0.1');
-  return `http://${host}:${runtime.port}/${runtimeUrlQuery(runtime, projectRoot)}`;
-}
-
-function localRuntimeUrl(runtime, projectRoot = null) {
-  const host = runtimeConnectHost(runtime.host || '127.0.0.1');
-  return `http://${host}:${runtime.port}/${runtimeUrlQuery(runtime, projectRoot)}`;
-}
-
 function tailFile(file, maxBytes = 12000) {
   try {
     const stat = fs.statSync(file);
@@ -1419,7 +1246,7 @@ function parseCodexCommandArgs(args) {
 
 async function runtimeRequest(ctx, method, route, body = null, runtime = null) {
   const rt = runtime || readRuntime(ctx);
-  const url = new URL(route, rt.base_url);
+  const url = runtimeApiUrl(rt, route);
   const headers = { 'Content-Type': 'application/json' };
   headers['X-HCC-Root'] = ctx.root;
   headers['X-HCC-DB'] = ctx.dbPath;
@@ -1453,38 +1280,6 @@ async function runtimeRequest(ctx, method, route, body = null, runtime = null) {
   return json || {};
 }
 
-const sleepBuffer = new SharedArrayBuffer(4);
-const sleepView = new Int32Array(sleepBuffer);
-
-function sleepSync(ms) {
-  Atomics.wait(sleepView, 0, 0, ms);
-}
-
-function isSqliteBusy(err) {
-  const text = `${err?.code || ''} ${err?.message || ''} ${err?.errstr || ''}`;
-  return err?.errcode === 5 ||
-    err?.errcode === 6 ||
-    err?.errcode === 261 ||
-    /SQLITE_BUSY|SQLITE_LOCKED|database is locked|database is busy/i.test(text);
-}
-
-function execWithBusyRetry(db, sql, { attempts = 30, delayMs = 100, ignoreBusy = false } = {}) {
-  for (let attempt = 0; attempt < attempts; attempt += 1) {
-    try {
-      db.exec(sql);
-      return true;
-    } catch (err) {
-      if (!isSqliteBusy(err)) throw err;
-      if (attempt === attempts - 1) {
-        if (ignoreBusy) return false;
-        throw err;
-      }
-      sleepSync(delayMs);
-    }
-  }
-  return false;
-}
-
 let projectMigrationFanoutDepth = 0;
 const migratedRegisteredProjectDbs = new Set();
 
@@ -1494,7 +1289,7 @@ function connect(ctx) {
   db.exec('PRAGMA busy_timeout = 5000;');
   execWithBusyRetry(db, 'PRAGMA journal_mode = WAL;', { ignoreBusy: true });
   db.exec('PRAGMA foreign_keys = ON;');
-  initSchema(db);
+  initSchema(db, { beforePostMigrationIndexes: dedupePeerBindings });
   migrateRegisteredProjectDbs(ctx);
   return db;
 }
@@ -1519,7 +1314,7 @@ function migrateRegisteredProjectDbs(ctx) {
         db.exec('PRAGMA busy_timeout = 5000;');
         execWithBusyRetry(db, 'PRAGMA journal_mode = WAL;', { ignoreBusy: true });
         db.exec('PRAGMA foreign_keys = ON;');
-        initSchema(db);
+        initSchema(db, { beforePostMigrationIndexes: dedupePeerBindings });
         migratedRegisteredProjectDbs.add(cacheKey);
       } catch (err) {
         throw new CliError('REGISTERED_DB_MIGRATION_FAILED', `Failed to migrate registered project database ${dbPath}: ${err?.message || err}`, {
@@ -1535,252 +1330,6 @@ function migrateRegisteredProjectDbs(ctx) {
   }
 }
 
-function initSchema(db) {
-  const existingVersion = readSchemaVersion(db);
-  if (existingVersion > DB_SCHEMA_VERSION) {
-    throw new CliError('DB_SCHEMA_TOO_NEW', `Database schema version ${existingVersion} is newer than this hcc (${DB_SCHEMA_VERSION})`, {
-      db_schema_version: existingVersion,
-      supported_schema_version: DB_SCHEMA_VERSION
-    });
-  }
-  createBaseSchema(db);
-  runSchemaMigrations(db);
-  dedupePeerBindings(db);
-  execWithBusyRetry(db, `
-    CREATE INDEX IF NOT EXISTS idx_peer_bindings_provider_session ON peer_bindings(provider, provider_session_id);
-    CREATE UNIQUE INDEX IF NOT EXISTS idx_peer_bindings_provider_session_id_unique
-      ON peer_bindings(provider, provider_session_id)
-      WHERE provider_session_id IS NOT NULL;
-    CREATE UNIQUE INDEX IF NOT EXISTS idx_peer_bindings_provider_session_name_unique
-      ON peer_bindings(provider, provider_session_name)
-      WHERE provider_session_name IS NOT NULL;
-    CREATE UNIQUE INDEX IF NOT EXISTS idx_peer_bindings_runtime_target_unique
-      ON peer_bindings(runtime_target)
-      WHERE runtime_target IS NOT NULL;
-  `);
-}
-
-function createBaseSchema(db) {
-  execWithBusyRetry(db, `
-    CREATE TABLE IF NOT EXISTS meta (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS schema_migrations (
-      version INTEGER PRIMARY KEY,
-      name TEXT NOT NULL,
-      applied_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS peers (
-      id TEXT PRIMARY KEY,
-      kind TEXT NOT NULL,
-      role TEXT,
-      worktree TEXT,
-      branch TEXT,
-      pid INTEGER,
-      status TEXT NOT NULL DEFAULT 'idle',
-      capabilities TEXT,
-      created_at INTEGER NOT NULL,
-      last_seen_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS peer_bindings (
-      peer TEXT PRIMARY KEY,
-      provider TEXT NOT NULL,
-      provider_session_id TEXT,
-      provider_session_name TEXT,
-      resume_mode TEXT NOT NULL DEFAULT 'new',
-      resume_arg TEXT,
-      command TEXT,
-      transport TEXT NOT NULL,
-      runtime_session_id TEXT,
-      runtime_target TEXT,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL,
-      FOREIGN KEY (peer) REFERENCES peers(id) ON DELETE CASCADE
-    );
-
-    CREATE TABLE IF NOT EXISTS tasks (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      title TEXT NOT NULL,
-      body TEXT,
-      status TEXT NOT NULL DEFAULT 'pending',
-      assignee TEXT,
-      owner TEXT,
-      parent_id INTEGER,
-      team_role TEXT,
-      priority INTEGER NOT NULL DEFAULT 100,
-      created_by TEXT,
-      claimed_at INTEGER,
-      completed_at INTEGER,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS messages (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      sender TEXT NOT NULL,
-      recipient TEXT,
-      task_id INTEGER,
-      kind TEXT NOT NULL DEFAULT 'note',
-      body TEXT NOT NULL,
-      reply_to INTEGER,
-      thread_id INTEGER,
-      created_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS message_reads (
-      message_id INTEGER NOT NULL,
-      peer TEXT NOT NULL,
-      read_at INTEGER NOT NULL,
-      PRIMARY KEY (message_id, peer),
-      FOREIGN KEY (message_id) REFERENCES messages(id) ON DELETE CASCADE
-    );
-
-    CREATE TABLE IF NOT EXISTS locks (
-      resource TEXT PRIMARY KEY,
-      owner TEXT NOT NULL,
-      task_id INTEGER,
-      reason TEXT,
-      expires_at INTEGER NOT NULL,
-      created_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS handoffs (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      task_id INTEGER,
-      from_peer TEXT NOT NULL,
-      to_peer TEXT,
-      summary TEXT NOT NULL,
-      changed_files TEXT,
-      tests TEXT,
-      risks TEXT,
-      created_at INTEGER NOT NULL
-    );
-
-    CREATE TABLE IF NOT EXISTS events (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      type TEXT NOT NULL,
-      actor TEXT,
-      task_id INTEGER,
-      payload TEXT,
-      created_at INTEGER NOT NULL
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_tasks_status_priority ON tasks(status, priority, id);
-    CREATE INDEX IF NOT EXISTS idx_tasks_owner ON tasks(owner);
-    CREATE INDEX IF NOT EXISTS idx_messages_recipient_id ON messages(recipient, id);
-    CREATE INDEX IF NOT EXISTS idx_events_id ON events(id);
-    CREATE INDEX IF NOT EXISTS idx_locks_expires ON locks(expires_at);
-  `);
-}
-
-function tableColumns(db, tableName) {
-  return new Set(db.prepare(`PRAGMA table_info(${tableName})`).all().map((col) => col.name));
-}
-
-function tableExists(db, tableName) {
-  return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1").get(tableName));
-}
-
-function readSchemaVersion(db) {
-  const metaExists = tableExists(db, 'meta');
-  const metaVersion = metaExists ? Number(db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get()?.value || 0) : 0;
-  const pragmaVersion = Number(db.prepare('PRAGMA user_version').get()?.user_version || 0);
-  const migrationVersion = tableExists(db, 'schema_migrations')
-    ? Number(db.prepare('SELECT MAX(version) AS version FROM schema_migrations').get()?.version || 0)
-    : 0;
-  return Math.max(metaVersion, pragmaVersion, migrationVersion);
-}
-
-function writeSchemaVersion(db, version) {
-  db.prepare(`
-    INSERT INTO meta(key, value) VALUES ('schema_version', ?)
-    ON CONFLICT(key) DO UPDATE SET value = excluded.value
-  `).run(String(version));
-  db.exec(`PRAGMA user_version = ${Number(version)}`);
-}
-
-function recordSchemaMigration(db, version, name) {
-  db.prepare(`
-    INSERT INTO schema_migrations(version, name, applied_at)
-    VALUES (?, ?, ?)
-    ON CONFLICT(version) DO NOTHING
-  `).run(version, name, now());
-}
-
-function addColumnIfMissing(db, tableName, columnName, ddl) {
-  const columns = tableColumns(db, tableName);
-  if (!columns.has(columnName)) db.exec(`ALTER TABLE ${tableName} ADD COLUMN ${ddl}`);
-}
-
-function runSchemaMigrations(db) {
-  const migrations = [
-    {
-      version: 1,
-      name: 'baseline',
-      up() {
-        // createBaseSchema already created the baseline tables.
-      }
-    },
-    {
-      version: 2,
-      name: 'peer binding runtime targets',
-      up(database) {
-        addColumnIfMissing(database, 'peer_bindings', 'runtime_target', 'runtime_target TEXT');
-      }
-    },
-    {
-      version: 3,
-      name: 'threaded messages',
-      up(database) {
-        addColumnIfMissing(database, 'messages', 'reply_to', 'reply_to INTEGER');
-        addColumnIfMissing(database, 'messages', 'thread_id', 'thread_id INTEGER');
-        database.exec(`
-          UPDATE messages SET thread_id = id WHERE thread_id IS NULL;
-          CREATE INDEX IF NOT EXISTS idx_messages_thread_id ON messages(thread_id, id);
-        `);
-      }
-    },
-    {
-      version: 4,
-      name: 'team task hierarchy',
-      up(database) {
-        addColumnIfMissing(database, 'tasks', 'parent_id', 'parent_id INTEGER');
-        addColumnIfMissing(database, 'tasks', 'team_role', 'team_role TEXT');
-        database.exec('CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_id, priority, id);');
-      }
-    }
-  ];
-  let version = readSchemaVersion(db);
-  if (version > DB_SCHEMA_VERSION) {
-    throw new CliError('DB_SCHEMA_TOO_NEW', `Database schema version ${version} is newer than this hcc (${DB_SCHEMA_VERSION})`, {
-      db_schema_version: version,
-      supported_schema_version: DB_SCHEMA_VERSION
-    });
-  }
-  const applied = new Set(db.prepare('SELECT version FROM schema_migrations').all().map((row) => Number(row.version)));
-  tx(db, () => {
-    for (const migration of migrations) {
-      if (version >= migration.version && applied.has(migration.version)) continue;
-      migration.up(db);
-      recordSchemaMigration(db, migration.version, migration.name);
-      applied.add(migration.version);
-      version = migration.version;
-      writeSchemaVersion(db, version);
-    }
-    if (version === 0) {
-      version = DB_SCHEMA_VERSION;
-    }
-    for (const migration of migrations) {
-      if (migration.version <= version) recordSchemaMigration(db, migration.version, migration.name);
-    }
-    writeSchemaVersion(db, version);
-  });
-}
-
 function peerBindingRuntimeRank(row) {
   if (row?.runtime_target && row.transport === 'tmux') return 50;
   if (row?.runtime_target) return 40;
@@ -1873,22 +1422,6 @@ function dedupePeerBindings(db) {
   }
 }
 
-function tx(db, fn) {
-  execWithBusyRetry(db, 'BEGIN IMMEDIATE;');
-  try {
-    const result = fn();
-    db.exec('COMMIT;');
-    return result;
-  } catch (err) {
-    try {
-      db.exec('ROLLBACK;');
-    } catch {
-      // Ignore rollback failures; the original error is more useful.
-    }
-    throw err;
-  }
-}
-
 function addEvent(db, type, actor, taskId, payload) {
   db.prepare(`
     INSERT INTO events(type, actor, task_id, payload, created_at)
@@ -2239,11 +1772,6 @@ function parseEventPayload(row) {
   }
 }
 
-function compactText(value, limit = 160) {
-  const text = String(value || '').replace(/\s+/g, ' ').trim();
-  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
-}
-
 function uniqueList(values) {
   return [...new Set(values.filter(Boolean).map(String))];
 }
@@ -2287,6 +1815,7 @@ const TIMELINE_EVENT_ALLOW = new Set([
   'task.blocked',
   'task.done',
   'task.abandoned',
+  'task.takeover',
   'team.started',
   'lock.acquired',
   'lock.released',
@@ -2388,7 +1917,7 @@ function timelineFromRows({ messages = [], handoffs = [], tasks = [], locks = []
       peers: uniqueList([lock.owner]),
       task_id: lock.task_id || null,
       kind: 'active',
-      title: `lock ${lock.resource}`,
+      title: `lock ${lockLabel(lock)}`,
       text: compactText(lock.reason || `owner=${lock.owner}`),
       direction: 'project'
     };
@@ -2436,6 +1965,51 @@ function makeAction(kind, argv, reason, mutates = true, extra = {}) {
   };
 }
 
+const WHOLE_LOCK_SCOPE = '*';
+
+function normalizeLockScope(scope) {
+  const text = String(scope || '').trim();
+  return text || WHOLE_LOCK_SCOPE;
+}
+
+function scopedLockResource(resource, scope = WHOLE_LOCK_SCOPE) {
+  const baseResource = String(resource || '').trim();
+  const normalizedScope = normalizeLockScope(scope);
+  if (!baseResource) throw new CliError('BAD_ARGS', 'Missing --resource');
+  return {
+    resource: normalizedScope === WHOLE_LOCK_SCOPE
+      ? baseResource
+      : `scoped:${Buffer.from(JSON.stringify([baseResource, normalizedScope]), 'utf8').toString('base64url')}`,
+    base_resource: baseResource,
+    scope: normalizedScope
+  };
+}
+
+function lockBaseResource(lock) {
+  return lock?.base_resource || lock?.resource || '';
+}
+
+function lockScope(lock) {
+  return normalizeLockScope(lock?.scope);
+}
+
+function lockLabel(lock) {
+  const base = lockBaseResource(lock);
+  const scope = lockScope(lock);
+  return scope === WHOLE_LOCK_SCOPE ? base : `${base} [${scope}]`;
+}
+
+function lockArgv(resource, scope) {
+  const argv = ['--resource', resource];
+  if (normalizeLockScope(scope) !== WHOLE_LOCK_SCOPE) argv.push('--scope', normalizeLockScope(scope));
+  return argv;
+}
+
+function locksConflict(a, b) {
+  return lockBaseResource(a) === lockBaseResource(b) &&
+    (lockScope(a) === WHOLE_LOCK_SCOPE || lockScope(b) === WHOLE_LOCK_SCOPE || lockScope(a) === lockScope(b));
+}
+
 function looksLikeMultiTask(task) {
   if (!task) return false;
   const text = `${task.title || ''}\n${task.body || ''}`;
@@ -2457,6 +2031,63 @@ function selectCurrentTask(tasks, peerId) {
   return ownedTasks.find((task) => ['running', 'claimed', 'review', 'blocked'].includes(task.status)) || ownedTasks[0] || null;
 }
 
+function taskRelatedLocks(task, locks) {
+  const taskId = Number(task?.id || 0);
+  const owner = task?.owner || '';
+  return (locks || []).filter((lock) => {
+    if (taskId && Number(lock.task_id || 0) === taskId) return true;
+    return Boolean(owner && lock.owner === owner);
+  });
+}
+
+function taskOwnerLiveness(task, peers, locks, t = now()) {
+  const owner = task?.owner || null;
+  const relatedLocks = taskRelatedLocks(task, locks);
+  if (!owner) {
+    return {
+      owner_known: false,
+      owner_active: null,
+      owner_stale: false,
+      owner_age_sec: null,
+      related_lock_count: relatedLocks.length,
+      takeover_ready: false
+    };
+  }
+  const ownerRow = (peers || []).find((row) => row.id === owner) || null;
+  const ownerAge = ownerRow
+    ? Number(ownerRow.age_sec ?? (t - Number(ownerRow.last_seen_at || 0)))
+    : null;
+  const ownerActive = Boolean(ownerRow && Number.isFinite(ownerAge) && ownerAge <= ACTIVE_PEER_TTL);
+  const ownerStale = !ownerActive;
+  const takeoverStatus = ['claimed', 'running', 'review', 'blocked'].includes(task.status);
+  return {
+    owner_known: Boolean(ownerRow),
+    owner_active: ownerActive,
+    owner_stale: ownerStale,
+    owner_age_sec: Number.isFinite(ownerAge) ? ownerAge : null,
+    related_lock_count: relatedLocks.length,
+    takeover_ready: Boolean(takeoverStatus && ownerStale && relatedLocks.length === 0)
+  };
+}
+
+function annotateTasksWithLiveness(tasks, peers, locks, t = now()) {
+  return (tasks || []).map((task) => ({
+    ...task,
+    ...taskOwnerLiveness(task, peers, locks, t)
+  }));
+}
+
+function taskOwnerStateText(task) {
+  if (!task?.owner) return '';
+  if (task.owner_stale) {
+    if (task.takeover_ready) return 'stale/no-lock';
+    const locks = Number(task.related_lock_count || 0);
+    return locks ? `stale/locks=${locks}` : 'stale';
+  }
+  if (task.owner_active) return 'active';
+  return '';
+}
+
 function summarizeTask(task) {
   if (!task) return null;
   return {
@@ -2467,8 +2098,151 @@ function summarizeTask(task) {
     assignee: task.assignee || null,
     parent_id: task.parent_id || null,
     team_role: task.team_role || null,
-    priority: task.priority
+    priority: task.priority,
+    owner_active: task.owner_active ?? null,
+    owner_stale: Boolean(task.owner_stale),
+    owner_age_sec: task.owner_age_sec ?? null,
+    related_lock_count: Number(task.related_lock_count || 0),
+    takeover_ready: Boolean(task.takeover_ready)
+  };
+}
+
+function parseTaskIds(opts) {
+  const values = [];
+  const addValue = (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value) addValue(item);
+      return;
+    }
+    if (value === undefined || value === null || value === '') return;
+    for (const part of String(value).split(',')) {
+      const text = part.trim();
+      if (text) values.push(text);
+    }
   };
+  addValue(opts.id);
+  addValue(opts.ids);
+  addValue(opts._ || []);
+  const seen = new Set();
+  const ids = [];
+  for (const value of values) {
+    if (!/^\d+$/.test(value)) throw new CliError('BAD_ARGS', `task id must be an integer: ${value}`);
+    const id = Number.parseInt(value, 10);
+    if (!seen.has(id)) {
+      seen.add(id);
+      ids.push(id);
+    }
+  }
+  if (!ids.length) throw new CliError('BAD_ARGS', 'Missing --id');
+  return ids;
+}
+
+function positiveIntOpt(opts, key, fallback, { max = 50 } = {}) {
+  const value = intOpt(opts, key, fallback);
+  if (value < 1) throw new CliError('BAD_ARGS', `--${key} must be >= 1`);
+  if (value > max) throw new CliError('BAD_ARGS', `--${key} must be <= ${max}`);
+  return value;
+}
+
+function taskRowsText(tasks, verb = 'claimed') {
+  const rows = Array.isArray(tasks) ? tasks : [tasks].filter(Boolean);
+  if (!rows.length) return 'no pending task';
+  return rows.map((task) => `${verb} task #${task.id}: ${task.title}`).join('\n');
+}
+
+function claimTaskRowsForPeer(db, peer, ids, { force = false, source = null } = {}) {
+  return tx(db, () => {
+    const tasks = [];
+    for (const id of ids) {
+      const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+      if (!row) throw new CliError('NOT_FOUND', `Task #${id} does not exist`);
+      if (row.owner && row.owner !== peer && !force) {
+        throw new CliError('TASK_OWNED', `Task #${id} is owned by ${row.owner}`, { owner: row.owner });
+      }
+      if (row.assignee && row.assignee !== peer && !force) {
+        throw new CliError('TASK_ASSIGNED', `Task #${id} is assigned to ${row.assignee}`, { assignee: row.assignee });
+      }
+      if (!['pending', 'blocked', 'claimed', 'running'].includes(row.status) && !force) {
+        throw new CliError('BAD_STATE', `Task #${id} is ${row.status}`);
+      }
+      const t = now();
+      db.prepare(`
+        UPDATE tasks
+        SET owner = ?, status = 'claimed', claimed_at = COALESCE(claimed_at, ?), updated_at = ?
+        WHERE id = ?
+      `).run(peer, t, t, id);
+      addEvent(db, 'task.claimed', peer, id, {
+        previous_owner: row.owner,
+        force,
+        ...(source ? { source } : {})
+      });
+      tasks.push(db.prepare('SELECT * FROM tasks WHERE id = ?').get(id));
+    }
+    return tasks;
+  });
+}
+
+function takeoverPolicyDetails(db, row, peer, { policy = 'any', staleAfter = ACTIVE_PEER_TTL } = {}) {
+  const normalized = String(policy || 'any').toLowerCase();
+  const allowed = new Set(['any', 'blocked', 'stale', 'blocked-or-stale']);
+  if (!allowed.has(normalized)) {
+    throw new CliError('BAD_ARGS', `Unsupported takeover policy: ${policy}`);
+  }
+  const previousOwner = row.owner || null;
+  const blocked = row.status === 'blocked';
+  const ownerRow = previousOwner ? db.prepare('SELECT id, last_seen_at FROM peers WHERE id = ?').get(previousOwner) : null;
+  const ownerAge = ownerRow ? now() - Number(ownerRow.last_seen_at || 0) : null;
+  const ownerStale = Boolean(previousOwner && previousOwner !== peer && (!ownerRow || ownerAge > staleAfter));
+  const alreadyOwner = previousOwner === peer;
+  const ok = alreadyOwner ||
+    normalized === 'any' ||
+    (normalized === 'blocked' && blocked) ||
+    (normalized === 'stale' && ownerStale) ||
+    (normalized === 'blocked-or-stale' && (blocked || ownerStale));
+  return { policy: normalized, blocked, owner_stale: ownerStale, owner_age_sec: ownerAge, stale_after_sec: staleAfter, ok };
+}
+
+function takeOverTaskForPeer(db, peer, id, { reason, policy = 'any', staleAfter = ACTIVE_PEER_TTL, source = null } = {}) {
+  return 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 (['done', 'abandoned'].includes(row.status)) {
+      throw new CliError('BAD_STATE', `Task #${id} is ${row.status}`);
+    }
+    const policyDetails = takeoverPolicyDetails(db, row, peer, { policy, staleAfter });
+    if (!policyDetails.ok) {
+      throw new CliError('TAKEOVER_POLICY', `Task #${id} does not match takeover policy ${policyDetails.policy}`, {
+        task_id: id,
+        status: row.status,
+        owner: row.owner || null,
+        policy: policyDetails.policy,
+        owner_stale: policyDetails.owner_stale,
+        owner_age_sec: policyDetails.owner_age_sec,
+        stale_after_sec: policyDetails.stale_after_sec
+      });
+    }
+    const previousOwner = row.owner || null;
+    const previousAssignee = row.assignee || null;
+    const t = now();
+    db.prepare(`
+      UPDATE tasks
+      SET owner = ?, status = 'claimed', claimed_at = COALESCE(claimed_at, ?), updated_at = ?
+      WHERE id = ?
+    `).run(peer, t, t, id);
+    addEvent(db, 'task.takeover', peer, id, {
+      previous_owner: previousOwner,
+      previous_assignee: previousAssignee,
+      reason,
+      policy: policyDetails.policy,
+      owner_stale: policyDetails.owner_stale,
+      stale_after_sec: staleAfter,
+      ...(source ? { source } : {})
+    });
+    if (previousOwner && previousOwner !== peer) {
+      sendMessage(db, peer, previousOwner, id, 'task.takeover', `Task #${id} taken over by ${peer}: ${reason}`);
+    }
+    return db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+  });
 }
 
 function deriveAutomation(snapshot, peer = null, opts = {}) {
@@ -2479,11 +2253,18 @@ function deriveAutomation(snapshot, peer = null, opts = {}) {
   const assignedTasks = peerId ? openTasks.filter((task) => !task.owner && task.assignee === peerId) : [];
   const availableTasks = openTasks.filter((task) => !task.owner && !task.assignee);
   const ownedTask = selectCurrentTask(openTasks, peerId);
+  const takeoverReadyTasks = peerId
+    ? openTasks.filter((task) => task.owner && task.owner !== peerId && task.takeover_ready)
+    : [];
+  const intent = String(opts.intent || 'work').toLowerCase();
+  const scope = normalizeLockScope(opts.scope || opts.lock_scope);
   const resources = uniqueList(Array.isArray(opts.resources) ? opts.resources : (opts.resource ? [opts.resource] : []));
   const ownLocks = peerId ? (snapshot.locks || []).filter((lock) => lock.owner === peerId) : [];
   const requestedLocks = resources.map((resource) => {
-    const lock = (snapshot.locks || []).find((row) => row.resource === resource && Number(row.expires_at || 0) > t);
-    return { resource, lock };
+    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);
+    return { ...requested, lock, exact };
   });
   const conflict = requestedLocks.find((entry) => entry.lock && entry.lock.owner !== peerId);
   const missingLock = requestedLocks.find((entry) => !entry.lock);
@@ -2501,14 +2282,14 @@ function deriveAutomation(snapshot, peer = null, opts = {}) {
       known: Boolean(peerRow),
       active: Boolean(peerRow && Number(peerRow.age_sec || 0) <= ACTIVE_PEER_TTL),
       age_sec: peerRow ? Number(peerRow.age_sec || 0) : null
-      } : null,
-      current_task: summarizeTask(ownedTask),
-      phase: 'idle',
-      next_action: makeAction('none', [], 'no immediate coordination action', false),
-      actions: [],
-      finish_actions: [],
-      warnings
-    };
+    } : null,
+    current_task: summarizeTask(ownedTask),
+    phase: 'idle',
+    next_action: makeAction('none', [], 'no immediate coordination action', false),
+    actions: [],
+    finish_actions: [],
+    warnings
+  };
 
   const orderedUnread = unread
     .filter((message) => message.sender !== peerId)
@@ -2529,15 +2310,41 @@ function deriveAutomation(snapshot, peer = null, opts = {}) {
   if (!ownedTask && assignedTasks.length) {
     const task = assignedTasks[0];
     taskActions.push(makeAction('task.claim', ['task', 'claim', '--peer', peerId, '--id', String(task.id)], `assigned task #${task.id}`, true, { task_id: task.id }));
+  } else if (!ownedTask && takeoverReadyTasks.length) {
+    const task = takeoverReadyTasks[0];
+    taskActions.push(makeAction(
+      'task.takeover',
+      ['task', 'takeover', '--peer', peerId, '--id', String(task.id), '--reason', 'owner stale and no active related locks', '--policy', 'stale'],
+      `task #${task.id} owner ${task.owner} is stale and has no active related locks`,
+      true,
+      { task_id: task.id, owner: task.owner, owner_age_sec: task.owner_age_sec ?? null }
+    ));
   } else if (!ownedTask && availableTasks.length) {
     taskActions.push(makeAction('task.next', ['task', 'next', '--peer', peerId], 'available pending task exists', true));
   }
 
   if (ownedTask) {
-    if (conflict) {
-      lockActions.push(makeAction('msg.send', ['msg', 'send', '--from', peerId, '--to', conflict.lock.owner, '--task', String(ownedTask.id), '--body', `Please coordinate ${conflict.resource}; it is locked by ${conflict.lock.owner}.`], `${conflict.resource} is locked by ${conflict.lock.owner}`, true, { task_id: ownedTask.id, resource: conflict.resource, lock_owner: conflict.lock.owner }));
+    const readOnlyIntent = ['read', 'review', 'inspect'].includes(intent);
+    if (readOnlyIntent && resources.length) {
+      warnings.push(`intent=${intent} is read-only; do not acquire file locks for snapshot inspection`);
+    } else if (conflict) {
+      const requestedLabel = lockLabel(conflict);
+      const heldLabel = lockLabel(conflict.lock);
+      lockActions.push(makeAction(
+        'msg.send',
+        ['msg', 'send', '--from', peerId, '--to', conflict.lock.owner, '--task', String(ownedTask.id), '--body', `Please coordinate ${requestedLabel}; ${heldLabel} is locked by ${conflict.lock.owner}. If our edits are separate, split to scoped locks before final tests/commit.`],
+        `${requestedLabel} conflicts with ${heldLabel} held by ${conflict.lock.owner}`,
+        true,
+        { task_id: ownedTask.id, resource: conflict.base_resource, scope: conflict.scope, lock_owner: conflict.lock.owner, lock_resource: conflict.lock.resource, lock_scope: lockScope(conflict.lock) }
+      ));
     } else if (missingLock) {
-      lockActions.push(makeAction('lock.acquire', ['lock', 'acquire', '--peer', peerId, '--task', String(ownedTask.id), '--resource', missingLock.resource, '--ttl', String(DEFAULT_LOCK_TTL), '--reason', '<work>'], `task #${ownedTask.id} needs lock for ${missingLock.resource}`, true, { task_id: ownedTask.id, resource: missingLock.resource }));
+      lockActions.push(makeAction(
+        'lock.acquire',
+        ['lock', 'acquire', '--peer', peerId, '--task', String(ownedTask.id), ...lockArgv(missingLock.base_resource, missingLock.scope), '--ttl', String(DEFAULT_LOCK_TTL), '--reason', '<work>'],
+        `task #${ownedTask.id} needs ${lockLabel(missingLock)} lock`,
+        true,
+        { task_id: ownedTask.id, resource: missingLock.base_resource, scope: missingLock.scope }
+      ));
     }
     if (ownedTask.status === 'claimed') {
       taskActions.push(makeAction('task.update', ['task', 'update', '--peer', peerId, '--id', String(ownedTask.id), '--status', 'running', '--summary', '<started>'], `task #${ownedTask.id} is claimed but not running`, true, { task_id: ownedTask.id }));
@@ -2551,7 +2358,7 @@ function deriveAutomation(snapshot, peer = null, opts = {}) {
     automation.finish_actions.push(makeAction('handoff.create', ['handoff', 'create', '--from', peerId, '--task', String(ownedTask.id), '--summary', '<summary>', '--tests', '<tests>', '--risks', '<risks>'], `handoff task #${ownedTask.id} before stopping`, true, { task_id: ownedTask.id }));
     automation.finish_actions.push(makeAction('task.done', ['task', 'done', '--peer', peerId, '--id', String(ownedTask.id), '--summary', '<summary>'], `mark task #${ownedTask.id} done after handoff`, true, { task_id: ownedTask.id }));
     for (const lock of ownLocks) {
-      automation.finish_actions.push(makeAction('lock.release', ['lock', 'release', '--peer', peerId, '--resource', lock.resource], `release ${lock.resource}`, true, { task_id: lock.task_id || null, resource: lock.resource }));
+      automation.finish_actions.push(makeAction('lock.release', ['lock', 'release', '--peer', peerId, ...lockArgv(lockBaseResource(lock), lockScope(lock))], `release ${lockLabel(lock)}`, true, { task_id: lock.task_id || null, resource: lockBaseResource(lock), scope: lockScope(lock) }));
     }
   }
   automation.actions.push(...lockActions, ...messageActions, ...taskActions);
@@ -2566,6 +2373,7 @@ function deriveAutomation(snapshot, peer = null, opts = {}) {
     : automation.next_action);
   if (automation.next_action.kind === 'msg.reply' || automation.next_action.kind === 'msg.inbox') automation.phase = 'reply_message';
   else if (automation.next_action.kind === 'task.claim' || automation.next_action.kind === 'task.next') automation.phase = 'claim_task';
+  else if (automation.next_action.kind === 'task.takeover') automation.phase = 'takeover_task';
   else if (automation.next_action.kind === 'lock.acquire') automation.phase = 'acquire_lock';
   else if (automation.next_action.kind === 'msg.send') automation.phase = 'coordinate_lock';
   else if (automation.next_action.kind === 'team.plan') automation.phase = 'team_plan';
@@ -2620,6 +2428,8 @@ function formatOpenTaskLine(task) {
   const parts = [`#${task.id}`, task.status];
   if (task.owner) parts.push(`owner=${task.owner}`);
   if (task.assignee) parts.push(`assignee=${task.assignee}`);
+  const ownerState = taskOwnerStateText(task);
+  if (ownerState) parts.push(`owner_state=${ownerState}`);
   return `${parts.join(' ')}: ${task.title}`;
 }
 
@@ -2644,14 +2454,15 @@ function collectStateSnapshot(db, ctx, peer = null, opts = {}) {
     ORDER BY last_seen_at DESC, id ASC
     LIMIT 200
   `).all(t);
-  const tasks = queryOpenTasks(db, 200);
+  const taskRows = queryOpenTasks(db, 200);
   const locks = db.prepare(`
-    SELECT resource, owner, task_id, reason, expires_at, created_at
+    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);
   const messages = peer
     ? queryInbox(db, peer, false, 50)
     : db.prepare(`
@@ -2742,7 +2553,7 @@ function buildHookCoordinationContext(db, ctx, peerId) {
   if (snapshot.locks.length > 0) {
     parts.push('[hello-cc active locks]');
     parts.push(...snapshot.locks.slice(0, 8).map((lock) =>
-      `- ${lock.resource} owner=${lock.owner}${lock.task_id ? ` task #${lock.task_id}` : ''}`));
+      `- ${lockLabel(lock)} owner=${lock.owner}${lock.task_id ? ` task #${lock.task_id}` : ''}`));
   } else {
     parts.push('[hello-cc active locks]\n(none)');
   }
@@ -2764,153 +2575,23 @@ function ackMessages(db, peerId, messages) {
   }
 }
 
-function formatJson(ok, dataOrError) {
-  if (ok) return JSON.stringify({ ok: true, data: dataOrError }, null, 2);
-  return JSON.stringify({ ok: false, error: dataOrError }, null, 2);
+function writeGuidance(ctx) {
+  return writeGuidanceForRoot(ctx.root);
 }
 
-function printResult(ctx, data, render) {
-  if (ctx.json) {
-    console.log(formatJson(true, data));
-  } else {
-    const output = render ? render(data) : String(data ?? '');
-    if (output) console.log(output);
-  }
+function removeGuidanceBlocks(ctx) {
+  return removeGuidanceBlocksForRoot(ctx.root);
 }
 
-function shellExports(values) {
-  return Object.entries(values)
-    .map(([key, value]) => `export ${key}=${shellQuoteArg(value)}`)
-    .join('\n');
-}
-
-function table(rows, columns) {
-  if (!rows.length) return '(none)';
-  const widths = columns.map((col) => Math.max(col.label.length, ...rows.map((row) => String(col.value(row) ?? '').length)));
-  const header = columns.map((col, i) => col.label.padEnd(widths[i])).join('  ');
-  const sep = widths.map((w) => '-'.repeat(w)).join('  ');
-  const body = rows.map((row) => columns.map((col, i) => String(col.value(row) ?? '').padEnd(widths[i])).join('  '));
-  return [header, sep, ...body].join('\n');
-}
-
-function writeGuidance(ctx) {
-  const guidePath = path.join(ctx.root, '.hello-cc', 'HCC.md');
-  fs.mkdirSync(path.dirname(guidePath), { recursive: true });
-  const content = `# hello-cc Coordination Rules
-
-This project may be edited by multiple Claude Code and Codex CLI sessions.
-
-Use \`hcc\` as the source of truth for cross-session coordination. If the user
-asks what other sessions are doing, do not answer from generic model knowledge.
-Run the project-local commands below and summarize the result.
-
-Each terminal session must use a stable peer id, for example codex-a,
-codex-b, claude-a, claude-b, or gpu-runner-a.
-
-Status checks:
-- \`hcc peers\` shows known Claude/Codex/shell sessions.
-- \`hcc task list\` shows all open tasks. Tasks stay visible until \`done\` or
-  \`abandoned\`; they are not read/unread items.
-- \`hcc msg inbox\` shows unread messages for this session.
-- \`hcc lock list\` shows active advisory locks.
-- \`hcc status\` summarizes peers, tasks, locks, inbox, and recent events.
-- \`hcc team status --task N\` summarizes explicit subtasks for a parent task.
-
-Read-only work:
-- Reading files, searching, inspecting \`git diff\` / \`git status\`, reviewing
-  uncommitted changes, and running non-mutating checks such as \`node --check\`
-  do not require locks.
-- For read-only review, do not acquire file locks. If another live peer already
-  holds write locks on changed files, report that the review is only a current
-  snapshot and not a final commit-ready verdict.
-- Use tasks, messages, events, or handoffs to make read-only review visible;
-  do not use advisory locks to reserve files you are only reading.
-
-Review and monitoring:
-- Reviewing another peer's work is a read-only activity. You may inspect current
-  diffs, task state, messages, handoffs, and non-mutating checks while that peer
-  keeps its write locks.
-- If you find a concrete issue in another peer's task, proactively send that
-  peer an \`hcc msg\` with the task id, affected file or behavior, why it is a
-  problem, and a suggested fix or verification step.
-- Continue monitoring until the peer fixes the issue, records a follow-up task,
-  or hands off. Do not silently treat a snapshot review as final approval.
-
-Before mutating work:
-- Register with hcc.
-- Read current status with \`hcc status\`, \`hcc state\`, \`hcc task list\`, and \`hcc msg inbox\`.
-- If \`hcc state\` shows a current task for this peer, continue that task until
-  handoff, done, or blocked instead of claiming a new task.
-- Claim one task before editing or mutating shared state when this peer has no
-  current task.
-- If work needs multiple peers, use \`hcc team plan\` and \`hcc team start\`
-  explicitly; do not create or claim hidden extra tasks.
-
-Before editing or mutating shared resources:
-- Acquire an advisory lock for the file, directory, module, or shared resource.
-- If another live peer holds the lock, message that peer instead of editing.
-- Acquire locks only before writes or shared-resource mutation, including file
-  edits, formatting, staging/committing through \`.git/index\`, intentional DB
-  data/schema changes, starting/stopping/restarting shared runtimes, or taking
-  over tmux/session/port resources.
-- Commit-readiness checks are read-only until staging begins. Do not lock source
-  files for review. Before committing, ensure no live peer holds write locks on
-  the files to be committed, then lock \`.git/index\` only while staging and
-  committing.
-
-During work:
-- Keep changes scoped to the claimed task.
-- Send progress messages when another session needs context.
-
-Before stopping:
-- Mark the task done or blocked.
-- Create a handoff with changed files, tests, and remaining risks.
-- Release locks you no longer need.
-`;
-  fs.writeFileSync(guidePath, content);
-  const clause = `\n<!-- hello-cc:start -->\n\n${content}\n<!-- hello-cc:end -->\n`;
-  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
-    const target = path.join(ctx.root, file);
-    if (!fs.existsSync(target)) {
-      fs.writeFileSync(target, clause.trimStart());
-      continue;
-    }
-    const existing = fs.readFileSync(target, 'utf8');
-    const updated = existing.includes('<!-- hello-cc:start -->')
-      ? existing.replace(/<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->/, clause.trim())
-      : `${existing.trimEnd()}\n${clause}`;
-    fs.writeFileSync(target, updated);
-  }
-  return guidePath;
-}
-
-function removeGuidanceBlocks(ctx) {
-  const changed = [];
-  for (const file of ['CLAUDE.md', 'AGENTS.md']) {
-    const target = path.join(ctx.root, file);
-    if (!fs.existsSync(target)) continue;
-    const existing = fs.readFileSync(target, 'utf8');
-    const updated = existing
-      .replace(/\n?<!-- hello-cc:start -->[\s\S]*?<!-- hello-cc:end -->\n?/g, '\n')
-      .replace(/\n{3,}/g, '\n\n')
-      .trimEnd();
-    if (updated !== existing) {
-      fs.writeFileSync(target, updated ? `${updated}\n` : '');
-      changed.push(target);
-    }
-  }
-  return changed;
-}
-
-function normalizeListText(value, fallback = []) {
-  if (value === undefined || value === null || value === '') return JSON.stringify(fallback);
-  const text = String(value);
-  try {
-    JSON.parse(text);
-    return text;
-  } catch {
-    return JSON.stringify(text.split(',').map((item) => item.trim()).filter(Boolean));
-  }
+function normalizeListText(value, fallback = []) {
+  if (value === undefined || value === null || value === '') return JSON.stringify(fallback);
+  const text = String(value);
+  try {
+    JSON.parse(text);
+    return text;
+  } catch {
+    return JSON.stringify(text.split(',').map((item) => item.trim()).filter(Boolean));
+  }
 }
 
 function changedFiles(cwd) {
@@ -3069,6 +2750,7 @@ async function cmdTask(ctx, args) {
   if (sub === 'create') return taskCreate(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));
   if (sub === 'next') return taskNext(ctx, args.slice(1));
   if (sub === 'update') return taskUpdate(ctx, args.slice(1));
   if (sub === 'done') return taskDone(ctx, args.slice(1));
@@ -3136,12 +2818,20 @@ async function taskList(ctx, args) {
   } else {
     rows = queryOpenTasks(db, limit);
   }
+  const t = now();
+  const peers = db.prepare(`
+    SELECT id, last_seen_at, (? - last_seen_at) AS age_sec
+    FROM peers
+  `).all(t);
+  const locks = db.prepare('SELECT * FROM locks WHERE expires_at > ?').all(t);
+  rows = annotateTasksWithLiveness(rows, peers, locks, t);
   printResult(ctx, rows, (data) => table(data, [
     { label: 'id', value: (r) => `#${r.id}` },
     { label: 'status', value: (r) => r.status },
     { label: 'prio', value: (r) => r.priority },
     { label: 'assignee', value: (r) => r.assignee || '' },
     { label: 'owner', value: (r) => r.owner || '' },
+    { label: 'owner_state', value: (r) => taskOwnerStateText(r) },
     { label: 'parent', value: (r) => r.parent_id ? `#${r.parent_id}` : '' },
     { label: 'role', value: (r) => r.team_role || '' },
     { label: 'title', value: (r) => r.title }
@@ -3149,86 +2839,45 @@ async function taskList(ctx, args) {
 }
 
 async function taskClaim(ctx, args) {
-  const opts = parseOpts(args, { booleans: ['force'] });
+  const opts = parseOpts(args, { booleans: ['force'], arrays: ['id', 'ids'] });
+  const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
+  const peer = identity.id;
+  const ids = parseTaskIds(opts);
+  const db = connect(ctx);
+  touchCurrentPeer(db, ctx, identity, 'working', 'shell');
+  const tasks = claimTaskRowsForPeer(db, peer, ids, { force: Boolean(opts.force) });
+  printResult(ctx, ids.length === 1 ? tasks[0] : tasks, (data) => taskRowsText(Array.isArray(data) ? data : [data], 'claimed'));
+}
+
+async function taskTakeover(ctx, args) {
+  const opts = parseOpts(args);
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
   const id = intOpt(opts, 'id', intOpt({ id: opts._[0] }, 'id'));
   if (!id) throw new CliError('BAD_ARGS', 'Missing --id');
+  const reason = required(opts, 'reason');
+  const policy = opts.policy || 'any';
+  const staleAfter = positiveIntOpt(opts, 'stale-after', ACTIVE_PEER_TTL, { max: 86400 * 30 });
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, '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 });
-    }
-    if (row.assignee && row.assignee !== peer && !opts.force) {
-      throw new CliError('TASK_ASSIGNED', `Task #${id} is assigned to ${row.assignee}`, { assignee: row.assignee });
-    }
-    if (!['pending', 'blocked', 'claimed', 'running'].includes(row.status) && !opts.force) {
-      throw new CliError('BAD_STATE', `Task #${id} is ${row.status}`);
-    }
-    const t = now();
-    db.prepare(`
-      UPDATE tasks
-      SET owner = ?, status = 'claimed', claimed_at = COALESCE(claimed_at, ?), updated_at = ?
-      WHERE id = ?
-    `).run(peer, t, t, id);
-    addEvent(db, 'task.claimed', peer, id, { previous_owner: row.owner, force: Boolean(opts.force) });
-    return db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
-  });
-  printResult(ctx, task, (data) => `claimed task #${data.id}: ${data.title}`);
+  const task = takeOverTaskForPeer(db, peer, id, { reason, policy, staleAfter });
+  printResult(ctx, task, (data) => `took over task #${data.id}: ${data.title}`);
 }
 
 async function taskNext(ctx, args) {
   const opts = parseOpts(args, { booleans: ['force'] });
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
+  const count = positiveIntOpt(opts, 'count', 1, { max: 50 });
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, 'working', 'shell');
-  const task = tx(db, () => {
-    if (!opts.force) {
-      const current = 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);
-      if (current) return { ...current, current: true };
-    }
-    const row = db.prepare(`
-      SELECT * FROM tasks
-      WHERE status = 'pending'
-        AND owner IS NULL
-        AND (assignee IS NULL OR assignee = ?)
-      ORDER BY CASE WHEN assignee = ? THEN 0 ELSE 1 END, priority ASC, id ASC
-      LIMIT 1
-    `).get(peer, peer);
-    if (!row) return null;
-    const t = now();
-    db.prepare(`
-      UPDATE tasks
-      SET owner = ?, status = 'claimed', claimed_at = ?, updated_at = ?
-      WHERE id = ? AND owner IS NULL AND status = 'pending'
-    `).run(peer, t, t, row.id);
-    addEvent(db, 'task.claimed', peer, row.id, { next: true });
-    return db.prepare('SELECT * FROM tasks WHERE id = ?').get(row.id);
-  });
-  printResult(ctx, task, (data) => {
+  const result = claimNextTasksForPeer(db, peer, { force: Boolean(opts.force), count });
+  printResult(ctx, count === 1 ? (result.current || result.tasks[0] || null) : result, (data) => {
     if (!data) return 'no pending task';
-    return data.current
-      ? `current task #${data.id}: ${data.title} (${data.status})`
-      : `claimed task #${data.id}: ${data.title}`;
+    if (data.current === true) return `current task #${data.id}: ${data.title} (${data.status})`;
+    if (data.current) return `current task #${data.current.id}: ${data.current.title} (${data.current.status})`;
+    if (data.tasks) return data.tasks.length ? taskRowsText(data.tasks, 'claimed') : 'no pending task';
+    return `claimed task #${data.id}: ${data.title}`;
   });
 }
 
@@ -3846,7 +3495,7 @@ async function lockAcquire(ctx, args) {
   const opts = parseOpts(args);
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
-  const resource = required(opts, 'resource');
+  const requested = scopedLockResource(required(opts, 'resource'), opts.scope);
   const taskId = intOpt(opts, 'task', null);
   const ttl = intOpt(opts, 'ttl', DEFAULT_LOCK_TTL);
   const reason = opts.reason || '';
@@ -3854,66 +3503,73 @@ async function lockAcquire(ctx, args) {
   touchCurrentPeer(db, ctx, identity, 'working', 'shell');
   const lock = tx(db, () => {
     const t = now();
-    const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(resource);
-    if (existing && existing.expires_at > t && existing.owner !== peer) {
-      throw new CliError('LOCK_HELD', `Resource is locked by ${existing.owner}`, {
-        resource,
-        owner: existing.owner,
-        expires_at: iso(existing.expires_at)
+    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, owner, task_id, reason, expires_at, created_at)
-      VALUES (?, ?, ?, ?, ?, ?)
+      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(resource, peer, taskId, reason, t + ttl, existing ? existing.created_at : t);
-    addEvent(db, 'lock.acquired', peer, taskId, { resource, ttl, previous_owner: existing ? existing.owner : null });
-    return db.prepare('SELECT * FROM locks WHERE resource = ?').get(resource);
+    `).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);
   });
-  printResult(ctx, lock, (data) => `locked ${data.resource} by ${data.owner} until ${iso(data.expires_at)}`);
+  printResult(ctx, lock, (data) => `locked ${lockLabel(data)} by ${data.owner} until ${iso(data.expires_at)}`);
 }
 
 async function lockRelease(ctx, args) {
   const opts = parseOpts(args, { booleans: ['force'] });
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
-  const resource = required(opts, 'resource');
+  const requested = scopedLockResource(required(opts, 'resource'), opts.scope);
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, null, 'shell');
   const result = tx(db, () => {
-    const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(resource);
-    if (!existing) return { released: false, resource };
+    const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+    if (!existing) return { released: false, ...requested };
     if (existing.owner !== peer && !opts.force) {
       throw new CliError('LOCK_OWNED', `Lock is owned by ${existing.owner}`, { owner: existing.owner });
     }
-    db.prepare('DELETE FROM locks WHERE resource = ?').run(resource);
-    addEvent(db, 'lock.released', peer, existing.task_id || null, { resource, force: Boolean(opts.force) });
-    return { released: true, resource };
+    db.prepare('DELETE FROM locks WHERE resource = ?').run(requested.resource);
+    addEvent(db, 'lock.released', peer, existing.task_id || null, { resource: requested.base_resource, lock_resource: requested.resource, scope: requested.scope, force: Boolean(opts.force) });
+    return { released: true, ...requested };
   });
-  printResult(ctx, result, (data) => data.released ? `released ${data.resource}` : `no lock for ${data.resource}`);
+  printResult(ctx, result, (data) => data.released ? `released ${lockLabel(data)}` : `no lock for ${lockLabel(data)}`);
 }
 
 async function lockRenew(ctx, args) {
   const opts = parseOpts(args);
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
-  const resource = required(opts, 'resource');
+  const requested = scopedLockResource(required(opts, 'resource'), opts.scope);
   const ttl = intOpt(opts, 'ttl', DEFAULT_LOCK_TTL);
   const db = connect(ctx);
   touchCurrentPeer(db, ctx, identity, 'working', 'shell');
   const lock = tx(db, () => {
-    const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(resource);
-    if (!existing) throw new CliError('NOT_FOUND', `No lock for ${resource}`);
+    const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+    if (!existing) throw new CliError('NOT_FOUND', `No lock for ${lockLabel(requested)}`);
     if (existing.owner !== peer) throw new CliError('LOCK_OWNED', `Lock is owned by ${existing.owner}`, { owner: existing.owner });
-    db.prepare('UPDATE locks SET expires_at = ? WHERE resource = ?').run(now() + ttl, resource);
-    addEvent(db, 'lock.renewed', peer, existing.task_id || null, { resource, ttl });
-    return db.prepare('SELECT * FROM locks WHERE resource = ?').get(resource);
+    db.prepare('UPDATE locks SET expires_at = ? WHERE resource = ?').run(now() + ttl, requested.resource);
+    addEvent(db, 'lock.renewed', peer, existing.task_id || null, { resource: requested.base_resource, lock_resource: requested.resource, scope: requested.scope, ttl });
+    return db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
   });
-  printResult(ctx, lock, (data) => `renewed ${data.resource} until ${iso(data.expires_at)}`);
+  printResult(ctx, lock, (data) => `renewed ${lockLabel(data)} until ${iso(data.expires_at)}`);
 }
 
 async function lockList(ctx, args) {
@@ -3923,7 +3579,8 @@ async function lockList(ctx, args) {
     ? db.prepare('SELECT * FROM locks ORDER BY resource ASC').all()
     : db.prepare('SELECT * FROM locks WHERE expires_at > ? ORDER BY resource ASC').all(now());
   printResult(ctx, rows, (data) => table(data, [
-    { label: 'resource', value: (r) => r.resource },
+    { label: 'resource', value: (r) => lockBaseResource(r) },
+    { label: 'scope', value: (r) => lockScope(r) },
     { label: 'owner', value: (r) => r.owner },
     { label: 'task', value: (r) => r.task_id ? `#${r.task_id}` : '' },
     { label: 'expires', value: (r) => iso(r.expires_at) },
@@ -4009,36 +3666,46 @@ async function cmdStatus(ctx, args) {
   const opts = parseOpts(args);
   const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
   const peer = identity.id;
+  const data = statusSummary(ctx, peer, identity);
+  printResult(ctx, data, (s) => renderStatusSummary(s, peer));
+}
+
+function statusSummary(ctx, peer = null, identity = null) {
   const db = connect(ctx);
-  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 - ACTIVE_PEER_TTL).n;
-  const stalePeers = db.prepare('SELECT COUNT(*) AS n FROM peers WHERE last_seen_at < ?').get(t - ACTIVE_PEER_TTL).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 data = { root: ctx.root, db: ctx.dbPath, active_peers: activePeers, stale_peers: stalePeers, tasks: taskRows, active_locks: locks, unread, recent_events: recent };
-  printResult(ctx, data, (s) => {
-    const taskSummary = s.tasks.length ? s.tasks.map((r) => `${r.status}:${r.n}`).join(', ') : 'none';
-    return [
-      `root: ${s.root}`,
-      `db: ${s.db}`,
-      `peers: active=${s.active_peers}, stale=${s.stale_peers}`,
-      `tasks: ${taskSummary}`,
-      `locks: active=${s.active_locks}`,
-      peer ? `inbox(${peer}): unread=${s.unread}` : null,
-      '',
-      'recent events:',
-      table(s.recent_events, [
-        { label: 'id', value: (r) => `#${r.id}` },
-        { label: 'type', value: (r) => r.type },
-        { label: 'actor', value: (r) => r.actor || '' },
-        { label: 'task', value: (r) => r.task_id ? `#${r.task_id}` : '' },
-        { label: 'time', value: (r) => iso(r.created_at) }
-      ])
-    ].filter((line) => line !== null).join('\n');
-  });
+  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 - ACTIVE_PEER_TTL).n;
+    const stalePeers = db.prepare('SELECT COUNT(*) AS n FROM peers WHERE last_seen_at < ?').get(t - ACTIVE_PEER_TTL).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();
+    return { root: ctx.root, db: ctx.dbPath, active_peers: activePeers, stale_peers: stalePeers, tasks: taskRows, active_locks: locks, unread, recent_events: recent };
+  } finally {
+    db.close();
+  }
+}
+
+function renderStatusSummary(s, peer = null) {
+  const taskSummary = s.tasks.length ? s.tasks.map((r) => `${r.status}:${r.n}`).join(', ') : 'none';
+  return [
+    `root: ${s.root}`,
+    `db: ${s.db}`,
+    `peers: active=${s.active_peers}, stale=${s.stale_peers}`,
+    `tasks: ${taskSummary}`,
+    `locks: active=${s.active_locks}`,
+    peer ? `inbox(${peer}): unread=${s.unread}` : null,
+    '',
+    'recent events:',
+    table(s.recent_events, [
+      { label: 'id', value: (r) => `#${r.id}` },
+      { label: 'type', value: (r) => r.type },
+      { label: 'actor', value: (r) => r.actor || '' },
+      { label: 'task', value: (r) => r.task_id ? `#${r.task_id}` : '' },
+      { label: 'time', value: (r) => iso(r.created_at) }
+    ])
+  ].filter((line) => line !== null).join('\n');
 }
 
 function normalizeStateResources(values) {
@@ -4052,7 +3719,7 @@ async function cmdState(ctx, args) {
   const identity = resolveCurrentPeer(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 });
+  const snapshot = statusSnapshot(ctx, peer, { resources, intent: opts.intent || null, scope: opts.scope || null });
   printResult(ctx, snapshot, (data) => {
     const automation = data.automation;
     const lines = [
@@ -4103,75 +3770,22 @@ Coordination rules:
 - Claim exactly one task before editing.
 - If state shows a current task for ${peer}, continue that task before claiming another pending task.
 - Before editing a file, directory, module, or shared test resource, run:
-  ${cmd} lock acquire --peer ${peer} --resource <path-or-module> --task <task-id>
+  ${cmd} lock acquire --peer ${peer} --resource <path-or-module> [--scope <scope>] --task <task-id>
 - If a lock is held by another peer, message that peer instead of editing:
   ${cmd} msg send --from ${peer} --to <peer-id> --body "<question>"
 - Report progress or requests through msg send.
 - Before stopping, run tests, create a handoff, and release locks:
   ${cmd} handoff create --from ${peer} --task <task-id> --summary "<what changed>" --tests "<commands/results>" --risks "<known risks>"
   ${cmd} task done --peer ${peer} --id <task-id> --summary "<done summary>"
-  ${cmd} lock release --peer ${peer} --resource <path-or-module>
+  ${cmd} lock release --peer ${peer} --resource <path-or-module> [--scope <scope>]
 `;
   printResult(ctx, { prompt: text }, () => text);
 }
 
-function readRequestBody(req, limit = 1024 * 1024) {
-  return new Promise((resolve, reject) => {
-    let body = '';
-    req.on('data', (chunk) => {
-      body += chunk;
-      if (body.length > limit) {
-        reject(new CliError('REQUEST_TOO_LARGE', 'Request body is too large'));
-        req.destroy();
-      }
-    });
-    req.on('end', () => resolve(body));
-    req.on('error', reject);
-  });
-}
-
-async function readJsonRequest(req) {
-  const body = await readRequestBody(req);
-  if (!body.trim()) return {};
-  return JSON.parse(body);
-}
-
-function sendHttp(res, status, contentType, body) {
-  res.writeHead(status, {
-    'Content-Type': contentType,
-    'Cache-Control': 'no-store'
-  });
-  res.end(body);
-}
-
-function sendJson(res, status, body) {
-  sendHttp(res, status, 'application/json; charset=utf-8', JSON.stringify(body, null, 2));
-}
-
-function sendFile(res, filePath, contentType) {
-  try {
-    const body = fs.readFileSync(filePath);
-    res.writeHead(200, {
-      'Content-Type': contentType,
-      'Cache-Control': 'no-store'
-    });
-    res.end(body);
-  } catch {
-    sendJson(res, 404, { ok: false, error: { code: 'NOT_FOUND', message: 'Asset not found' } });
-  }
-}
-
 function isLoopbackHost(host) {
   return host === '127.0.0.1' || host === 'localhost' || host === '::1';
 }
 
-function authOk(url, req, token) {
-  if (!token) return true;
-  const queryToken = url.searchParams.get('token');
-  const auth = req.headers.authorization || '';
-  return queryToken === token || auth === `Bearer ${token}`;
-}
-
 function defaultSessionCommand(kind) {
   if (kind === 'codex') return 'codex';
   if (kind === 'claude') return 'claude';
@@ -4478,1558 +4092,263 @@ function statusSnapshot(ctx, peer = null, opts = {}) {
   }
 }
 
-function webIndexHtml() {
-  return `<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>hello-cc</title>
-  <link rel="stylesheet" href="/assets/xterm.css">
-  <style>
-    :root {
-      color-scheme: dark;
-      --bg: #101214;
-      --panel: #181b1f;
-      --panel-2: #20242a;
-      --border: #303640;
-      --text: #eef2f6;
-      --muted: #a3adba;
-      --accent: #40c4aa;
-      --warn: #f2bb4f;
-      --danger: #ff6b6b;
-      --ok: #75d17c;
-      --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
-      --sans: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-    }
-    * { box-sizing: border-box; }
-    body {
-      margin: 0;
-      min-height: 100vh;
-      background: var(--bg);
-      color: var(--text);
-      font-family: var(--sans);
-      overflow: hidden;
-    }
-    button, input, select {
-      font: inherit;
-    }
-    button {
-      border: 1px solid var(--border);
-      background: var(--panel-2);
-      color: var(--text);
-      height: 32px;
-      border-radius: 6px;
-      padding: 0 10px;
-      cursor: pointer;
-    }
-    button:hover { border-color: var(--accent); }
-    button.primary { background: #1b5f54; border-color: #267f71; }
-    button.danger { background: #5d252a; border-color: #8c333d; }
-    input, select {
-      width: 100%;
-      height: 32px;
-      border: 1px solid var(--border);
-      background: #0d0f12;
-      color: var(--text);
-      border-radius: 6px;
-      padding: 0 9px;
-      min-width: 0;
-    }
-    label {
-      display: grid;
-      gap: 4px;
-      color: var(--muted);
-      font-size: 12px;
-    }
-    .app {
-      position: relative;
-      height: 100vh;
-      display: grid;
-      --left-width: 320px;
-      --right-width: 360px;
-      grid-template-columns: var(--left-width) minmax(0, 1fr) var(--right-width);
-      min-width: 640px;
-      transition: grid-template-columns .18s ease;
-    }
-    .app.resizing { transition: none; }
-    .app.left-collapsed  { grid-template-columns: 0 minmax(0, 1fr) var(--right-width); }
-    .app.right-collapsed { grid-template-columns: var(--left-width) minmax(0, 1fr) 0; }
-    .app.left-collapsed.right-collapsed { grid-template-columns: 0 minmax(0, 1fr) 0; }
-    /* Hide sidebar borders when collapsed so no 1px seam remains. */
-    .app.left-collapsed .sidebar { border-right-width: 0; }
-    .app.right-collapsed .inspector { border-left-width: 0; }
-    .edge-resizer {
-      position: absolute;
-      top: 0;
-      bottom: 0;
-      z-index: 55;
-      width: 12px;
-      cursor: col-resize;
-      touch-action: none;
-      user-select: none;
-      background: transparent;
-      transition: left .18s ease, right .18s ease, background .12s;
-    }
-    .edge-resizer:hover,
-    .app.resizing .edge-resizer {
-      background: rgba(126, 231, 215, .08);
-    }
-    .app.resizing .edge-resizer { transition: none; }
-    .edge-resizer-left  { left: var(--left-width); transform: translateX(-50%); }
-    .edge-resizer-right { right: var(--right-width); transform: translateX(50%); }
-    .app.left-collapsed  .edge-resizer-left  { left: 0; }
-    .app.right-collapsed .edge-resizer-right { right: 0; }
-    /* Small collapse handles centered vertically on each divider border.
-       They are children of .app (no overflow clip) and track the column edge. */
-    .edge-toggle {
-      position: absolute;
-      top: 50%;
-      z-index: 60;
-      width: 16px;
-      height: 44px;
-      padding: 0;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      font-size: 11px;
-      line-height: 1;
-      color: var(--muted);
-      background: var(--panel);
-      border: 1px solid var(--border);
-      border-radius: 6px;
-      cursor: col-resize;
-      touch-action: none;
-      user-select: none;
-      transition: left .18s ease, right .18s ease, color .12s, border-color .12s, background .12s;
-    }
-    .app.resizing .edge-toggle { transition: none; }
-    .edge-toggle:hover { color: var(--text); border-color: var(--accent); background: #1b1f26; }
-    .edge-left  { left: var(--left-width); transform: translate(-50%, -50%); }
-    .edge-right { right: var(--right-width); transform: translate(50%, -50%); }
-    .app.left-collapsed  .edge-left  { left: 0;  transform: translate(0, -50%); }
-    .app.right-collapsed .edge-right { right: 0; transform: translate(0, -50%); }
-    .sidebar, .inspector {
-      min-height: 0;
-      min-width: 0;
-      max-width: 100%;
-      overflow: hidden;
-      background: var(--panel);
-      border-right: 1px solid var(--border);
-      display: grid;
-      grid-template-rows: auto auto auto auto 1fr;
-    }
-    .inspector {
-      border-right: 0;
-      border-left: 1px solid var(--border);
-      grid-template-rows: auto 1fr;
-    }
-    .sidebar > *, .inspector > * {
-      min-width: 0;
-      max-width: 100%;
-    }
-    .brand {
-      padding: 14px;
-      border-bottom: 1px solid var(--border);
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 10px;
-    }
-    .brand > div {
-      min-width: 0;
-    }
-    .brand strong { font-size: 15px; }
-    .brand span, .path {
-      color: var(--muted);
-      font-family: var(--mono);
-      font-size: 11px;
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
-    #connState {
-      flex: 0 0 92px;
-      max-width: 92px;
-      text-align: right;
-    }
-    .form {
-      padding: 12px;
-      display: grid;
-      gap: 9px;
-      border-bottom: 1px solid var(--border);
-    }
-    .grid2 {
-      display: grid;
-      grid-template-columns: 1fr 1fr;
-      gap: 8px;
-    }
-    .start-row {
-      display: grid;
-      grid-template-columns: 1fr auto;
-      gap: 8px;
-      align-items: end;
-    }
-    .start-options {
-      display: grid;
-      grid-template-columns: 1fr 1fr;
-      gap: 8px;
-    }
-    .start-options label[data-resume-field] {
-      grid-column: 1 / -1;
-    }
-    .session-header {
-      border-bottom: 1px solid var(--border);
-      padding: 8px 10px;
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 8px;
-      min-height: 48px;
-    }
-    .session-header strong {
-      font-size: 13px;
-      font-weight: 600;
-    }
-    .session-header label {
-      width: 118px;
-    }
-    .sessions, .state {
-      min-height: 0;
-      overflow-y: auto;
-      overflow-x: hidden;
-      padding: 10px;
-      display: grid;
-      grid-template-columns: minmax(0, 1fr);
-      align-content: start;
-      gap: 8px;
-      scrollbar-width: thin;
-      scrollbar-color: #3a3f4a transparent;
-    }
-    .sessions::-webkit-scrollbar, .state::-webkit-scrollbar { width: 8px; }
-    .sessions::-webkit-scrollbar-track, .state::-webkit-scrollbar-track { background: transparent; }
-    .sessions::-webkit-scrollbar-thumb, .state::-webkit-scrollbar-thumb { background: #3a3f4a; border-radius: 4px; }
-    .session {
-      border: 1px solid var(--border);
-      background: #111418;
-      border-radius: 8px;
-      padding: 9px;
-      display: grid;
-      grid-template-columns: minmax(0, 1fr);
-      gap: 7px;
-      cursor: pointer;
-    }
-    .session.active { border-color: var(--accent); }
-    .row {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 8px;
-      min-width: 0;
-    }
-    .row strong {
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
-    .badge {
-      font-family: var(--mono);
-      font-size: 11px;
-      border: 1px solid var(--border);
-      color: var(--muted);
-      padding: 2px 6px;
-      border-radius: 999px;
-      white-space: nowrap;
-    }
-    .badge.running { color: var(--ok); border-color: #3b7b44; }
-    .badge.working, .badge.busy { color: var(--warn); border-color: #6b5a20; }
-    .badge.stale, .badge.detached, .badge.idle { color: var(--muted); border-color: var(--border); }
-    .badge.exited { color: var(--danger); border-color: #87434a; }
-    .main {
-      min-height: 0;
-      min-width: 0;
-      overflow: hidden;
-      display: grid;
-      grid-template-rows: auto 1fr;
-      background: #0b0d10;
-    }
-    .toolbar {
-      min-height: 48px;
-      border-bottom: 1px solid var(--border);
-      display: flex;
-      align-items: center;
-      gap: 8px;
-      padding: 8px 10px;
-      overflow: hidden;
-    }
-    .toolbar .title {
-      flex: 1 1 auto;
-      min-width: 0;
-      display: grid;
-      gap: 2px;
-    }
-    .toolbar .title strong {
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
-    .quick {
-      display: flex;
-      gap: 8px;
-      flex-wrap: nowrap;
-      align-items: center;
-      flex: 0 0 auto;
-    }
-    /* Toolbar edge toggles for collapsing the side panels. */
-    .icon-btn {
-      flex: 0 0 auto;
-      width: 30px;
-      height: 30px;
-      padding: 0;
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      font-size: 15px;
-      line-height: 1;
-      color: var(--muted);
-      background: transparent;
-      border: 1px solid var(--border);
-      border-radius: 7px;
-      cursor: pointer;
-    }
-    .icon-btn:hover { color: var(--text); border-color: var(--accent); }
-    /* Compact actions dropdown so the top bar stays a single tidy row. */
-    .menu-wrap { position: relative; display: inline-flex; }
-    .menu-btn { white-space: nowrap; }
-    .menu {
-      position: fixed;
-      z-index: 1000;
-      min-width: 150px;
-      padding: 5px;
-      display: grid;
-      gap: 2px;
-      background: var(--panel);
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      box-shadow: 0 8px 24px rgba(0,0,0,.45);
-    }
-    .menu[hidden] { display: none; }
-    .menu button {
-      width: 100%;
-      text-align: left;
-      border: 0;
-      background: transparent;
-      padding: 7px 9px;
-      border-radius: 6px;
-      color: var(--text);
-    }
-    .menu button:hover { background: #1b1f26; }
-    #terminal {
-      min-height: 0;
-      overflow: hidden;
-      padding: 8px;
-    }
-    #terminal .xterm {
-      cursor: default;
-    }
-    /* The terminal mirrors a tmux pane; keep xterm's own hidden helper textarea
-       off-screen, but DO show the rendered block cursor (positioned from tmux). */
-    #terminal .xterm-helper-textarea {
-      caret-color: transparent !important;
-      color: transparent !important;
-      background: transparent !important;
-      left: -10000px !important;
-      top: 0 !important;
-      width: 1px !important;
-      height: 1px !important;
-      opacity: 0 !important;
-    }
-    .card {
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      background: #111418;
-      overflow: hidden;
-    }
-    .card.state-card {
-      min-height: 0;
-      max-height: min(34vh, 280px);
-      display: grid;
-      grid-template-rows: auto minmax(0, 1fr);
-    }
-    .card h2 {
-      margin: 0;
-      padding: 8px 10px;
-      border-bottom: 1px solid var(--border);
-      font-size: 13px;
-      font-weight: 600;
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      gap: 8px;
-    }
-    .card .body {
-      padding: 8px 10px;
-      display: grid;
-      gap: 6px;
-    }
-    .state-card .body {
-      min-height: 0;
-      max-height: min(28vh, 228px);
-      overflow-y: auto;
-      overflow-x: hidden;
-      align-content: start;
-      scrollbar-width: thin;
-      scrollbar-color: #3a3f4a transparent;
-    }
-    .state-card .body::-webkit-scrollbar { width: 8px; }
-    .state-card .body::-webkit-scrollbar-track { background: transparent; }
-    .state-card .body::-webkit-scrollbar-thumb { background: #3a3f4a; border-radius: 4px; }
-    .item {
-      display: grid;
-      gap: 2px;
-      font-size: 12px;
-      color: var(--muted);
-      border-bottom: 1px solid #242932;
-      padding-bottom: 6px;
-    }
-    .item:last-child { border-bottom: 0; padding-bottom: 0; }
-    .item strong { color: var(--text); font-size: 12px; }
-    .item span { overflow-wrap: anywhere; }
-    .mono { font-family: var(--mono); }
-    .empty { color: var(--muted); font-size: 12px; }
-    .sec-label { font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); padding: 6px 10px 2px; display: flex; align-items: center; gap: 6px; }
-    #terminal { display: flex; flex-direction: column; }
-  </style>
-</head>
-<body>
-  <div class="app">
-    <aside class="sidebar">
-      <div class="brand">
-        <div>
-          <strong>hello-cc</strong>
-          <div class="path" id="rootPath"></div>
-        </div>
-        <span id="connState" data-i18n="conn.offline">offline</span>
-      </div>
-      <div class="form" style="padding-top:10px;padding-bottom:10px">
-        <div class="grid2">
-          <label><span data-i18n="project">Project</span><select id="projectSelect"></select></label>
-          <label><span data-i18n="language">Language</span><select id="langSelect"><option value="en">English</option><option value="zh">中文</option></select></label>
-        </div>
-        <label><span data-i18n="projectPath">Project path</span><input id="projectPath" data-i18n-placeholder="projectPathPlaceholder" placeholder="/path/to/project"></label>
-        <button id="addProjectBtn" type="button" data-i18n="registerProject">Register Project</button>
-      </div>
-      <form class="form" id="startForm">
-        <div class="start-row">
-          <label><span data-i18n="newSession">New session</span><select id="kind"><option value="codex">codex</option><option value="claude">claude</option><option value="shell" data-i18n="kind.shell">shell</option></select></label>
-          <button class="primary" type="submit" data-i18n="start">Start</button>
-        </div>
-        <div class="start-options">
-          <label><span data-i18n="mode">Mode</span><select id="startMode"><option value="new" data-i18n="mode.new">new</option><option value="resume" data-i18n="mode.resume">resume</option><option value="last" data-i18n="mode.last">last</option><option value="continue" data-i18n="mode.continue">continue</option></select></label>
-          <label data-resume-field><span data-i18n="session">Session</span><select id="resumeSelect"></select></label>
-          <label data-resume-field data-resume-custom style="display:none"><span data-i18n="sessionId">Session id</span><input id="resumeArg" data-i18n-placeholder="sessionIdPlaceholder" placeholder="session id or name"></label>
-        </div>
-      </form>
-      <div class="session-header">
-        <strong data-i18n="sessions">Sessions</strong>
-        <label><span data-i18n="view">View</span><select id="sessionKindFilter"><option value="all" data-i18n="kind.all">all</option><option value="claude">claude</option><option value="codex">codex</option><option value="shell" data-i18n="kind.shell">shell</option><option value="other" data-i18n="kind.other">other</option></select></label>
-      </div>
-      <div class="sessions" id="sessions"></div>
-    </aside>
-
-    <main class="main">
-      <div class="toolbar">
-        <div class="title">
-          <strong id="activeTitle" data-i18n="noSessionSelected">No session selected</strong>
-          <span class="path" id="activeMeta" data-i18n="startOrSelect">Start or select a session from the left panel</span>
-        </div>
-        <div class="quick" id="quickBar">
-          <div class="menu-wrap">
-            <button class="menu-btn" id="actionsBtn" type="button" aria-haspopup="true" aria-expanded="false"><span data-i18n="actions">Actions</span> ▾</button>
-            <div class="menu" id="actionsMenu" hidden>
-              <button data-send="register" data-i18n="action.register">register</button>
-              <button data-send="inbox" data-i18n="action.inbox">inbox</button>
-              <button data-send="next" data-i18n="action.nextTask">next task</button>
-              <button data-send="status" data-i18n="action.status">status</button>
-              <button data-send="heartbeat" data-i18n="action.heartbeat">heartbeat</button>
-            </div>
-          </div>
-          <button class="danger" id="stopBtn" type="button" data-i18n="stop">stop</button>
-        </div>
-      </div>
-      <div id="terminal" style="min-height:0;flex:1"></div>
-      <div id="detectedPanel" style="display:none;overflow:auto;flex:1"></div>
-    </main>
-
-    <aside class="inspector">
-      <div class="brand">
-        <strong data-i18n="projectState">Project State</strong>
-        <button id="refreshBtn" type="button" data-i18n="refresh">Refresh</button>
-      </div>
-      <div class="state" id="state"></div>
-    </aside>
-
-    <button class="edge-toggle edge-left" id="toggleLeft" type="button" data-i18n-title="collapseSidebar" data-i18n-aria="toggleLeftSidebar" title="Collapse sidebar" aria-label="Toggle left sidebar">⟨</button>
-    <button class="edge-toggle edge-right" id="toggleRight" type="button" data-i18n-title="collapseStatePanel" data-i18n-aria="toggleRightPanel" title="Collapse state panel" aria-label="Toggle right panel">⟩</button>
-    <div class="edge-resizer edge-resizer-left" id="resizeLeft" role="separator" aria-orientation="vertical" data-i18n-aria="resizeLeftSidebar" data-i18n-title="resizeLeftSidebar" aria-label="Resize left sidebar" title="Resize left sidebar"></div>
-    <div class="edge-resizer edge-resizer-right" id="resizeRight" role="separator" aria-orientation="vertical" data-i18n-aria="resizeRightPanel" data-i18n-title="resizeRightPanel" aria-label="Resize right panel" title="Resize right panel"></div>
-  </div>
-
-  <script src="/assets/xterm.js"></script>
-  <script>
-    const initialParams = new URLSearchParams(location.search);
-    const token = initialParams.get('token') || '';
-    const headers = token ? { Authorization: 'Bearer ' + token } : {};
-    let currentProject = initialParams.get('project') || initialParams.get('root') || '';
-    let projects = [];
-    let sessionKindFilter = initialParams.get('kind') || 'all';
-    let sessions  = [];    // managed (PTY) sessions
-    let detected  = [];    // coordination-only peers (from hooks/watcher)
-    let resumableCache = []; // provider sessions available to resume (from /api/resumable)
-    let active    = null;  // active managed session id
-    let activeDetected = null; // active detected peer id
-    let activeType = 'managed'; // 'managed' | 'detected'
-    let activePeerTtl = 600;
-    let lastStateNow = 0;
-    let lastStateRoot = '';
-    let ws        = null;
-    let wsReconnectTimer = null;
-    const i18n = {
-      en: {
-        language: 'Language',
-        project: 'Project',
-        projectPath: 'Project path',
-        projectPathPlaceholder: '/path/to/project',
-        registerProject: 'Register Project',
-        newSession: 'New session',
-        start: 'Start',
-        mode: 'Mode',
-        'mode.new': 'new',
-        'mode.resume': 'resume',
-        'mode.last': 'last',
-        'mode.continue': 'continue',
-        session: 'Session',
-        sessionId: 'Session id',
-        sessionIdPlaceholder: 'session id or name',
-        sessions: 'Sessions',
-        view: 'View',
-        'kind.all': 'all',
-        'kind.shell': 'shell',
-        'kind.other': 'other',
-        noSessionSelected: 'No session selected',
-        startOrSelect: 'Start or select a session from the left panel',
-        actions: 'Actions',
-        'action.register': 'register',
-        'action.inbox': 'inbox',
-        'action.nextTask': 'next task',
-        'action.status': 'status',
-        'action.heartbeat': 'heartbeat',
-        stop: 'stop',
-        projectState: 'Project State',
-        refresh: 'Refresh',
-        managed: 'Managed',
-        detected: 'Detected',
-        running: 'running',
-        noActiveSessions: 'No active sessions.',
-        startOneAbove: 'Start one above',
-        orRunTerminal: 'or run in any terminal:',
-        noDetectedPeers: 'No detected peers.',
-        viewFilter: 'View filter',
-        noTasks: 'No tasks.',
-        noPeers: 'No peers.',
-        noActiveLocks: 'No active locks.',
-        noMessages: 'No messages.',
-        noTimelineItems: 'No timeline items.',
-        nextAction: 'Next Action',
-        timeline: 'Timeline',
-        messages: 'Messages',
-        peers: 'Peers',
-        tasks: 'Tasks',
-        locks: 'Locks',
-        owner: 'owner',
-        assignee: 'assignee',
-        task: 'task',
-        all: 'all',
-        next: 'next',
-        finish: 'finish',
-        warnings: 'warnings',
-        noImmediateAction: 'No immediate coordination action',
-        detectedSession: 'Detected Session',
-        sendMessage: 'Send Message',
-        messageHelp: "Message will appear in the peer's <code>hcc msg inbox</code> and be injected on next hook fire.",
-        messageBodyPlaceholder: 'Message body...',
-        send: 'Send',
-        peer: 'peer',
-        kind: 'kind',
-        status: 'status',
-        cwd: 'cwd',
-        pid: 'pid',
-        unknown: 'unknown',
-        lastSeen: 'last seen',
-        secondsAgo: 's ago',
-        age: 'age',
-        branch: 'branch',
-        runtime: 'runtime',
-        thread: 'thread',
-        reply: 'reply',
-        'status.active': 'active',
-        'status.stale': 'stale',
-        'status.unknown': 'unknown',
-        'status.running': 'running',
-        'status.idle': 'idle',
-        'status.exited': 'exited',
-        'status.claimed': 'claimed',
-        'status.review': 'review',
-        'status.blocked': 'blocked',
-        'status.done': 'done',
-        'status.abandoned': 'abandoned',
-        'status.pending': 'pending',
-        'conn.offline': 'offline',
-        'conn.online': 'online',
-        'conn.attached': 'attached',
-        'conn.reconnecting': 'reconnecting...',
-        'conn.coordinationOnly': 'coordination only',
-        'conn.error': 'error',
-        show: 'Show',
-        collapse: 'Collapse',
-        sidebar: 'sidebar',
-        statePanel: 'state panel',
-        dragToResize: 'drag to resize',
-        collapseSidebar: 'Collapse sidebar',
-        collapseStatePanel: 'Collapse state panel',
-        toggleLeftSidebar: 'Toggle left sidebar',
-        toggleRightPanel: 'Toggle right panel',
-        resizeLeftSidebar: 'Resize left sidebar',
-        resizeRightPanel: 'Resize right panel',
-        customSession: 'custom session id...'
-      },
-      zh: {
-        language: '语言',
-        project: '项目',
-        projectPath: '项目路径',
-        projectPathPlaceholder: '/项目/路径',
-        registerProject: '注册项目',
-        newSession: '新会话',
-        start: '启动',
-        mode: '模式',
-        'mode.new': '新建',
-        'mode.resume': '恢复',
-        'mode.last': '最近',
-        'mode.continue': '继续',
-        session: '会话',
-        sessionId: '会话 ID',
-        sessionIdPlaceholder: '会话 ID 或名称',
-        sessions: '会话',
-        view: '视图',
-        'kind.all': '全部',
-        'kind.shell': 'shell',
-        'kind.other': '其他',
-        noSessionSelected: '未选择会话',
-        startOrSelect: '从左侧面板启动或选择一个会话',
-        actions: '操作',
-        'action.register': '注册',
-        'action.inbox': '收件箱',
-        'action.nextTask': '下个任务',
-        'action.status': '状态',
-        'action.heartbeat': '心跳',
-        stop: '停止',
-        projectState: '项目状态',
-        refresh: '刷新',
-        managed: '托管',
-        detected: '检测到',
-        running: '运行中',
-        noActiveSessions: '没有活动会话。',
-        startOneAbove: '在上方启动一个会话',
-        orRunTerminal: '或在任意终端运行：',
-        noDetectedPeers: '没有检测到的协作方。',
-        viewFilter: '视图过滤',
-        noTasks: '没有任务。',
-        noPeers: '没有协作方。',
-        noActiveLocks: '没有活动锁。',
-        noMessages: '没有消息。',
-        noTimelineItems: '没有时间线条目。',
-        nextAction: '下一步',
-        timeline: '时间线',
-        messages: '消息',
-        peers: '协作方',
-        tasks: '任务',
-        locks: '锁',
-        owner: '负责人',
-        assignee: '执行者',
-        task: '任务',
-        all: '全部',
-        next: '下一步',
-        finish: '收尾',
-        warnings: '警告',
-        noImmediateAction: '当前没有需要立即处理的协作动作',
-        detectedSession: '检测到的会话',
-        sendMessage: '发送消息',
-        messageHelp: '消息会出现在该 peer 的 <code>hcc msg inbox</code> 中，并在下一次 hook 触发时注入。',
-        messageBodyPlaceholder: '消息内容...',
-        send: '发送',
-        peer: '协作方',
-        kind: '类型',
-        status: '状态',
-        cwd: '工作目录',
-        pid: 'PID',
-        unknown: '未知',
-        lastSeen: '最后出现',
-        secondsAgo: ' 秒前',
-        age: '时长',
-        branch: '分支',
-        runtime: '运行时',
-        thread: '线程',
-        reply: '回复',
-        'status.active': '活跃',
-        'status.stale': '过期',
-        'status.unknown': '未知',
-        'status.running': '运行中',
-        'status.idle': '空闲',
-        'status.exited': '已退出',
-        'status.claimed': '已认领',
-        'status.review': '审查中',
-        'status.blocked': '阻塞',
-        'status.done': '完成',
-        'status.abandoned': '已放弃',
-        'status.pending': '待处理',
-        'conn.offline': '离线',
-        'conn.online': '在线',
-        'conn.attached': '已连接',
-        'conn.reconnecting': '重连中...',
-        'conn.coordinationOnly': '仅协作',
-        'conn.error': '错误',
-        show: '显示',
-        collapse: '折叠',
-        sidebar: '侧栏',
-        statePanel: '状态面板',
-        dragToResize: '拖动调整大小',
-        collapseSidebar: '折叠侧栏',
-        collapseStatePanel: '折叠状态面板',
-        toggleLeftSidebar: '切换左侧栏',
-        toggleRightPanel: '切换右侧面板',
-        resizeLeftSidebar: '调整左侧栏宽度',
-        resizeRightPanel: '调整右侧面板宽度',
-        customSession: '自定义会话 ID...'
-      }
-    };
-    let lang = localStorage.getItem('hcc.lang') || ((navigator.language || '').toLowerCase().startsWith('zh') ? 'zh' : 'en');
-    if (!i18n[lang]) lang = 'en';
-
-    function tr(key, fallback = '') {
-      return i18n[lang]?.[key] || i18n.en[key] || fallback || key;
-    }
-
-    function setText(id, key) {
-      const el = document.getElementById(id);
-      if (el) el.textContent = tr(key);
-    }
-
-    function connText(key) {
-      const el = document.getElementById('connState');
-      if (el) {
-        el.dataset.stateKey = key;
-        el.textContent = tr('conn.' + key);
-      }
-    }
-
-    function applyLanguage() {
-      document.documentElement.lang = lang === 'zh' ? 'zh-CN' : 'en';
-      localStorage.setItem('hcc.lang', lang);
-      const sel = document.getElementById('langSelect');
-      if (sel) sel.value = lang;
-      document.querySelectorAll('[data-i18n]').forEach((el) => { el.textContent = tr(el.dataset.i18n); });
-      document.querySelectorAll('[data-i18n-placeholder]').forEach((el) => { el.placeholder = tr(el.dataset.i18nPlaceholder); });
-      document.querySelectorAll('[data-i18n-title]').forEach((el) => { el.title = tr(el.dataset.i18nTitle); });
-      document.querySelectorAll('[data-i18n-aria]').forEach((el) => { el.setAttribute('aria-label', tr(el.dataset.i18nAria)); });
-      if (!active && !activeDetected) {
-        setText('activeTitle', 'noSessionSelected');
-        setText('activeMeta', 'startOrSelect');
-      }
-      const stateKey = document.getElementById('connState')?.dataset.stateKey || 'offline';
-      connText(stateKey);
-      syncStartModeOptions();
-      renderSections();
-      if (activeType === 'detected' && activeDetected) {
-        const draft = document.getElementById('detMsg')?.value || '';
-        const peer = detected.find((p) => p.id === activeDetected) || { id: activeDetected };
-        document.getElementById('activeTitle').textContent = activeDetected + ' (' + tr('detected') + ')';
-        renderDetectedPanel(peer);
-        const detMsg = document.getElementById('detMsg');
-        if (detMsg && draft) detMsg.value = draft;
-      } else if (activeType === 'managed' && active) {
-        const meta = sessions.find((s) => s.id === active);
-        if (meta) {
-          document.getElementById('activeTitle').textContent = sessionPeerId(meta) || active;
-          document.getElementById('activeMeta').textContent = sessionMetaText(meta);
-        }
-      }
-      if (lastStateRoot) refreshCurrentState().catch(console.error);
-      syncToggleIcons();
-    }
-
-    function requestQuery(extra = {}) {
-      const params = new URLSearchParams();
-      if (token) params.set('token', token);
-      if (currentProject) params.set('root', currentProject);
-      for (const [key, value] of Object.entries(extra)) {
-        if (value !== undefined && value !== null && value !== '') params.set(key, value);
-      }
-      const text = params.toString();
-      return text ? '?' + text : '';
-    }
-
-    function updateLocationProject() {
-      const params = new URLSearchParams(location.search);
-      if (token) params.set('token', token);
-      if (currentProject) params.set('project', currentProject);
-      if (sessionKindFilter && sessionKindFilter !== 'all') params.set('kind', sessionKindFilter);
-      history.replaceState(null, '', location.pathname + '?' + params.toString());
-    }
-
-    const term = new Terminal({
-      cursorBlink: true,
-      cursorInactiveStyle: 'outline',
-      cursorStyle: 'bar',
-      convertEol: true,
-      fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
-      fontSize: 13,
-      theme: { background: '#0b0d10', foreground: '#eef2f6', cursor: '#7dd3fc', cursorAccent: '#0b0d10' }
-    });
-    term.open(document.getElementById('terminal'));
-
-    // Accurate terminal sizing via character measurement
-    function measureCharSize() {
-      const el = document.getElementById('terminal');
-      const canvas = document.createElement('canvas');
-      const ctx2d = canvas.getContext('2d');
-      ctx2d.font = '13px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace';
-      const m = ctx2d.measureText('M');
-      return { w: m.width || 8, h: 17 };
-    }
-
-    function resizeTerm() {
-      const el = document.getElementById('terminal');
-      const { w, h } = measureCharSize();
-      const cols = Math.max(60, Math.floor((el.clientWidth  - 16) / w));
-      const rows = Math.max(10, Math.floor((el.clientHeight - 16) / h));
-      term.resize(cols, rows);
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.send(JSON.stringify({ type: 'resize', cols, rows }));
-      }
-    }
-    window.addEventListener('resize', resizeTerm);
-    setTimeout(resizeTerm, 80);
-
-    term.onData((data) => {
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        ws.send(JSON.stringify({ type: 'input', data }));
-      }
-    });
-
-    async function api(path, options = {}) {
-      const res = await fetch(path + (path.includes('?') ? '&' : '?') + requestQuery().slice(1), {
-        ...options,
-        headers: { 'Content-Type': 'application/json', ...headers, ...(options.headers || {}) }
-      });
-      const json = await res.json();
-      if (!res.ok) throw new Error(json.error?.message || json.message || 'request failed');
-      return json;
-    }
-
-    function renderProjects() {
-      const select = document.getElementById('projectSelect');
-      select.innerHTML = projects.map((p) =>
-        '<option value="' + esc(p.root) + '">' + esc((p.name || p.root) + ' · ' + p.root) + '</option>'
-      ).join('');
-      if (currentProject) select.value = currentProject;
-      document.getElementById('sessionKindFilter').value = sessionKindFilter;
-    }
-
-    function kindMatches(item) {
-      const kind = ['claude', 'codex', 'shell'].includes(item.kind) ? item.kind : 'other';
-      return sessionKindFilter === 'all' || kind === sessionKindFilter;
-    }
-
-    function syncStartModeOptions() {
-      const kind = document.getElementById('kind').value;
-      const modeSelect = document.getElementById('startMode');
-      const current = modeSelect.value;
-      const modes = kind === 'claude'
-        ? [['new', 'new'], ['resume', 'resume'], ['continue', 'continue']]
-        : kind === 'codex'
-          ? [['new', 'new'], ['resume', 'resume'], ['last', 'last']]
-          : [['new', 'new']];
-      modeSelect.innerHTML = modes.map(([value]) => '<option value="' + value + '">' + tr('mode.' + value, value) + '</option>').join('');
-      modeSelect.value = modes.some(([value]) => value === current) ? current : 'new';
-      const isResume = modeSelect.value === 'resume';
-      document.querySelector('[data-resume-field]:not([data-resume-custom])').style.display = isResume ? '' : 'none';
-      if (isResume) loadResumable();
-      else document.querySelector('[data-resume-custom]').style.display = 'none';
-    }
-
-    // Fetch provider sessions hcc knows about and fill the resume dropdown.
-    async function loadResumable() {
-      try { const d = await api('/api/resumable'); resumableCache = d.resumable || []; }
-      catch { resumableCache = []; }
-      populateResumeSelect();
-    }
-    function populateResumeSelect() {
-      const kind = document.getElementById('kind').value;
-      const sel = document.getElementById('resumeSelect');
-      const prev = sel.value;
-      const items = resumableCache.filter((r) => r.provider === kind);
-      const opts = items.map((r) => {
-        const resume = r.resume || r.session_id || r.session_name || '';
-        const shortResume = resume.length > 14 ? resume.slice(0, 10) + '…' : resume;
-        const label = (r.name && r.name !== resume ? r.name + ' · ' : '') + shortResume + ' (' + r.peer + ')';
-        return '<option value="' + esc(resume) + '">' + esc(label) + '</option>';
-      });
-      opts.push('<option value="__custom__">' + esc(tr('customSession')) + '</option>');
-      sel.innerHTML = opts.join('');
-      if (prev && [...sel.options].some((o) => o.value === prev)) sel.value = prev;
-      toggleResumeCustom();
-    }
-    function toggleResumeCustom() {
-      const sel = document.getElementById('resumeSelect');
-      document.querySelector('[data-resume-custom]').style.display = sel.value === '__custom__' ? '' : 'none';
-    }
-
-    async function loadProjects() {
-      const data = await api('/api/projects');
-      projects = data.projects || [];
-      if (!currentProject) currentProject = data.current?.root || projects[0]?.root || '';
-      renderProjects();
-      updateLocationProject();
-    }
-
-    async function switchProject(root) {
-      currentProject = root;
-      updateLocationProject();
-      active = null;
-      activeDetected = null;
-      activeType = 'managed';
-      if (ws) { clearTimeout(wsReconnectTimer); ws.close(); ws = null; }
-      term.reset();
-      document.getElementById('activeTitle').textContent = tr('noSessionSelected');
-      document.getElementById('activeMeta').textContent = tr('startOrSelect');
-      await Promise.all([refreshSessions(), refreshDetected(), refreshState()]);
-      const first = sessions.find(s => s.status === 'running');
-      if (first) connectManaged(first.id);
-    }
-
-    function esc(text) {
-      return String(text ?? '').replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[ch]));
-    }
-
-    function fmtTime(ts) {
-      if (!ts) return '';
-      return new Date(ts * 1000).toLocaleTimeString();
-    }
-
-    function badgeClass(status) {
-      return String(status || '').toLowerCase().replace(/[^a-z0-9_-]/g, '');
-    }
-
-    function fmtAge(age) {
-      const n = Number(age);
-      if (!Number.isFinite(n)) return '?';
-      return Math.max(0, Math.round(n)) + (lang === 'zh' ? '秒' : 's');
-    }
-
-    function sessionPeerId(session) {
-      return session?.peer_id || session?.id || '';
-    }
-
-    function sessionRuntimeNote(session) {
-      const peerId = sessionPeerId(session);
-      return session?.id && peerId && session.id !== peerId ? tr('runtime') + '=' + session.id + ' · ' : '';
-    }
-
-    function sessionMetaText(session) {
-      return sessionRuntimeNote(session) + (session.command || '') + (session.pane ? ' · ' + session.pane : '') + ' · ' + (session.cwd || '');
-    }
-
-    function statusText(status) {
-      const value = String(status || 'unknown');
-      return tr('status.' + value.toLowerCase(), value);
-    }
-
-    function managedPeerId(id) {
-      return sessionPeerId(sessions.find((s) => s.id === id)) || id;
-    }
-
-    function peerIsActive(peer, basisNow = lastStateNow) {
-      const age = Number(peer?.age_sec);
-      if (Number.isFinite(age)) return age <= activePeerTtl;
-      const seen = Number(peer?.last_seen_at || 0);
-      const t = Number(basisNow || 0) || Math.floor(Date.now() / 1000);
-      return seen > 0 && (t - seen) <= activePeerTtl;
-    }
-
-      function peerStateView(peer, runtime = null, basisNow = lastStateNow) {
-      const activity = peer?.status || 'unknown';
-      const liveness = peerIsActive(peer, basisNow) ? 'active' : 'stale';
-      const age = fmtAge(peer?.age_sec);
-      const branch = peer?.branch ? ' ' + tr('branch') + '=' + peer.branch : '';
-      if (runtime) {
-        return {
-          label: runtime.status || 'running',
-          detail: tr('peer') + '=' + statusText(activity) + ' ' + statusText(liveness) + ' ' + tr('age') + '=' + age + branch
-        };
-      }
-      if (liveness === 'stale') {
-        return {
-          label: 'stale',
-          detail: tr('lastSeen') + '=' + statusText(activity) + ' ' + tr('age') + '=' + age + branch
-        };
-      }
-        return {
-          label: activity,
-          detail: statusText(liveness) + ' ' + tr('age') + '=' + age + branch
-        };
-      }
-
-      function bodyPinned(el) {
-        if (!el) return false;
-        return el.scrollTop + el.clientHeight >= el.scrollHeight - 8;
-      }
-
-      function renderTimelineItem(item) {
-        const meta = [
-          item.source + ':' + item.source_id,
-          item.task_id ? tr('task') + ' #' + item.task_id : '',
-          item.thread_id ? tr('thread') + ' #' + item.thread_id : '',
-          item.direction || '',
-          fmtTime(item.ts)
-        ].filter(Boolean).join(' · ');
-        return \`
-          <div class="item timeline-item">
-            <strong>\${esc(item.title || item.kind || item.source)} <span class="badge">\${esc(item.kind || item.source)}</span></strong>
-            <span>\${esc(meta)}</span>
-            \${item.text ? '<span>' + esc(item.text) + '</span>' : ''}
-          </div>\`;
-      }
-
-    document.getElementById('projectSelect').addEventListener('change', (event) => {
-      switchProject(event.target.value).catch(console.error);
-    });
-    document.getElementById('langSelect').addEventListener('change', (event) => {
-      lang = event.target.value === 'zh' ? 'zh' : 'en';
-      applyLanguage();
-    });
-    document.getElementById('sessionKindFilter').addEventListener('change', (event) => {
-      sessionKindFilter = event.target.value || 'all';
-      updateLocationProject();
-      renderSections();
-    });
-    document.getElementById('addProjectBtn').addEventListener('click', async () => {
-      const input = document.getElementById('projectPath');
-      const root = input.value.trim();
-      if (!root) return;
-      await api('/api/projects', { method: 'POST', body: JSON.stringify({ root }) });
-      input.value = '';
-      await loadProjects();
-      await switchProject(root);
-    });
-
-    // ── Sessions rendering (managed + detected) ──────────────────────────
-    function renderSections() {
-      const box = document.getElementById('sessions');
-      const visibleSessions = sessions.filter(kindMatches);
-      const visibleDetected = detected.filter(kindMatches);
-      const filterNote = sessionKindFilter === 'all' ? '' : '<br><br>' + esc(tr('viewFilter')) + ': ' + esc(sessionKindFilter);
-      const manHtml = visibleSessions.length
-        ? visibleSessions.map((s) => {
-          const peerId = sessionPeerId(s);
-          return \`
-          <div class="session \${active === s.id && activeType === 'managed' ? 'active' : ''}" data-id="\${esc(s.id)}" data-type="managed">
-            <div class="row"><strong>\${esc(peerId)}</strong><span class="badge \${badgeClass(s.status)}">\${esc(statusText(s.status))}</span></div>
-            <div class="row"><span class="badge">\${esc(s.kind)}</span><span class="badge \${s.type === 'external' || s.type === 'tmux' ? 'warn' : ''}">\${s.type === 'external' ? 'external' : s.type === 'tmux' ? 'tmux' : 'pty'}</span></div>
-            <div class="path">\${esc(sessionRuntimeNote(s) + (s.command || ''))}</div>
-          </div>\`;
-        }).join('')
-        : '<div class="empty">' + esc(tr('noActiveSessions')) + filterNote + '<br><br>' + esc(tr('startOneAbove')) + '<br>' + esc(tr('orRunTerminal')) + '<br><code>hcc peer start X -- claude</code></div>';
-
-      const detHtml = visibleDetected.length
-        ? visibleDetected.map((p) => {
-          const state = peerStateView(p);
-          return \`
-          <div class="session \${activeDetected === p.id && activeType === 'detected' ? 'active' : ''}" data-id="\${esc(p.id)}" data-type="detected">
-            <div class="row"><strong>\${esc(p.id)}</strong><span class="badge" style="color:var(--warn);border-color:#6b5a20">\${esc(tr('detected'))}</span></div>
-            <div class="row"><span class="badge">\${esc(p.kind)}</span><span class="badge \${badgeClass(state.label)}" title="\${esc(state.detail)}">\${esc(statusText(state.label))}</span></div>
-            <div class="path" title="\${esc(p.worktree || '')}">\${esc((p.worktree || '').split('/').slice(-2).join('/'))}</div>
-          </div>\`;
-        }).join('')
-        : '<div class="empty">' + esc(tr('noDetectedPeers')) + filterNote + '</div>';
-
-      const savedScroll = box.scrollTop;
-      box.innerHTML = \`
-        <div class="sec-label">\${esc(tr('managed'))} <span class="badge">\${visibleSessions.filter(s=>s.status==='running').length} \${esc(tr('running'))}</span></div>
-        \${manHtml}
-        <div class="sec-label" style="margin-top:10px">\${esc(tr('detected'))} <span class="badge" style="color:var(--warn)">\${visibleDetected.length}</span></div>
-        \${detHtml}
-      \`;
-      box.scrollTop = savedScroll;
-      box.querySelectorAll('.session[data-type="managed"]').forEach((el) => {
-        el.addEventListener('click', () => connectManaged(el.dataset.id));
-      });
-      box.querySelectorAll('.session[data-type="detected"]').forEach((el) => {
-        el.addEventListener('click', () => connectDetected(el.dataset.id));
-      });
-    }
-
-    async function refreshSessions() {
-      const data = await api('/api/sessions');
-      sessions = data.sessions || [];
-      renderSections();
-      if (active && activeType === 'managed') {
-        const meta = sessions.find((s) => s.id === active);
-        if (meta) {
-          document.getElementById('activeTitle').textContent = sessionPeerId(meta) || active;
-          document.getElementById('activeMeta').textContent = sessionMetaText(meta);
-        }
-      }
-      connText('online');
-    }
-
-    async function refreshDetected() {
-      try {
-        const data = await api('/api/detected');
-        activePeerTtl = Number(data.active_peer_ttl || activePeerTtl);
-        lastStateNow = Number(data.now || lastStateNow);
-        detected = data.detected || [];
-        renderSections();
-      } catch {}
-    }
-
-    // ── Project state panel ───────────────────────────────────────────────
-    function renderState(data) {
-      const stateRoot = data.root || '';
-      document.getElementById('rootPath').textContent = stateRoot;
-      activePeerTtl = Number(data.active_peer_ttl || activePeerTtl);
-      lastStateNow = Number(data.now || lastStateNow);
-      const state = document.getElementById('state');
-      const preserveScroll = lastStateRoot === stateRoot;
-        const savedStateScroll = preserveScroll ? state.scrollTop : 0;
-        const savedCardScroll = preserveScroll
-          ? new Map(
-            [...state.querySelectorAll('.state-card[data-section]')].map((card) => [
-              card.dataset.section,
-              {
-                top: card.querySelector('.body')?.scrollTop || 0,
-                pinned: bodyPinned(card.querySelector('.body'))
-              }
-            ])
-          )
-          : new Map();
-        const runtimeById = new Map();
-        for (const session of sessions || []) {
-          runtimeById.set(session.id, session);
-          const peerId = sessionPeerId(session);
-          if (peerId) runtimeById.set(peerId, session);
-        }
-	        const tasksData = data.tasks || [];
-	        const peersData = data.peers || [];
-	        const locksData = data.locks || [];
-	        const messagesData = data.messages || [];
-	        const timelineData = data.timeline || [];
-	        const automation = data.automation || {};
-	        const nextAction = automation.next_action || {};
-      const tasks = tasksData.map((t) => \`
-          <div class="item"><strong>#\${t.id} \${esc(t.title)}</strong><span>\${esc(statusText(t.status))} \${esc(tr('owner'))}=\${esc(t.owner || '')} \${esc(tr('assignee'))}=\${esc(t.assignee || '')}</span></div>
-        \`).join('') || '<div class="empty">' + esc(tr('noTasks')) + '</div>';
-        const peers = peersData.map((a) => {
-        const peerRuntime = runtimeById.get(a.id);
-        const peerState = peerStateView(a, peerRuntime, data.now);
-        return \`
-        <div class="item"><strong>\${esc(a.id)} <span class="badge">\${esc(a.kind)}</span> <span class="badge \${badgeClass(peerState.label)}">\${esc(statusText(peerState.label))}</span></strong><span>\${esc(peerState.detail)}</span></div>
-      \`;
-        }).join('') || '<div class="empty">' + esc(tr('noPeers')) + '</div>';
-		        const locks = locksData.map((l) => \`
-		          <div class="item"><strong>\${esc(l.resource)}</strong><span>\${esc(tr('owner'))}=\${esc(l.owner)} \${esc(tr('task'))}=\${l.task_id ? '#' + l.task_id : ''}</span></div>
-		        \`).join('') || '<div class="empty">' + esc(tr('noActiveLocks')) + '</div>';
-		        const messages = messagesData.map((m) => \`
-			          <div class="item"><strong>#\${m.id} \${esc(m.sender)} → \${esc(m.recipient || tr('all'))}\${m.reply_to ? ' ' + esc(tr('reply')) + ' #' + m.reply_to : ''}</strong><span>\${esc(m.body)}</span></div>
-			        \`).join('') || '<div class="empty">' + esc(tr('noMessages')) + '</div>';
-			        const timeline = timelineData.map(renderTimelineItem).join('') || '<div class="empty">' + esc(tr('noTimelineItems')) + '</div>';
-        const actionLines = [
-          '<div class="item"><strong>' + esc(statusText(automation.phase || 'idle')) + '</strong><span>' + esc(nextAction.reason || tr('noImmediateAction')) + '</span></div>',
-          nextAction.command ? '<div class="item"><strong>' + esc(tr('next')) + '</strong><span class="mono">' + esc(nextAction.command) + '</span></div>' : '',
-          (automation.finish_actions || []).length ? '<div class="item"><strong>' + esc(tr('finish')) + '</strong><span>' + esc(automation.finish_actions.map((a) => a.command).join(' | ')) + '</span></div>' : '',
-          (automation.warnings || []).length ? '<div class="item"><strong>' + esc(tr('warnings')) + '</strong><span>' + esc(automation.warnings.join(' | ')) + '</span></div>' : ''
-        ].filter(Boolean).join('');
-        state.innerHTML = \`
-		          <div class="card state-card" data-section="automation"><h2>\${esc(tr('nextAction'))} <span class="badge">\${esc(statusText(automation.phase || 'idle'))}</span></h2><div class="body">\${actionLines}</div></div>
-		          <div class="card state-card" data-section="timeline"><h2>\${esc(tr('timeline'))} <span class="badge">\${timelineData.length}</span></h2><div class="body">\${timeline}</div></div>
-		          <div class="card state-card" data-section="messages"><h2>\${esc(tr('messages'))} <span class="badge">\${messagesData.length}</span></h2><div class="body">\${messages}</div></div>
-		          <div class="card state-card" data-section="peers"><h2>\${esc(tr('peers'))} <span class="badge">\${peersData.length}</span></h2><div class="body">\${peers}</div></div>
-          <div class="card state-card" data-section="tasks"><h2>\${esc(tr('tasks'))} <span class="badge">\${tasksData.length}</span></h2><div class="body">\${tasks}</div></div>
-          <div class="card state-card" data-section="locks"><h2>\${esc(tr('locks'))} <span class="badge">\${locksData.length}</span></h2><div class="body">\${locks}</div></div>
-      \`;
-        state.scrollTop = savedStateScroll;
-        for (const [section, saved] of savedCardScroll) {
-          const body = state.querySelector('.state-card[data-section="' + section + '"] .body');
-          if (!body) continue;
-          if (section === 'timeline' && saved.pinned) body.scrollTop = body.scrollHeight;
-          else body.scrollTop = saved.top;
-        }
-        lastStateRoot = stateRoot;
-      }
-
-    async function refreshState() {
-      const peer = active ? managedPeerId(active) : null;
-      const p = peer ? '/api/state?peer=' + encodeURIComponent(peer) : '/api/state';
-      const data = await api(p);
-      renderState(data);
-    }
-
-      async function refreshDetectedState() {
-        if (!activeDetected) return;
-        const data = await api('/api/state?peer=' + encodeURIComponent(activeDetected));
-        renderState(data);
-      }
+function webPeerRegister(projectCtx, peer, input = {}) {
+  const db = connect(projectCtx);
+  const row = {
+    id: peer,
+    kind: input.kind || 'other',
+    role: input.role || 'peer',
+    worktree: path.resolve(input.worktree || projectCtx.cwd),
+    branch: input.branch || detectBranch(projectCtx.cwd),
+    pid: intOpt(input, 'pid', process.ppid),
+    status: input.status || 'idle',
+    capabilities: Array.isArray(input.cap) ? input.cap.join(',') : (input.cap || input.capabilities || 'web')
+  };
+  try {
+    upsertPeer(db, row);
+    addEvent(db, 'peer.registered', peer, null, { ...row, source: 'web' });
+  } finally {
+    db.close();
+  }
+  return { peer: row, summary: `registered ${row.id} (${row.kind}${row.role ? `, ${row.role}` : ''})` };
+}
 
-      async function refreshCurrentState() {
-        if (activeType === 'detected') return refreshDetectedState();
-        return refreshState();
-      }
+function webPeerHeartbeat(projectCtx, peer, input = {}) {
+  const ttl = intOpt(input, 'ttl', DEFAULT_LOCK_TTL);
+  const status = input.status || null;
+  const renewLocks = input['renew-locks'] !== false && input.renew_locks !== false;
+  const db = connect(projectCtx);
+  const t = now();
+  let renewed = 0;
+  try {
+    touchPeer(db, peer, status);
+    if (renewLocks) {
+      renewed = db.prepare(`
+        UPDATE locks SET expires_at = ?
+        WHERE owner = ? AND expires_at > ?
+      `).run(t + ttl, peer, t).changes;
+    }
+    addEvent(db, 'peer.heartbeat', peer, null, { status, renewed, source: 'web' });
+  } finally {
+    db.close();
+  }
+  return {
+    peer,
+    status,
+    renewed,
+    summary: `heartbeat ${peer}${renewed ? `, renewed locks: ${renewed}` : ''}`
+  };
+}
 
-    // ── Connect to managed (PTY) session ─────────────────────────────────
-    function connectManaged(id) {
-      const meta = sessions.find((s) => s.id === id);
-      const peerId = sessionPeerId(meta) || id;
-      active = id;
-      activeDetected = null;
-      activeType = 'managed';
-      renderSections();
-      document.getElementById('activeTitle').textContent = peerId;
-      document.getElementById('activeMeta').textContent = meta ? sessionMetaText(meta) : '';
-      document.getElementById('terminal').style.display = '';
-      document.getElementById('detectedPanel').style.display = 'none';
-      document.getElementById('quickBar').style.display = '';
-
-      if (ws) { clearTimeout(wsReconnectTimer); ws.close(); }
-      term.reset();
-      openWs(id);
-      refreshState().catch(console.error);
+function claimNextTasksForPeer(db, peer, { force = false, count = 1 } = {}) {
+  return tx(db, () => {
+    if (!force) {
+      const current = 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);
+      if (current) return { current: { ...current, current: true }, tasks: [] };
     }
+    const rows = db.prepare(`
+      SELECT * FROM tasks
+      WHERE status = 'pending'
+        AND owner IS NULL
+        AND (assignee IS NULL OR assignee = ?)
+      ORDER BY CASE WHEN assignee = ? THEN 0 ELSE 1 END, priority ASC, id ASC
+      LIMIT ?
+    `).all(peer, peer, count);
+    if (!rows.length) return { current: null, tasks: [] };
+    const t = now();
+    const claimed = [];
+    for (const row of rows) {
+      const changes = db.prepare(`
+        UPDATE tasks
+        SET owner = ?, status = 'claimed', claimed_at = ?, updated_at = ?
+        WHERE id = ? AND owner IS NULL AND status = 'pending'
+      `).run(peer, t, t, row.id).changes;
+      if (!changes) continue;
+      addEvent(db, 'task.claimed', peer, row.id, { next: true, count });
+      claimed.push(db.prepare('SELECT * FROM tasks WHERE id = ?').get(row.id));
+    }
+    return { current: null, tasks: claimed };
+  });
+}
 
-    function openWs(id) {
-      const proto = location.protocol === 'https:' ? 'wss' : 'ws';
-      ws = new WebSocket(proto + '://' + location.host + '/ws/terminal/' + encodeURIComponent(id) + requestQuery());
-      ws.onopen = () => {
-        resizeTerm();
-        connText('attached');
-      };
-      ws.onmessage = (event) => {
-        const msg = JSON.parse(event.data);
-        // Check before any reset whether the viewport is pinned at the bottom
-        const pinned = (() => {
-          try { const b = term.buffer.active; return b.viewportY >= b.baseY; } catch { return true; }
-        })();
-        // The server streams the tmux pane's raw output, so xterm renders
-        // incrementally (no reset/redraw → no flicker) and the program's own
-        // escape sequences carry the cursor.
-        if (msg.type === 'snapshot') { term.reset(); term.write(msg.data || '', () => { term.scrollToBottom(); }); }
-        if (msg.type === 'data') { term.write(msg.data || '', pinned ? () => { term.scrollToBottom(); } : undefined); }
-        if (msg.type === 'replace') { term.reset(); term.write(msg.data || '', pinned ? () => { term.scrollToBottom(); } : undefined); }
-        if (msg.type === 'exit') { refreshSessions().catch(console.error); }
-      };
-      ws.onclose = () => {
-        connText('reconnecting');
-        // Auto-reconnect if session is still in the list and running
-        wsReconnectTimer = setTimeout(() => {
-          const s = sessions.find((s) => s.id === id);
-          if (s && s.status === 'running' && active === id) openWs(id);
-          else connText('online');
-        }, 2000);
-      };
-    }
+function webPeerTaskNext(projectCtx, peer, input = {}) {
+  const db = connect(projectCtx);
+  try {
+    touchPeer(db, peer, 'working');
+    const count = positiveIntOpt(input, 'count', 1, { max: 50 });
+    const result = claimNextTasksForPeer(db, peer, { force: Boolean(input.force), count });
+    const task = result.current || result.tasks[0] || null;
+    if (!task) return { peer, task: null, tasks: [], summary: 'no pending task' };
+    return {
+      peer,
+      task,
+      tasks: result.tasks,
+      current: Boolean(result.current),
+      summary: result.current
+        ? `current task #${task.id}: ${task.title} (${task.status})`
+        : result.tasks.length === 1
+          ? `claimed task #${task.id}: ${task.title}`
+          : `claimed ${result.tasks.length} tasks`
+    };
+  } finally {
+    db.close();
+  }
+}
 
-    // ── Connect to detected (coordination-only) peer ──────────────────────
-    function connectDetected(id) {
-      const peer = detected.find((p) => p.id === id);
-      active = null;
-      activeDetected = id;
-      activeType = 'detected';
-      if (ws) { clearTimeout(wsReconnectTimer); ws.close(); ws = null; }
-      renderSections();
-      document.getElementById('activeTitle').textContent = id + ' (' + tr('detected') + ')';
-      document.getElementById('activeMeta').textContent = peer ? peer.kind + ' · ' + (peer.worktree || '') : '';
-      document.getElementById('terminal').style.display = 'none';
-      document.getElementById('detectedPanel').style.display = '';
-      document.getElementById('quickBar').style.display = 'none';
-      connText('coordinationOnly');
-      renderDetectedPanel(peer || { id });
-      refreshDetectedState().catch(console.error);
-    }
+function webPeerTaskTakeover(projectCtx, peer, input = {}) {
+  const id = intOpt(input, 'id', intOpt({ id: input.task }, 'id'));
+  if (!id) throw new CliError('BAD_REQUEST', 'task id required');
+  const reason = required(input, 'reason');
+  const policy = input.policy || 'any';
+  const staleAfter = positiveIntOpt(input, 'stale-after', intOpt(input, 'stale_after', ACTIVE_PEER_TTL), { max: 86400 * 30 });
+  const db = connect(projectCtx);
+  try {
+    touchPeer(db, peer, 'working');
+    const task = takeOverTaskForPeer(db, peer, id, { reason, policy, staleAfter, source: 'web' });
+    return { peer, task, summary: `took over task #${task.id}: ${task.title}` };
+  } finally {
+    db.close();
+  }
+}
 
-    function renderDetectedPanel(peer) {
-      const dp = document.getElementById('detectedPanel');
-      dp.innerHTML = \`
-        <div style="padding:16px;display:grid;gap:12px">
-          <div class="card">
-            <h2>\${esc(tr('detectedSession'))}</h2>
-            <div class="body">
-              <div class="item"><strong>\${esc(tr('peer'))}</strong><span class="mono">\${esc(peer.id)}</span></div>
-              <div class="item"><strong>\${esc(tr('kind'))}</strong><span>\${esc(peer.kind || '')}</span></div>
-              <div class="item"><strong>\${esc(tr('status'))}</strong><span>\${esc(peer.status || '')}</span></div>
-              <div class="item"><strong>\${esc(tr('cwd'))}</strong><span class="mono" style="font-size:11px">\${esc(peer.worktree || '')}</span></div>
-              <div class="item"><strong>\${esc(tr('pid'))}</strong><span>\${esc(peer.pid || tr('unknown'))}</span></div>
-              <div class="item"><strong>\${esc(tr('lastSeen'))}</strong><span>\${peer.age_sec != null ? esc(peer.age_sec + tr('secondsAgo')) : ''}</span></div>
-            </div>
-          </div>
-          <div class="card">
-            <h2>\${esc(tr('sendMessage'))}</h2>
-            <div class="body" style="gap:8px">
-              <div style="font-size:12px;color:var(--muted)">\${tr('messageHelp')}</div>
-              <textarea id="detMsg" rows="3" style="width:100%;background:#0d0f12;border:1px solid var(--border);color:var(--text);border-radius:6px;padding:8px;font:inherit;resize:vertical" placeholder="\${esc(tr('messageBodyPlaceholder'))}"></textarea>
-              <button class="primary" id="sendDetMsg">\${esc(tr('send'))}</button>
-            </div>
-          </div>
-        </div>
-      \`;
-      document.getElementById('sendDetMsg').addEventListener('click', async () => {
-        const body = document.getElementById('detMsg').value.trim();
-        if (!body) return;
-        await api('/api/detected/' + encodeURIComponent(peer.id) + '/msg', {
-          method: 'POST',
-          body: JSON.stringify({ body, from: 'web' })
-          });
-          document.getElementById('detMsg').value = '';
-          await refreshDetectedState();
+function webPeerLockAcquire(projectCtx, peer, input = {}) {
+  const requested = scopedLockResource(required(input, 'resource'), input.scope);
+  const ttl = intOpt(input, 'ttl', DEFAULT_LOCK_TTL);
+  const taskId = intOpt(input, 'task', intOpt(input, 'task_id', null));
+  const reason = input.reason || '';
+  const db = connect(projectCtx);
+  try {
+    touchPeer(db, peer, 'working');
+    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)
         });
       }
-
-    // ── Helpers ───────────────────────────────────────────────────────────
-    function sendLine(text) {
-      if (!active || !ws || ws.readyState !== WebSocket.OPEN) return;
-      ws.send(JSON.stringify({ type: 'input', data: text + '\\r' }));
-    }
-
-    // ── Start session form ────────────────────────────────────────────────
-    document.getElementById('kind').addEventListener('change', syncStartModeOptions);
-    document.getElementById('startMode').addEventListener('change', syncStartModeOptions);
-    document.getElementById('resumeSelect').addEventListener('change', toggleResumeCustom);
-    syncStartModeOptions();
-
-    document.getElementById('startForm').addEventListener('submit', async (event) => {
-      event.preventDefault();
-      const kind = document.getElementById('kind').value;
-      const mode = document.getElementById('startMode').value;
-      const sel = document.getElementById('resumeSelect');
-      const resume = (sel.value && sel.value !== '__custom__')
-        ? sel.value
-        : document.getElementById('resumeArg').value.trim();
-      if (mode === 'resume' && !resume) return;
-      const payload = { kind, mode };
-      if (mode === 'resume') payload.resume = resume;
-      const data = await api('/api/sessions', { method: 'POST', body: JSON.stringify(payload) });
-      await refreshSessions();
-      connectManaged(data.session.id);
-    });
-
-    document.querySelectorAll('[data-send]').forEach((button) => {
-      button.addEventListener('click', () => {
-        if (!active) return;
-        const session = sessions.find((s) => s.id === active) || { kind: 'other', role: 'peer' };
-        const peerId = sessionPeerId(session) || active;
-        const lines = {
-          register: \`hcc register --peer \${peerId} --kind \${session.kind || 'other'} --role \${session.role || 'peer'}\`,
-          inbox:    \`hcc msg inbox --peer \${peerId}\`,
-          next:     \`hcc task next --peer \${peerId}\`,
-          status:   \`hcc status --peer \${peerId}\`,
-          heartbeat:\`hcc heartbeat --peer \${peerId} --renew-locks\`
-        };
-        sendLine(lines[button.dataset.send]);
-        closeActionsMenu();
-      });
+      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, source: 'web' });
+      return db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
     });
+    return { peer, lock, summary: `locked ${lockLabel(lock)} by ${lock.owner} until ${iso(lock.expires_at)}` };
+  } finally {
+    db.close();
+  }
+}
 
-    // ── Actions dropdown (declutters the toolbar) ─────────────────────────
-    const actionsBtn = document.getElementById('actionsBtn');
-    const actionsMenu = document.getElementById('actionsMenu');
-    function closeActionsMenu() {
-      actionsMenu.hidden = true;
-      actionsBtn.setAttribute('aria-expanded', 'false');
-    }
-    actionsBtn.addEventListener('click', (e) => {
-      e.stopPropagation();
-      const open = actionsMenu.hidden;
-      actionsMenu.hidden = !open;
-      actionsBtn.setAttribute('aria-expanded', String(open));
-      if (open) {
-        // Position as a fixed layer so it escapes the toolbar/main overflow clip.
-        const r = actionsBtn.getBoundingClientRect();
-        actionsMenu.style.top = (r.bottom + 6) + 'px';
-        actionsMenu.style.left = Math.max(8, r.right - actionsMenu.offsetWidth) + 'px';
-      }
-    });
-    document.addEventListener('click', (e) => {
-      if (!actionsMenu.hidden && !e.target.closest('.menu-wrap')) closeActionsMenu();
-    });
-    document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closeActionsMenu(); });
-
-    // ── Collapsible side panels ───────────────────────────────────────────
-    const appEl = document.querySelector('.app');
-    const toggleLeftBtn = document.getElementById('toggleLeft');
-    const toggleRightBtn = document.getElementById('toggleRight');
-    const resizeLeftHandle = document.getElementById('resizeLeft');
-    const resizeRightHandle = document.getElementById('resizeRight');
-    const sideDefaults = { left: 320, right: 360 };
-    const sideMin = { left: 220, right: 240 };
-    const sideMax = { left: 560, right: 640 };
-    const sideWidthKey = { left: 'hcc.sidebar.left.width', right: 'hcc.sidebar.right.width' };
-    const dragState = { side: null, startX: 0, startWidth: 0, moved: false, suppressClick: false };
-    function sideIsCollapsed(side) {
-      return appEl.classList.contains(side + '-collapsed') || localStorage.getItem('hcc.collapse.' + side) === '1';
-    }
-    function storedSideWidth(side) {
-      const raw = Number(localStorage.getItem(sideWidthKey[side]));
-      return Number.isFinite(raw) && raw > 0 ? raw : sideDefaults[side];
-    }
-    function effectiveOppositeWidth(side) {
-      const opposite = side === 'left' ? 'right' : 'left';
-      return sideIsCollapsed(opposite) ? 0 : storedSideWidth(opposite);
-    }
-    function clampSideWidth(side, width) {
-      const viewport = Math.max(640, window.innerWidth || appEl.clientWidth || 0);
-      const opposite = effectiveOppositeWidth(side);
-      const maxByViewport = Math.max(sideMin[side], viewport - opposite - 280);
-      return Math.max(sideMin[side], Math.min(sideMax[side], maxByViewport, Math.round(width)));
-    }
-    function readSideWidth(side) {
-      return clampSideWidth(side, storedSideWidth(side));
-    }
-    function setSideWidth(side, width, persist = true) {
-      const value = clampSideWidth(side, width);
-      appEl.style.setProperty('--' + side + '-width', value + 'px');
-      if (persist) localStorage.setItem(sideWidthKey[side], String(value));
-      return value;
-    }
-    function applySideWidths() {
-      setSideWidth('left', readSideWidth('left'), false);
-      setSideWidth('right', readSideWidth('right'), false);
-    }
-    function syncToggleIcons() {
-      const l = appEl.classList.contains('left-collapsed');
-      const r = appEl.classList.contains('right-collapsed');
-      toggleLeftBtn.textContent = l ? '⟩' : '⟨';
-      toggleLeftBtn.title = (l ? tr('show') : tr('collapse')) + ' ' + tr('sidebar') + '; ' + tr('dragToResize');
-      toggleRightBtn.textContent = r ? '⟨' : '⟩';
-      toggleRightBtn.title = (r ? tr('show') : tr('collapse')) + ' ' + tr('statePanel') + '; ' + tr('dragToResize');
-    }
-    function applyCollapseState() {
-      appEl.classList.toggle('left-collapsed', localStorage.getItem('hcc.collapse.left') === '1');
-      appEl.classList.toggle('right-collapsed', localStorage.getItem('hcc.collapse.right') === '1');
-      applySideWidths();
-      syncToggleIcons();
-    }
-    function toggleSide(side) {
-      const cls = side + '-collapsed';
-      const on = appEl.classList.toggle(cls);
-      localStorage.setItem('hcc.collapse.' + side, on ? '1' : '0');
-      applySideWidths();
-      syncToggleIcons();
-      // Refit the terminal after the grid transition so xterm uses the new width.
-      setTimeout(() => { try { resizeTerm(); } catch {} }, 200);
-    }
-    function beginSideDrag(side, event) {
-      if (event.button !== undefined && event.button !== 0) return;
-      dragState.side = side;
-      dragState.startX = event.clientX;
-      dragState.startWidth = readSideWidth(side);
-      dragState.moved = false;
-      dragState.suppressClick = false;
-      appEl.classList.add('resizing');
-      event.currentTarget.setPointerCapture?.(event.pointerId);
-      event.preventDefault();
-    }
-    function moveSideDrag(event) {
-      if (!dragState.side) return;
-      const delta = event.clientX - dragState.startX;
-      if (!dragState.moved && Math.abs(delta) <= 3) return;
-      dragState.moved = true;
-      const width = dragState.side === 'left'
-        ? dragState.startWidth + delta
-        : dragState.startWidth - delta;
-      setSideWidth(dragState.side, width);
-      if (dragState.side === 'left') {
-        appEl.classList.remove('left-collapsed');
-        localStorage.setItem('hcc.collapse.left', '0');
-      } else {
-        appEl.classList.remove('right-collapsed');
-        localStorage.setItem('hcc.collapse.right', '0');
+function webPeerLockRelease(projectCtx, peer, input = {}) {
+  const requested = scopedLockResource(required(input, 'resource'), input.scope);
+  const force = Boolean(input.force);
+  const db = connect(projectCtx);
+  try {
+    touchPeer(db, peer, null);
+    const result = tx(db, () => {
+      const existing = db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource);
+      if (!existing) return { released: false, ...requested };
+      if (existing.owner !== peer && !force) {
+        throw new CliError('LOCK_OWNED', `Lock is owned by ${existing.owner}`, { owner: existing.owner });
       }
-      syncToggleIcons();
-      try { resizeTerm(); } catch {}
-      event.preventDefault();
-    }
-    function endSideDrag(event) {
-      if (!dragState.side) return;
-      dragState.suppressClick = dragState.moved;
-      event.currentTarget.releasePointerCapture?.(event.pointerId);
-      dragState.side = null;
-      appEl.classList.remove('resizing');
-      setTimeout(() => { dragState.suppressClick = false; }, 0);
-      try { resizeTerm(); } catch {}
-    }
-    function bindSideHandle(handle, side, clickAction = null) {
-      handle.addEventListener('pointerdown', (event) => beginSideDrag(side, event));
-      handle.addEventListener('pointermove', moveSideDrag);
-      handle.addEventListener('pointerup', endSideDrag);
-      handle.addEventListener('pointercancel', endSideDrag);
-      handle.addEventListener('click', (event) => {
-        if (dragState.suppressClick) {
-          event.preventDefault();
-          return;
-        }
-        if (clickAction) clickAction(side);
-      });
-    }
-    bindSideHandle(resizeLeftHandle, 'left');
-    bindSideHandle(resizeRightHandle, 'right');
-    bindSideHandle(toggleLeftBtn, 'left', toggleSide);
-    bindSideHandle(toggleRightBtn, 'right', toggleSide);
-    window.addEventListener('resize', () => {
-      applySideWidths();
-      setTimeout(() => { try { resizeTerm(); } catch {} }, 50);
+      db.prepare('DELETE FROM locks WHERE resource = ?').run(requested.resource);
+      addEvent(db, 'lock.released', peer, existing.task_id || null, { resource: requested.base_resource, lock_resource: requested.resource, scope: requested.scope, force, source: 'web' });
+      return { released: true, ...requested };
     });
-    applyCollapseState();
+    return { peer, result, summary: result.released ? `released ${lockLabel(result)}` : `no lock for ${lockLabel(result)}` };
+  } finally {
+    db.close();
+  }
+}
 
-    document.getElementById('stopBtn').addEventListener('click', async () => {
-      if (!active) return;
-      await api('/api/sessions/' + encodeURIComponent(active) + '/stop', { method: 'POST', body: '{}' });
-      await refreshSessions();
-    });
-      document.getElementById('refreshBtn').addEventListener('click', () => {
-        Promise.all([refreshSessions(), refreshDetected(), refreshCurrentState()]).catch(console.error);
-      });
+function webPeerInbox(projectCtx, peer, input = {}) {
+  const db = connect(projectCtx);
+  try {
+    const messages = queryInbox(db, peer, Boolean(input.all), intOpt(input, 'limit', 20));
+    return {
+      peer,
+      messages,
+      summary: messages.length ? `${messages.length} message${messages.length === 1 ? '' : 's'}` : 'no messages'
+    };
+  } finally {
+    db.close();
+  }
+}
 
-    applyLanguage();
-    loadProjects().then(() => Promise.all([refreshSessions(), refreshDetected(), refreshState()])).then(() => {
-      // Auto-connect to first running managed session on load
-      if (!active && !activeDetected) {
-        const first = sessions.find(s => s.status === 'running');
-        if (first) connectManaged(first.id);
-      }
-    }).catch((err) => {
-      connText('error');
-      console.error(err);
+function webPeerAction(projectCtx, peer, action, input = {}) {
+  const normalized = String(action || '').replace(/_/g, '-');
+  if (!peer) throw new CliError('BAD_REQUEST', 'peer required');
+  if (normalized === 'status') {
+    const status = statusSummary(projectCtx, peer);
+    return { ok: true, action: normalized, peer, summary: `active=${status.active_peers}, stale=${status.stale_peers}, locks=${status.active_locks}, unread=${status.unread ?? 0}`, data: status };
+  }
+  if (normalized === 'state') {
+    const data = statusSnapshot(projectCtx, peer, {
+      resources: normalizeStateResources(input.resource || input.resources || []),
+      intent: input.intent || null,
+      scope: input.scope || null
     });
-    // ── Auto-poll state ──────────────────────────────────────────────────
-    setInterval(() => {
-      refreshSessions().catch(console.error);
-      refreshDetected().catch(console.error);
-      if (activeType === 'detected') refreshDetectedState().catch(console.error);
-      else if (active) refreshState().catch(console.error);
-    }, 3000);
-    setInterval(() => {
-      loadProjects().catch(console.error);
-    }, 8000);
-  </script>
-</body>
-</html>`;
+    return { ok: true, action: normalized, peer, summary: data.automation?.next_action?.reason || 'state loaded', data };
+  }
+  if (normalized === 'inbox') {
+    const data = webPeerInbox(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  if (normalized === 'task-next') {
+    const data = webPeerTaskNext(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  if (normalized === 'task-takeover') {
+    const data = webPeerTaskTakeover(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  if (normalized === 'lock-acquire') {
+    const data = webPeerLockAcquire(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  if (normalized === 'lock-release') {
+    const data = webPeerLockRelease(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  if (normalized === 'heartbeat') {
+    const data = webPeerHeartbeat(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  if (normalized === 'register') {
+    const data = webPeerRegister(projectCtx, peer, input);
+    return { ok: true, action: normalized, peer, summary: data.summary, data };
+  }
+  throw new CliError('BAD_REQUEST', `Unknown peer action: ${action}`);
 }
 
 async function cmdWeb(ctx, args, startMeta = {}) {
@@ -6413,6 +4732,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     if (session.replaceTimer) clearTimeout(session.replaceTimer);
     session.replaceTimer = setTimeout(() => {
       session.replaceTimer = null;
+      session.lastBroadcastTime = Date.now();
       broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
     }, 80);
   }
@@ -6426,6 +4746,10 @@ async function cmdWeb(ctx, args, startMeta = {}) {
     const safeId = String(session.id).replace(/[^A-Za-z0-9_.-]/g, '_');
     const pipeFile = path.join(bufsDir, `tmux-${safePane}-${safeId}.pipe`);
     session.pipeFile = pipeFile;
+    // Restored panes may still have pipe-pane writers from a previous runtime.
+    // Disable first so tmux tears down the stale writer before this runtime
+    // installs its own FIFO reader.
+    try { runTmux(['pipe-pane', '-t', session.pane]); } catch {}
     // Capture the existing screen once for the initial paint; pipe-pane only
     // forwards output produced after it is enabled.
     try {
@@ -6481,6 +4805,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         const data = Buffer.concat(chunks).toString();
         session.buffer += data;
         if (session.buffer.length > 250000) session.buffer = session.buffer.slice(-200000);
+        session.lastBroadcastTime = Date.now();
         broadcast(session, { type: 'data', data });
       } catch {
         if (session.streamFd !== null && session.streamFd !== undefined) {
@@ -6489,11 +4814,26 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         }
       }
     }, 40);
+
+    // Fallback replace poller: if the FIFO produces no data for N seconds
+    // (e.g. pipe-pane output is fully buffered), send a fresh capture-pane
+    // snapshot so the browser stays current. This also recovers from any
+    // silent FIFO-read failures on restored panes.
+    session.lastBroadcastTime = Date.now();
+    session.replacePoller = setInterval(() => {
+      if (session.status !== 'running') return;
+      if (Date.now() - (session.lastBroadcastTime || 0) > 4000) {
+        session.lastBroadcastTime = Date.now();
+        broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
+      }
+    }, 1600);
   }
 
   function stopTmuxStream(session) {
     if (session.streamPoller) { clearInterval(session.streamPoller); session.streamPoller = null; }
+    if (session.replacePoller) { clearInterval(session.replacePoller); session.replacePoller = null; }
     if (session.replaceTimer) { clearTimeout(session.replaceTimer); session.replaceTimer = null; }
+    if (session.inputRefreshTimer) { clearTimeout(session.inputRefreshTimer); session.inputRefreshTimer = null; }
     // Turn piping back off for this pane (no command toggles it off).
     try { runTmux(['pipe-pane', '-t', session.pane]); } catch {}
     if (session.streamFd !== null && session.streamFd !== undefined) {
@@ -6555,6 +4895,8 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       streamPoller: null,
       streamFd: null,
       pipeFile: null,
+      replacePoller: null,
+      lastBroadcastTime: 0,
       exitPoller: null
     };
     sessions.set(key, session);
@@ -6612,11 +4954,21 @@ async function cmdWeb(ctx, args, startMeta = {}) {
       try { fs.appendFileSync(session.inFile, data); } catch {}
     } else if (session.type === 'tmux') {
       tmuxSendLiteral(session.pane, data);
+      scheduleTmuxInputRefresh(session);
     } else {
       session.pty.write(data);
     }
   }
 
+  function scheduleTmuxInputRefresh(session) {
+    if (session.type !== 'tmux' || !session.pane) return;
+    if (session.inputRefreshTimer) return;
+    session.inputRefreshTimer = setTimeout(() => {
+      session.inputRefreshTimer = null;
+      if (session.status === 'running') broadcast(session, { type: 'replace', data: refreshTmuxSnapshot(session) });
+    }, 80);
+  }
+
   function resizeSession(session, cols, rows) {
     if (session.type === 'external') {
       try { fs.appendFileSync(session.resizeFile, JSON.stringify({ cols, rows }) + '\n'); } catch {}
@@ -6935,7 +5287,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   }
 
   const server = http.createServer(async (req, res) => {
-    const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+    const url = requestUrl(req);
     try {
       if (req.method === 'GET' && url.pathname === '/') {
         sendHttp(res, 200, 'text/html; charset=utf-8', webIndexHtml());
@@ -6986,10 +5338,33 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         ]);
         sendJson(res, 200, statusSnapshot(reqCtx, url.searchParams.get('peer'), {
           resources,
-          intent: url.searchParams.get('intent') || null
+          intent: url.searchParams.get('intent') || null,
+          scope: url.searchParams.get('scope') || null
         }));
         return;
       }
+      const peerActionMatch = url.pathname.match(/^\/api\/peers\/([^/]+)\/actions\/([^/]+)$/);
+      if (peerActionMatch) {
+        const peer = decodeURIComponent(peerActionMatch[1]);
+        const action = decodeURIComponent(peerActionMatch[2]);
+        const readOnly = ['status', 'state', 'inbox'].includes(action);
+        if (readOnly && req.method !== 'GET') {
+          sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: 'Use GET for read-only peer actions' } });
+          return;
+        }
+        if (!readOnly && req.method !== 'POST') {
+          sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: 'Use POST for mutating peer actions' } });
+          return;
+        }
+        const input = readOnly
+          ? {
+              ...Object.fromEntries(url.searchParams.entries()),
+              resource: url.searchParams.getAll('resource')
+            }
+          : await readJsonRequest(req);
+        sendJson(res, 200, webPeerAction(reqCtx, peer, action, input));
+        return;
+      }
       // Detected sessions: peers registered via hooks/watcher but without PTY
       if (req.method === 'GET' && url.pathname === '/api/detected') {
         const db = connect(reqCtx);
@@ -7150,7 +5525,17 @@ 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 {}
             detachTmuxSession(session, 'detached');
+            if (input.kill_tmux) {
+              try {
+                const sessName = runTmux(['display-message', '-p', '-t', session.pane, '#{session_name}']).trim();
+                if (sessName) tmuxKillSession(sessName);
+              } catch {
+                // Pane or session already gone; no fallback needed.
+              }
+            }
           } else {
             session.pty.kill();
           }
@@ -7177,6 +5562,46 @@ async function cmdWeb(ctx, args, startMeta = {}) {
         sendJson(res, 200, { ok: true, id: msgId });
         return;
       }
+      const detectedStopMatch = url.pathname.match(/^\/api\/detected\/([^/]+)\/stop$/);
+      if (req.method === 'POST' && detectedStopMatch) {
+        const peerId = decodeURIComponent(detectedStopMatch[1]);
+        let input = {};
+        try { input = await readJsonRequest(req); } catch {}
+        const db = connect(reqCtx);
+        try {
+          const now_ = now();
+          db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now_, peerId);
+          const binding = db.prepare('SELECT * FROM peer_bindings WHERE peer = ?').get(peerId);
+          if (binding && input.kill_tmux && binding.runtime_target) {
+            try {
+              const sessName = runTmux(['display-message', '-p', '-t', binding.runtime_target, '#{session_name}']).trim();
+              if (sessName) tmuxKillSession(sessName);
+            } catch {
+              // Session already gone.
+            }
+          }
+          db.prepare('UPDATE peer_bindings SET runtime_target = NULL, updated_at = ? WHERE peer = ?').run(now_, peerId);
+          addEvent(db, 'peer.stopped', 'web', null, { peer: peerId });
+        } finally {
+          db.close();
+        }
+        sendJson(res, 200, { ok: true, peer: peerId, status: 'exited' });
+        return;
+      }
+      const detectedRestartMatch = url.pathname.match(/^\/api\/detected\/([^/]+)\/restart$/);
+      if (req.method === 'POST' && detectedRestartMatch) {
+        const peerId = decodeURIComponent(detectedRestartMatch[1]);
+        const db = connect(reqCtx);
+        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 });
+        } finally {
+          db.close();
+        }
+        sendJson(res, 200, { ok: true, peer: peerId, status: 'running' });
+        return;
+      }
       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';
@@ -7186,7 +5611,7 @@ async function cmdWeb(ctx, args, startMeta = {}) {
 
   const wss = new WebSocketServer({ noServer: true });
   server.on('upgrade', (req, socket, head) => {
-    const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+    const url = requestUrl(req);
     if (!authOk(url, req, token)) {
       socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
       socket.destroy();
@@ -7287,12 +5712,10 @@ async function cmdWeb(ctx, args, startMeta = {}) {
   } finally {
     db.close();
   }
-  const shownHost = host === '0.0.0.0' ? '<machine-ip>' : host;
-  const url = `http://${shownHost}:${actualPort}/${runtimeUrlQuery(runtime, ctx.root)}`;
   console.log(`${PRODUCT_NAME} web listening on ${host}:${actualPort}`);
   console.log(`project: ${ctx.root}`);
   console.log(`database: ${ctx.dbPath}`);
-  console.log(`open: ${url}`);
+  console.log(`open: ${publicRuntimeUrl(runtime, ctx.root)}`);
 }
 
 async function cmdRun(ctx, args) {
@@ -7571,8 +5994,9 @@ Usage:
   ${CLI_NAME} task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
   ${CLI_NAME} task create --title TEXT --parent N [--team-role ROLE]
   ${CLI_NAME} task list [--status pending|claimed|running|review|blocked|done|abandoned] [--peer ID] [--all]
-  ${CLI_NAME} task claim [--peer ID] --id N
-  ${CLI_NAME} task next [--peer ID] [--force]
+  ${CLI_NAME} task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
+  ${CLI_NAME} task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--stale-after SECONDS]
+  ${CLI_NAME} task next [--peer ID] [--force] [--count N]
   ${CLI_NAME} task update [--peer ID] --id N --status STATUS [--summary TEXT] [--body TEXT] [--to ID]
   ${CLI_NAME} task done [--peer ID] --id N --summary TEXT
 
@@ -7580,8 +6004,13 @@ Default task list shows all project tasks that are not done or abandoned.
 --peer is an explicit filter; HCC_PEER does not hide other open tasks.
 Messages use per-peer unread ack state; tasks do not.
 task next returns your existing claimed/running/review/blocked task before
-claiming another pending task. Use --force only when intentionally taking
-another pending task.
+claiming another pending task. Use --force when intentionally taking additional
+pending tasks; combine it with --count N for explicit batch claims.
+Use task takeover when explicitly taking over a non-complete task from another
+owner; it records the previous owner, requires a reason, and notifies them.
+Use --policy blocked, stale, or blocked-or-stale to require an auditable
+precondition before takeover. The default policy is any for backward
+compatibility.
 
 If --peer/--from and HCC_PEER are absent, hcc auto-joins the current terminal
 as a stable project-local peer.
@@ -7607,7 +6036,7 @@ function helpState() {
   console.log(`${CLI_NAME} state
 
 Usage:
-  ${CLI_NAME} state [--peer ID] [--resource PATH] [--intent work|stop|finish]
+  ${CLI_NAME} state [--peer ID] [--resource PATH] [--scope SCOPE] [--intent read|review|work|write|stop|finish]
 
 Shows the current collaboration timeline plus a machine-readable coordination
 state machine. With --json, the response includes automation.next_action.argv so
@@ -7616,6 +6045,9 @@ automation.current_task shows the peer's active claimed/running/review/blocked
 task when one exists.
 If a current task looks splittable, automation may suggest hcc team plan; this
 is read-only until hcc team start is run explicitly.
+With --intent read or --intent review, state treats resources as snapshot
+inspection and does not suggest acquiring file locks. With write/work intents,
+--scope lets agents coordinate independent regions of the same resource.
 
 State does not execute coordination actions: it does not ack messages, claim
 tasks, acquire locks, send messages, create handoffs, or mark tasks done. Opening
@@ -7745,10 +6177,13 @@ function helpLock() {
   console.log(`${CLI_NAME} lock
 
 Usage:
-  ${CLI_NAME} lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
-  ${CLI_NAME} lock renew [--peer ID] --resource PATH [--ttl SEC]
-  ${CLI_NAME} lock release [--peer ID] --resource PATH [--force]
+  ${CLI_NAME} lock acquire [--peer ID] --resource PATH [--scope SCOPE] [--task N] [--ttl SEC] [--reason TEXT]
+  ${CLI_NAME} lock renew [--peer ID] --resource PATH [--scope SCOPE] [--ttl SEC]
+  ${CLI_NAME} lock release [--peer ID] --resource PATH [--scope SCOPE] [--force]
   ${CLI_NAME} lock list [--all]
+
+Omit --scope to lock the whole resource. Different scopes on the same resource
+can be held concurrently, but a whole-resource lock conflicts with every scope.
 `);
 }