@logicseek/hello-cc 0.1.9 → 1.0.1

package/lib/cli/commands/lock.mjs

@@ -0,0 +1,197 @@
+// Lock CLI commands extracted from bin/hcc.mjs.
+// Factory pattern with injected deps.
+
+export function createLockCommands(deps) {
+  const {
+    connect,
+    now,
+    iso,
+    tx,
+    addEvent,
+    touchCurrentPeer,
+    resolveCurrentPeer,
+    parseOpts,
+    intOpt,
+    required,
+    positiveSafeIntOpt,
+    wantsHelp,
+    helpLock,
+    printResult,
+    table,
+    CliError,
+    DEFAULT_LOCK_TTL,
+    leaseDeadline,
+    scopedLockResource,
+    lockLabel,
+    lockScope,
+    lockBaseResource,
+    locksConflict,
+    clockGraceSuppressed,
+    readClockGraceUntil,
+    clockSafetyUnavailable,
+    captureLockAcquireSubject,
+    sameLockAcquireSubject,
+    observeLockOwnerEvidence,
+    observePeerEvidence,
+    prepareLockClockObservation,
+    runOptimisticEvidenceMutation,
+    assertTaskOwnerForMutation,
+    notifyTaskOwnerConflict
+  } = deps;
+
+  async function cmdLock(ctx, args) {
+    const sub = args[0];
+    if (!sub || wantsHelp(args)) return helpLock();
+    if (sub === 'acquire') return lockAcquire(ctx, args.slice(1));
+    if (sub === 'release') return lockRelease(ctx, args.slice(1));
+    if (sub === 'renew') return lockRenew(ctx, args.slice(1));
+    if (sub === 'list') return lockList(ctx, args.slice(1));
+    throw new CliError('BAD_ARGS', `Unknown lock command: ${sub}`);
+  }
+
+  async function lockAcquire(ctx, args) {
+    const opts = parseOpts(args);
+    const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
+    const peer = identity.id;
+    const requested = scopedLockResource(required(opts, 'resource'), opts.scope);
+    const taskId = intOpt(opts, 'task', null);
+    const ttl = positiveSafeIntOpt(opts, 'ttl', DEFAULT_LOCK_TTL);
+    const reason = opts.reason || '';
+    const acquisitionNow = now();
+    leaseDeadline(acquisitionNow, ttl);
+    const db = connect(ctx);
+    touchCurrentPeer(db, ctx, identity, 'working', 'shell');
+    let lock;
+    try {
+      const outcome = runOptimisticEvidenceMutation(db, {
+        capture: (subjectDb) => {
+          try {
+            return captureLockAcquireSubject(subjectDb, {
+              taskId,
+              requested,
+              now: acquisitionNow
+            });
+          } catch (err) {
+            throw clockSafetyUnavailable(err);
+          }
+        },
+        observe: (subject) => observeLockOwnerEvidence(subject, (row, binding) =>
+          observePeerEvidence(ctx, row, binding)),
+        same: sameLockAcquireSubject,
+        beforeMutate: (subject, evidenceByOwner) =>
+          prepareLockClockObservation(db, subject, evidenceByOwner),
+        changedMessage: `Lock subjects changed while acquiring ${lockLabel(requested)}; retry`,
+        mutate: (subject, evidenceByOwner, clockObservation) => {
+          const t = subject.observedAt;
+          if (taskId) {
+            const task = subject.task;
+            if (!task) throw new CliError('NOT_FOUND', `Task #${taskId} does not exist`);
+            assertTaskOwnerForMutation(db, peer, task, 'lock-acquire');
+          }
+          const graceActive = clockGraceSuppressed(t, clockObservation.graceUntil);
+          const activeLocks = graceActive
+            ? subject.locks.filter((row) =>
+                !(Number(row.expires_at) <= t && evidenceByOwner.get(row.owner)?.state === 'dead'))
+            : subject.locks.filter((row) =>
+                Number(row.expires_at) > t ||
+                evidenceByOwner.get(row.owner)?.state === 'live'
+              );
+          const conflict = activeLocks.find((row) => locksConflict(row, requested) && row.owner !== peer);
+          if (conflict) {
+            return { error: 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 = subject.locks.find((row) => row.resource === requested.resource) || null;
+          const expiresAt = leaseDeadline(t, ttl);
+          db.prepare(`
+            INSERT INTO locks(resource, base_resource, scope, owner, task_id, reason, expires_at, created_at, ttl_sec)
+            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,
+              created_at = excluded.created_at,
+              ttl_sec = excluded.ttl_sec
+          `).run(requested.resource, requested.base_resource, requested.scope, peer, taskId, reason, expiresAt, t, ttl);
+          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 { lock: db.prepare('SELECT * FROM locks WHERE resource = ?').get(requested.resource) };
+        }
+      });
+      if (outcome.error) throw outcome.error;
+      lock = outcome.lock;
+    } catch (err) {
+      notifyTaskOwnerConflict(ctx, err);
+      throw err;
+    }
+    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 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(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(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 ${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 requested = scopedLockResource(required(opts, 'resource'), opts.scope);
+    const ttl = positiveSafeIntOpt(opts, 'ttl', DEFAULT_LOCK_TTL);
+    const renewalNow = now();
+    const expiresAt = leaseDeadline(renewalNow, 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(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 = ?, ttl_sec = ? WHERE resource = ?').run(expiresAt, 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 ${lockLabel(data)} until ${iso(data.expires_at)}`);
+  }
+
+  async function lockList(ctx, args) {
+    const opts = parseOpts(args, { booleans: ['all'] });
+    const db = connect(ctx);
+    const t = now();
+    const rows = opts.all || clockGraceSuppressed(t, readClockGraceUntil(db))
+      ? db.prepare('SELECT * FROM locks ORDER BY resource ASC').all()
+      : db.prepare('SELECT * FROM locks WHERE expires_at > ? ORDER BY resource ASC').all(t);
+    printResult(ctx, rows, (data) => table(data, [
+      { 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) },
+      { label: 'reason', value: (r) => r.reason || '' }
+    ]));
+  }
+
+  return { cmdLock };
+}

package/lib/cli/commands/misc.mjs

@@ -0,0 +1,76 @@
+// Small utility commands extracted from bin/hcc.mjs: down, find-root, which-real.
+
+export function createMiscCommands(deps) {
+  const {
+    path, process, CliError, parseOpts, printResult,
+    readRuntime, runtimeRequest, runtimePath, globalRuntimePath,
+    reclaimRuntimePointerFiles, helpDown, loadSetup,
+    waitForProcessIdentityExit,
+    PRODUCT_NAME
+  } = deps;
+
+  async function cmdDown(ctx, args) {
+    if (args[0] === '--help' || args[0] === '-h') return helpDown();
+    const pointerFiles = [runtimePath(ctx), globalRuntimePath()];
+    let runtime;
+    try {
+      runtime = readRuntime(ctx);
+    } catch (err) {
+      if (!(err instanceof CliError && err.code === 'RUNTIME_NOT_RUNNING') || process.env.HCC_RUNTIME_URL) throw err;
+      const cleanup = reclaimRuntimePointerFiles(pointerFiles, { reclaimUnknown: false });
+      if (cleanup.reclaimed < 1 || cleanup.blocked) throw err;
+      printResult(ctx, { pointers: cleanup.reclaimed }, (result) =>
+        `${PRODUCT_NAME} stale runtime pointer removed${result.pointers === 1 ? '' : 's'}`);
+      return;
+    }
+    try {
+      await runtimeRequest(ctx, 'POST', '/api/runtime/stop', {}, runtime);
+    } catch (err) {
+      if (!(err instanceof CliError && err.code === 'RUNTIME_UNREACHABLE')) throw err;
+      if (runtime.source === 'env') throw err;
+      const source = path.resolve(String(runtime.source || ''));
+      const localSource = pointerFiles.find((file) => path.resolve(file) === source);
+      if (!localSource) throw err;
+      const cleanup = reclaimRuntimePointerFiles([localSource], { reclaimUnknown: false });
+      if (cleanup.reclaimed !== 1 || cleanup.blocked) throw err;
+      printResult(ctx, { runtime: localSource }, () => `${PRODUCT_NAME} stale runtime pointer removed`);
+      return;
+    }
+    if (runtime.source !== 'env') {
+      const processIdentity = runtime.process_identity || runtime.processIdentity || runtime.pid;
+      const stopped = await waitForProcessIdentityExit(processIdentity, {
+        timeoutMs: 5_000,
+        intervalMs: 25
+      });
+      if (stopped.state !== 'dead') {
+        throw new CliError(
+          'RUNTIME_STOP_TIMEOUT',
+          `Runtime accepted the stop request, but process ${runtime.pid || 'unknown'} did not exit within 5s.`,
+          { pid: runtime.pid || null, state: stopped.state }
+        );
+      }
+    }
+    printResult(ctx, { runtime: runtime.source || runtime.base_url }, () => `${PRODUCT_NAME} runtime stopped`);
+  }
+
+  async function cmdFindRoot(ctx, args) {
+    const opts = parseOpts(args);
+    if (process.env.HCC_ROOT) {
+      process.stdout.write(path.resolve(process.env.HCC_ROOT) + '\n');
+      return;
+    }
+    const root = ctx.explicitRoot ? ctx.root : path.resolve(opts.cwd || process.cwd());
+    process.stdout.write(root + '\n');
+  }
+
+  async function cmdWhichReal(ctx, args) {
+    const name = args[0];
+    if (!name) throw new CliError('BAD_ARGS', 'Usage: hcc which-real <binary>');
+    const { findRealBinary } = await loadSetup();
+    const p = findRealBinary(name);
+    if (!p) { process.exitCode = 1; return; }
+    process.stdout.write(p + '\n');
+  }
+
+  return { cmdDown, cmdFindRoot, cmdWhichReal };
+}

package/lib/cli/commands/msg.mjs

@@ -0,0 +1,152 @@
+// Message CLI commands extracted from bin/hcc.mjs.
+// Factory pattern: all bin/hcc.mjs dependencies are injected.
+
+export function createMsgCommands(deps) {
+  const {
+    connect,
+    now,
+    iso,
+    touchCurrentPeer,
+    resolveCurrentPeer,
+    registerProjectActivity,
+    parseOpts,
+    intOpt,
+    required,
+    wantsHelp,
+    helpMsg,
+    printResult,
+    table,
+    sleep,
+    CliError,
+    ackMessage,
+    getMessage,
+    queryInbox,
+    queryMessageThread,
+    sendMessage
+  } = deps;
+
+  async function cmdMsg(ctx, args) {
+    const sub = args[0];
+    if (!sub || wantsHelp(args)) return helpMsg();
+    if (sub === 'send') return msgSend(ctx, args.slice(1));
+    if (sub === 'inbox') return msgInbox(ctx, args.slice(1));
+    if (sub === 'ack') return msgAck(ctx, args.slice(1));
+    if (sub === 'reply') return msgReply(ctx, args.slice(1));
+    if (sub === 'thread') return msgThread(ctx, args.slice(1));
+    throw new CliError('BAD_ARGS', `Unknown msg command: ${sub}`);
+  }
+
+  async function msgSend(ctx, args) {
+    const opts = parseOpts(args);
+    const identity = resolveCurrentPeer(ctx, opts, 'from', 'shell');
+    const sender = identity.id;
+    const recipient = opts.to || 'all';
+    const body = required(opts, 'body');
+    const taskId = intOpt(opts, 'task', null);
+    const kind = opts.kind || 'note';
+    const db = connect(ctx);
+    touchCurrentPeer(db, ctx, identity, null, 'shell');
+    const id = sendMessage(db, sender, recipient, taskId, kind, body);
+    printResult(ctx, { id, sender, recipient, task_id: taskId, kind, body, reply_to: null, thread_id: id },
+      (data) => `sent message #${data.id} ${data.sender} -> ${data.recipient}`);
+  }
+
+  async function msgInbox(ctx, args) {
+    const opts = parseOpts(args, { booleans: ['all'] });
+    const identity = resolveCurrentPeer(ctx, opts, 'peer', 'shell');
+    const peer = identity.id;
+    const waitSec = intOpt(opts, 'wait', 0);
+    const limit = intOpt(opts, 'limit', 20);
+    const includeAll = Boolean(opts.all);
+    const db = connect(ctx);
+    touchCurrentPeer(db, ctx, identity, null, 'shell');
+    const deadline = Date.now() + waitSec * 1000;
+    let rows = queryInbox(db, peer, includeAll, limit);
+    while (!rows.length && waitSec > 0 && Date.now() < deadline) {
+      await sleep(1000);
+      rows = queryInbox(db, peer, includeAll, limit);
+    }
+    printResult(ctx, rows, (data) => table(data, [
+      { label: 'id', value: (r) => `#${r.id}` },
+      { label: 'from', value: (r) => r.sender },
+      { label: 'kind', value: (r) => r.kind },
+      { label: 'task', value: (r) => r.task_id ? `#${r.task_id}` : '' },
+      { label: 'reply', value: (r) => r.reply_to ? `#${r.reply_to}` : '' },
+      { label: 'thread', value: (r) => r.thread_id ? `#${r.thread_id}` : '' },
+      { label: 'time', value: (r) => iso(r.created_at) },
+      { label: 'body', value: (r) => r.body }
+    ]));
+  }
+
+  async function msgAck(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 db = connect(ctx);
+    touchCurrentPeer(db, ctx, identity, null, 'shell');
+    const message = db.prepare('SELECT * FROM messages WHERE id = ?').get(id);
+    if (!message) throw new CliError('NOT_FOUND', `Message #${id} does not exist`);
+    ackMessage(db, peer, message);
+    printResult(ctx, { id, peer }, (data) => `acknowledged message #${data.id} for ${data.peer}`);
+  }
+
+  async function msgReply(ctx, args) {
+    const opts = parseOpts(args);
+    const id = intOpt(opts, 'id', intOpt({ id: opts._[0] }, 'id'));
+    if (!id) throw new CliError('BAD_ARGS', 'Missing --id');
+    const body = required(opts, 'body');
+    const db = connect(ctx);
+    const original = getMessage(db, id);
+    if (!original) throw new CliError('NOT_FOUND', `Message #${id} does not exist`);
+    const identity = resolveCurrentPeer(ctx, opts, 'from', 'shell');
+    const sender = identity.id;
+    touchCurrentPeer(db, ctx, identity, null, 'shell');
+    const recipient = opts.to || original.sender;
+    const taskId = intOpt(opts, 'task', original.task_id || null);
+    const kind = opts.kind || 'reply';
+    const threadId = original.thread_id || original.id;
+    const replyId = sendMessage(db, sender, recipient, taskId, kind, body, {
+      reply_to: original.id,
+      thread_id: threadId
+    });
+    ackMessage(db, sender, original);
+    printResult(ctx, {
+      id: replyId,
+      sender,
+      recipient,
+      task_id: taskId,
+      kind,
+      body,
+      reply_to: original.id,
+      thread_id: threadId
+    }, (data) => `sent reply #${data.id} to #${data.reply_to} ${data.sender} -> ${data.recipient}`);
+  }
+
+  async function msgThread(ctx, args) {
+    const opts = parseOpts(args);
+    const id = intOpt(opts, 'id', intOpt({ id: opts._[0] }, 'id'));
+    if (!id) throw new CliError('BAD_ARGS', 'Missing --id');
+    const limit = intOpt(opts, 'limit', 50);
+    const db = connect(ctx);
+    const data = queryMessageThread(db, id, limit);
+    printResult(ctx, data, (thread) => {
+      const lines = [`thread #${thread.thread_id} (${thread.messages.length} message${thread.messages.length === 1 ? '' : 's'})`];
+      for (const message of thread.messages) {
+        const parts = [
+          `#${message.id}`,
+          `${message.sender} -> ${message.recipient || 'all'}`,
+          message.task_id ? `task #${message.task_id}` : '',
+          message.reply_to ? `reply #${message.reply_to}` : '',
+          message.kind || 'note',
+          iso(message.created_at)
+        ].filter(Boolean).join(' ');
+        lines.push(`${parts}\n  ${message.body}`);
+      }
+      return lines.join('\n');
+    });
+  }
+
+  return { cmdMsg };
+}

package/lib/cli/commands/peer.mjs

@@ -0,0 +1,249 @@
+// Peer management commands extracted from bin/hcc.mjs.
+
+import {
+  RUNTIME_SESSION_MUTATION_TIMEOUT_MS,
+  RUNTIME_SESSION_START_TIMEOUT_MS
+} from '../../runtime/client.mjs';
+
+export function createPeerCommands(deps) {
+  const {
+    connect, now, tx, addEvent, auditPayload, printResult, CliError, parseOpts,
+    detectBranch, buildPeerCommand, childSessionEnv, inferPeerKind,
+    findProviderSessionBinding, bindingHasRuntime,
+    resolveCurrentPeer, helpPeer, wantsHelp, CLI_NAME, cmdPeers,
+    runtimeRequest, readRuntime,
+    upsertPeer, upsertCanonicalPeerBinding, storedPeerIdentity,
+    path, process, Map, table
+  } = deps;
+
+async function cmdPeer(ctx, args) {
+  const sub = args[0];
+  if (!sub || wantsHelp(args)) return helpPeer();
+  if (sub === 'list') return peerList(ctx, args.slice(1));
+  if (sub === 'start') return peerStart(ctx, args.slice(1));
+  if (sub === 'attach') return peerAttach(ctx, args.slice(1));
+  if (sub === 'stop') return peerStop(ctx, args.slice(1));
+  throw new CliError('BAD_ARGS', `Unknown peer command: ${sub}`);
+}
+
+async function peerList(ctx, args) {
+  parseOpts(args);
+  try {
+    const data = await runtimeRequest(ctx, 'GET', '/api/sessions');
+    const db = connect(ctx);
+    let bindings;
+    try {
+      bindings = new Map(db.prepare('SELECT * FROM peer_bindings').all().map((row) => [row.peer, row]));
+    } finally {
+      db.close();
+    }
+    const rows = (data.sessions || []).map((session) => ({
+      ...session,
+      binding: bindings.get(session.peer_id || session.id) || bindings.get(session.id) || null
+    }));
+    printResult(ctx, rows, (items) => table(items, [
+      { label: 'id', value: (r) => r.id },
+      { label: 'peer', value: (r) => r.peer_id && r.peer_id !== r.id ? r.peer_id : '' },
+      { label: 'kind', value: (r) => r.kind },
+      { label: 'role', value: (r) => r.role || '' },
+      { label: 'status', value: (r) => r.status },
+      { label: 'type', value: (r) => r.type || '' },
+      { label: 'pane', value: (r) => r.pane || '' },
+      { label: 'provider', value: (r) => r.binding ? r.binding.provider : '' },
+      { label: 'resume', value: (r) => r.binding ? r.binding.resume_mode : '' },
+      { label: 'session', value: (r) => r.binding ? (r.binding.provider_session_id || r.binding.provider_session_name || '') : '' },
+      { label: 'pid', value: (r) => r.pid || '' },
+      { label: 'command', value: (r) => r.command || '' }
+    ]));
+  } catch (err) {
+    if (err instanceof CliError && ['RUNTIME_NOT_RUNNING', 'RUNTIME_UNREACHABLE'].includes(err.code)) {
+      return cmdPeers(ctx, []);
+    }
+    throw err;
+  }
+}
+
+async function peerStart(ctx, args) {
+  const sep = args.indexOf('--');
+  const optArgs = sep >= 0 ? args.slice(0, sep) : args;
+  const cmdArgs = sep >= 0 ? args.slice(sep + 1) : [];
+  const opts = parseOpts(optArgs, { booleans: ['last', 'continue', 'fork', 'force', 'restart-env'] });
+  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
+  const id = opts.peer || opts._[0];
+  if (!id) throw new CliError('BAD_ARGS', 'Missing peer');
+  const firstCommand = cmdArgs[0] || '';
+  const kind = inferPeerKind(id, opts.kind, firstCommand);
+  const role = opts.role || 'peer';
+  const cwd = path.resolve(opts.cwd || ctx.root);
+  const built = buildPeerCommand(id, kind, opts, cmdArgs);
+  const command = built.command;
+  const binding = { ...built.binding, transport: 'tmux', runtime_session_id: id };
+
+  let runtime;
+  try { runtime = readRuntime(ctx); } catch (e) {
+    if (e instanceof CliError && e.code === 'RUNTIME_NOT_RUNNING') {
+      throw new CliError('RUNTIME_NOT_RUNNING',
+        `No running web runtime found. Start ${CLI_NAME} web first, then ${CLI_NAME} peer start ${id}`);
+    }
+    throw e;
+  }
+
+  await runtimeRequest(ctx, 'GET', '/api/runtime', null, runtime, {
+    timeoutMs: RUNTIME_SESSION_START_TIMEOUT_MS
+  });
+  const db = connect(ctx);
+  try {
+    tx(db, () => {
+      if (!opts.force) {
+        const conflict = findProviderSessionBinding(db, binding);
+        if (bindingHasRuntime(conflict)) {
+          const providerSession = binding.provider_session_id || binding.provider_session_name || '';
+          throw new CliError('PROVIDER_SESSION_IN_USE', `${binding.provider} session ${providerSession} is already bound to ${conflict.peer}`, {
+            peer: conflict.peer,
+            provider: conflict.provider,
+            provider_session: providerSession
+          });
+        }
+      }
+      const previousOwner = db.prepare(`
+        SELECT pid, pid_start_token, pid_command_hash
+        FROM peers WHERE id = ?
+      `).get(id) || null;
+      upsertPeer(db, {
+        id, kind, role,
+        worktree: cwd,
+        branch: detectBranch(cwd),
+        pid: previousOwner?.pid || null,
+        processIdentity: storedPeerIdentity(previousOwner),
+        status: 'starting',
+        capabilities: 'tmux'
+      });
+      addEvent(db, 'peer.start.requested', actor, null, auditPayload({
+        actor,
+        target: id,
+        peer: id,
+        source: 'cli',
+        admin: actor !== id,
+        kind,
+        role,
+        command,
+        cwd
+      }));
+    });
+  } finally {
+    db.close();
+  }
+  const data = await runtimeRequest(ctx, 'POST', '/api/sessions', {
+    id,
+    kind,
+    role,
+    command,
+    cwd,
+    binding,
+    env: childSessionEnv(),
+    restartOnEnvChange: Boolean(opts['restart-env']),
+    providerForce: Boolean(opts.force)
+  }, runtime, { timeoutMs: RUNTIME_SESSION_START_TIMEOUT_MS });
+  printResult(ctx, data.session, (session) =>
+    `started ${session.id} (${session.kind}, ${session.role})${session.pane ? ` pane=${session.pane}` : ` pid=${session.pid}`}`);
+}
+
+async function peerAttach(ctx, args) {
+  const opts = parseOpts(args, { booleans: ['force'] });
+  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
+  const id = opts.peer || opts._[0];
+  if (!id) throw new CliError('BAD_ARGS', 'Missing peer');
+  const pane = opts.pane || process.env.TMUX_PANE || null;
+  const kind = opts.kind || null;
+  const role = opts.role || 'peer';
+  const cwd = opts.cwd ? path.resolve(opts.cwd) : null;
+
+  let runtime;
+  try { runtime = readRuntime(ctx); } catch (e) {
+    if (e instanceof CliError && e.code === 'RUNTIME_NOT_RUNNING') {
+      throw new CliError('RUNTIME_NOT_RUNNING',
+        `No running web runtime found. Start ${CLI_NAME} web first, then ${CLI_NAME} peer attach ${id}`);
+    }
+    throw e;
+  }
+  await runtimeRequest(ctx, 'GET', '/api/runtime', null, runtime, {
+    timeoutMs: RUNTIME_SESSION_START_TIMEOUT_MS
+  });
+  const db = connect(ctx);
+  try {
+    addEvent(db, 'peer.attach.requested', actor, null, auditPayload({
+      actor,
+      target: id,
+      peer: id,
+      source: 'cli',
+      admin: actor !== id,
+      pane,
+      kind,
+      role,
+      cwd
+    }));
+  } finally {
+    db.close();
+  }
+  const data = await runtimeRequest(ctx, 'POST', '/api/sessions/attach', {
+    id,
+    kind,
+    role,
+    pane,
+    cwd,
+    force: Boolean(opts.force)
+  }, runtime, { timeoutMs: RUNTIME_SESSION_START_TIMEOUT_MS });
+  printResult(ctx, data.session, (session) => `attached ${session.id} (${session.kind}, ${session.role}) pane=${session.pane}`);
+}
+
+async function peerStop(ctx, args) {
+  const opts = parseOpts(args);
+  const actor = resolveCurrentPeer(ctx, {}, 'peer', 'shell').id;
+  const id = opts.peer || opts._[0];
+  if (!id) throw new CliError('BAD_ARGS', 'Missing peer');
+  let data;
+  try {
+    const db = connect(ctx);
+    try {
+      addEvent(db, 'peer.stop.requested', actor, null, auditPayload({
+        actor,
+        target: id,
+        peer: id,
+        source: 'cli',
+        admin: actor !== id
+      }));
+    } finally {
+      db.close();
+    }
+    data = await runtimeRequest(
+      ctx,
+      'POST',
+      `/api/sessions/${encodeURIComponent(id)}/stop`,
+      {},
+      null,
+      { timeoutMs: RUNTIME_SESSION_MUTATION_TIMEOUT_MS }
+    );
+  } catch (err) {
+    if (err instanceof CliError && err.code === 'RUNTIME_NOT_RUNNING') {
+      // No server: just update the DB to mark the peer as exited
+      const db = connect(ctx);
+      try {
+        db.prepare('UPDATE peers SET status = ?, last_seen_at = ? WHERE id = ?').run('exited', now(), id);
+        addEvent(db, 'peer.stopped', actor, null, auditPayload({
+          actor,
+          target: id,
+          peer: id,
+          admin: actor !== id
+        }));
+      } finally { db.close(); }
+      printResult(ctx, { id, status: 'exited' }, (s) => `stopped ${s.id} (no server running — DB marked exited)`);
+      return;
+    }
+    throw err;
+  }
+  printResult(ctx, data.session, (session) => `stopped ${session.id}`);
+}
+
+
+  return { cmdPeer };
+}