@logicseek/hello-cc 0.1.4 → 0.1.5

package/docs/commands.md

@@ -36,7 +36,7 @@ want coordination without the Web console or shims.
 ```text
 hcc peers
 hcc status [--peer ID]
-hcc state [--peer ID] [--resource PATH] [--intent work|stop|finish]
+hcc state [--peer ID] [--resource PATH] [--scope SCOPE] [--intent read|review|work|write|stop|finish]
 hcc scan [--register]
 hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
 hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
@@ -51,7 +51,9 @@ coordination actions such as acking messages, claiming tasks, acquiring locks, o
 creating handoffs. It adds a unified collaboration timeline plus
 `automation.next_action.argv`, a machine-readable next coordination command for
 agents to execute explicitly. `automation.current_task` records the peer's active
-task when one exists.
+task when one exists. Use `--intent read` or `--intent review` for snapshot
+inspection that should not acquire locks; use `--scope` with write/work intents
+to coordinate one region of a larger shared resource.
 
 ## Browser-Controllable Terminals
 
@@ -92,8 +94,9 @@ sender by default. Use `msg thread` to inspect the full thread for one message.
 ```text
 hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
 hcc task list [--status S] [--peer ID] [--all]
-hcc task claim [--peer ID] --id N
-hcc task next [--peer ID] [--force]
+hcc task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
+hcc task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--stale-after SECONDS]
+hcc task next [--peer ID] [--force] [--count N]
 hcc task create --title TEXT --parent N [--team-role ROLE]
 hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
 hcc task done [--peer ID] --id N --summary TEXT
@@ -102,7 +105,13 @@ hcc task done [--peer ID] --id N --summary TEXT
 Tasks are shared project facts. They remain visible until marked `done` or
 `abandoned`. `task next` returns your existing claimed/running/review/blocked
 task before claiming a new pending task; use `--force` only when intentionally
-taking another pending task.
+taking additional pending tasks, and combine it with `--count N` for explicit
+batch claims. `task claim` also accepts repeated `--id` values and comma-separated
+`--id` or `--ids` lists. Use `task takeover` when explicitly taking a
+non-complete task from another owner; it records the previous owner, requires a
+reason, and notifies them. Add `--policy blocked`, `stale`, or `blocked-or-stale`
+when takeover should only proceed under that auditable precondition. The default
+policy is `any` for compatibility.
 
 ## Teams
 
@@ -121,9 +130,9 @@ explicit peer IDs or kind counts such as `codex:2,claude:1`.
 ## Locks, Handoffs, And Events
 
 ```text
-hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
-hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
-hcc lock release [--peer ID] --resource PATH [--force]
+hcc lock acquire [--peer ID] --resource PATH [--scope SCOPE] [--task N] [--ttl SEC] [--reason TEXT]
+hcc lock renew [--peer ID] --resource PATH [--scope SCOPE] [--ttl SEC]
+hcc lock release [--peer ID] --resource PATH [--scope SCOPE] [--force]
 hcc lock list [--all]
 hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
 hcc handoff list [--task N] [--limit N]
@@ -131,5 +140,8 @@ hcc event tail [--limit N]
 hcc gc [--older-than DAYS] [--yes]
 ```
 
-Locks are advisory coordination locks with TTLs. Handoffs preserve the result,
+Locks are advisory coordination locks with TTLs. Omitting `--scope` locks the
+whole resource. Different scopes on the same resource can be held concurrently,
+for example `--resource bin/hcc.mjs --scope db-schema` and `--scope web-ui`, but
+a whole-resource lock conflicts with every scope. Handoffs preserve the result,
 tests, changed files, and remaining risks when work moves between peers.

package/docs/commands.zh-CN.md

@@ -33,7 +33,7 @@ URL token；首次使用时自动生成并保存。用 `--local` 可只绑定 `1
 ```text
 hcc peers
 hcc status [--peer ID]
-hcc state [--peer ID] [--resource PATH] [--intent work|stop|finish]
+hcc state [--peer ID] [--resource PATH] [--scope SCOPE] [--intent read|review|work|write|stop|finish]
 hcc scan [--register]
 hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
 hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
@@ -47,6 +47,8 @@ hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
 创建 handoff 这类协作动作；它会返回统一协作时间线，以及
 `automation.next_action.argv` 这种机器可读的下一步协作命令，供 agent 显式执行
 并留下审计记录。`automation.current_task` 会记录当前 peer 已经拥有的活动任务。
+使用 `--intent read` 或 `--intent review` 表示只做快照检查，不应获取文件锁；
+写入/工作意图下可用 `--scope` 协调同一个大资源中的某个区域。
 
 ## Web 可控终端
 
@@ -85,8 +87,9 @@ hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
 ```text
 hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
 hcc task list [--status S] [--peer ID] [--all]
-hcc task claim [--peer ID] --id N
-hcc task next [--peer ID] [--force]
+hcc task claim [--peer ID] --id N[,N] [--id N] [--ids N,N] [--force]
+hcc task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|blocked-or-stale] [--stale-after SECONDS]
+hcc task next [--peer ID] [--force] [--count N]
 hcc task create --title TEXT --parent N [--team-role ROLE]
 hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
 hcc task done [--peer ID] --id N --summary TEXT
@@ -94,7 +97,12 @@ hcc task done [--peer ID] --id N --summary TEXT
 
 任务是项目共享事实。任务会一直可见，直到被标记为 `done` 或 `abandoned`。
 `task next` 会优先返回当前 peer 已经认领、运行、审查或阻塞中的任务；只有明确
-要再接一个 pending 任务时才使用 `--force`。
+要再接 pending 任务时才使用 `--force`，并可结合 `--count N` 做显式批量认领。
+`task claim` 也支持重复 `--id`、逗号分隔的 `--id` 或 `--ids` 列表。明确要从
+其他 owner 手里接管未完成任务时，使用 `task takeover`；它要求填写 reason，会
+记录原 owner 并通知对方。需要更保守时，可加 `--policy blocked`、`stale` 或
+`blocked-or-stale`，要求任务符合可审计的阻塞/陈旧条件后才允许接管。默认 policy
+仍是 `any`，以保持兼容。
 
 ## 团队
 
@@ -112,9 +120,9 @@ hcc team status --task N
 ## 锁、交接和事件
 
 ```text
-hcc lock acquire [--peer ID] --resource PATH [--task N] [--ttl SEC] [--reason TEXT]
-hcc lock renew [--peer ID] --resource PATH [--ttl SEC]
-hcc lock release [--peer ID] --resource PATH [--force]
+hcc lock acquire [--peer ID] --resource PATH [--scope SCOPE] [--task N] [--ttl SEC] [--reason TEXT]
+hcc lock renew [--peer ID] --resource PATH [--scope SCOPE] [--ttl SEC]
+hcc lock release [--peer ID] --resource PATH [--scope SCOPE] [--force]
 hcc lock list [--all]
 hcc handoff create [--from ID] --summary TEXT [--task N] [--to ID] [--changed-files JSON_OR_CSV] [--tests TEXT] [--risks TEXT]
 hcc handoff list [--task N] [--limit N]
@@ -122,5 +130,7 @@ hcc event tail [--limit N]
 hcc gc [--older-than DAYS] [--yes]
 ```
 
-锁是带 TTL 的协作式 advisory lock。交接记录用于保存结果、测试、变更文件和
-剩余风险，方便工作在多个 peer 之间继续。
+锁是带 TTL 的协作式 advisory lock。不传 `--scope` 表示锁住整个资源。同一个
+资源的不同 scope 可以并行持有，例如 `--resource bin/hcc.mjs --scope db-schema`
+和 `--scope web-ui`；但整资源锁会和所有 scope 冲突。交接记录用于保存结果、
+测试、变更文件和剩余风险，方便工作在多个 peer 之间继续。

package/lib/cli-args.mjs

@@ -0,0 +1,89 @@
+import process from 'node:process';
+import { CliError } from './errors.mjs';
+
+export 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 };
+}
+
+export 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;
+}
+
+export 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('--');
+}
+
+export 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]}`);
+}
+
+export 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;
+}
+
+export function intOpt(opts, key, fallback = null) {
+  if (opts[key] === undefined || opts[key] === null || opts[key] === '') return fallback;
+  const value = Number.parseInt(String(opts[key]), 10);
+  if (!Number.isFinite(value)) throw new CliError('BAD_ARGS', `--${key} must be an integer`);
+  return value;
+}

package/lib/db-schema.mjs

@@ -0,0 +1,324 @@
+import { CliError } from './errors.mjs';
+
+export const DB_SCHEMA_VERSION = 5;
+
+const sleepBuffer = new SharedArrayBuffer(4);
+const sleepView = new Int32Array(sleepBuffer);
+
+function now() {
+  return Math.floor(Date.now() / 1000);
+}
+
+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);
+}
+
+export 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;
+}
+
+export 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;
+  }
+}
+
+export function initSchema(db, { beforePostMigrationIndexes = null } = {}) {
+  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);
+  if (typeof beforePostMigrationIndexes === 'function') beforePostMigrationIndexes(db);
+  createPostMigrationIndexes(db);
+}
+
+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,
+      base_resource TEXT,
+      scope TEXT NOT NULL DEFAULT '*',
+      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 createPostMigrationIndexes(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 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));
+}
+
+export 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);');
+      }
+    },
+    {
+      version: 5,
+      name: 'scoped advisory locks',
+      up(database) {
+        addColumnIfMissing(database, 'locks', 'base_resource', 'base_resource TEXT');
+        addColumnIfMissing(database, 'locks', 'scope', "scope TEXT NOT NULL DEFAULT '*'");
+        database.exec(`
+          UPDATE locks
+          SET base_resource = resource
+          WHERE base_resource IS NULL OR base_resource = '';
+          UPDATE locks
+          SET scope = '*'
+          WHERE scope IS NULL OR scope = '';
+          CREATE INDEX IF NOT EXISTS idx_locks_base_scope ON locks(base_resource, scope);
+        `);
+      }
+    }
+  ];
+  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);
+  });
+}

package/lib/errors.mjs

@@ -0,0 +1,7 @@
+export class CliError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.code = code;
+    this.extra = extra;
+  }
+}

package/lib/format.mjs

@@ -0,0 +1,39 @@
+export function compactText(value, limit = 160) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  return text.length > limit ? `${text.slice(0, limit - 1)}\u2026` : text;
+}
+
+export function formatJson(ok, dataOrError) {
+  if (ok) return JSON.stringify({ ok: true, data: dataOrError }, null, 2);
+  return JSON.stringify({ ok: false, error: dataOrError }, null, 2);
+}
+
+export 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);
+  }
+}
+
+export function shellQuoteArg(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(text)) return text;
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+export function shellExports(values) {
+  return Object.entries(values)
+    .map(([key, value]) => `export ${key}=${shellQuoteArg(value)}`)
+    .join('\n');
+}
+
+export 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');
+}

package/lib/guidance.mjs

@@ -53,8 +53,16 @@ Before mutating work:
   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 an advisory lock for the file, directory, module scope, or shared
+  resource.
+- Locks are coordination signals, not task ownership and not read barriers.
+  A broad lock such as \`--resource bin/hcc.mjs\` protects the whole file, while
+  scoped locks such as \`--resource bin/hcc.mjs --scope db-schema\` and
+  \`--scope web-ui\` can be held by different peers at the same time.
+- If another live peer holds a conflicting lock, message that peer before
+  editing. When the work is in separate regions of the same file, agree on
+  narrower scoped locks and wait for all related scopes to hand off or release
+  before final tests, formatting, staging, or commit.
 - 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

package/lib/json-file.mjs

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function readJsonSafe(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return null; }
+}
+
+export function writeJsonSafe(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = filePath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n');
+  fs.renameSync(tmpPath, filePath);
+}

package/lib/runtime-paths.mjs

@@ -0,0 +1,45 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export function projectStateDir(root) {
+  return path.join(root, '.hello-cc');
+}
+
+export function projectDbPath(root) {
+  return path.join(projectStateDir(root), 'mesh.db');
+}
+
+export function runtimePath(ctx) {
+  return path.join(projectStateDir(ctx.root), 'runtime.json');
+}
+
+export function webLogPath(ctx) {
+  return path.join(projectStateDir(ctx.root), 'web.log');
+}
+
+export function globalStateDir() {
+  return path.join(os.homedir(), '.hello-cc');
+}
+
+export function globalRuntimePath() {
+  return path.join(globalStateDir(), 'runtime.json');
+}
+
+export function globalWebTokenPath() {
+  return path.join(globalStateDir(), 'web-token');
+}
+
+export function projectRegistryPath() {
+  return path.join(globalStateDir(), 'projects.json');
+}
+
+export function contextForProject(root, dbPath = null, base = {}) {
+  const resolvedRoot = path.resolve(root);
+  return {
+    cwd: base.cwd || resolvedRoot,
+    root: resolvedRoot,
+    dbPath: path.resolve(dbPath || projectDbPath(resolvedRoot)),
+    json: Boolean(base.json),
+    explicitRoot: true
+  };
+}