@bahulam/code 0.1.1 → 0.1.3

package/src/daemon/socket-server.mjs

@@ -0,0 +1,329 @@
+/**
+ * Unix socket server — accepts local CLI client connections and
+ * dispatches relay events to attached clients.
+ *
+ * Commands accepted from local clients:
+ *   • `approve` / `deny` — dispatched to the approval handler
+ *   • `interrupt`, `send_message`, `switch_model` — forwarded to relay
+ *   • `take_input_lock` / `release_input_lock` — lock management *   • Multi-attach input lock ().
+ *   • Relay bridge ().
+ *
+ * Design invariants:
+ *   • ONE writer per event log; the server never writes to the log
+ *     directly. The tap does. The server only READS the log to replay.
+ *   • Broadcast failures on ONE client MUST NOT affect other clients or
+ *     the daemon's own event flow. Every socket write is try/catch'd.
+ *   • The server is a passive fan-out: it does not mutate session
+ *     state, it does not drive the SSE loop, it does not have opinions
+ *     about which events matter.
+ */
+
+import * as net from 'node:net';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { readEvents, readLatestSnapshot } from '../core/event-log.mjs';
+import { daemonSocketPath, daemonSocketsDir } from '../core/paths.mjs';
+import {
+  onAttachJoined, onAttachLeft, takeInputLock, releaseInputLock, isHolder,
+} from './input-lock.mjs';
+
+const NL = '\n';
+
+/**
+ * Create + start a socket server for one session.
+ *
+ * @param {object} opts
+ * @param {string} opts.sessionId
+ * @param {object} [opts.onCommand] — { approve, deny, interrupt, sendMessage, ... }
+ *                                     each handler is `async (payload, attachId) => void`.
+ *                                     Missing keys → the server responds with a
+ *                                     `command_error { code: "not_implemented" }` event.
+ * @returns {Promise<{
+ *   sockPath: string,
+ *   broadcastEvent(event: object): void,
+ *   attachedCount(): number,
+ *   close(): Promise<void>,
+ * }>}
+ */
+export async function startSocketServer({ sessionId, onCommand = {} } = {}) {
+  if (!sessionId) throw new Error('startSocketServer: sessionId is required');
+
+  const sockPath = daemonSocketPath(sessionId);
+  fs.mkdirSync(daemonSocketsDir(), { recursive: true, mode: 0o700 });
+  // If a stale socket exists (previous daemon crashed), remove it before bind.
+  // The OS retains the inode across process death so `listen` will EADDRINUSE
+  // even though nothing owns it.
+  try { fs.unlinkSync(sockPath); } catch { /* file didn't exist, fine */ }
+
+  /** @type {Set<AttachedClient>} */
+  const clients = new Set();
+
+  const server = net.createServer(sock => {
+    // 0600 on the socket path itself. On most kernels this is enforced at
+    // bind() time (see below), but re-chmod defensively in case umask lied.
+    try { fs.chmodSync(sockPath, 0o600); } catch { /* best effort */ }
+
+    const client = _createAttachedClient(sock, sessionId, onCommand);
+    clients.add(client);
+    sock.on('close', () => { clients.delete(client); });
+  });
+
+  server.on('error', err => {
+    // Never crash on a listen error — log and let the caller notice via
+    // attachedCount() staying at 0. The daemon session itself continues.
+    try { process.stderr.write(`[socket-server] listen error: ${err.message}\n`); } catch {}
+  });
+
+  // Bind with umask temporarily narrowed so the socket file is created 0600
+  // even if the user's shell umask would grant group/other read.
+  const priorUmask = process.umask(0o077);
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(sockPath, () => {
+        server.off('error', reject);
+        resolve();
+      });
+    });
+  } finally {
+    process.umask(priorUmask);
+  }
+  // chmod again post-listen — belt and braces on platforms where the umask
+  // trick doesn't cover socket files (rare but seen on some Linux configs).
+  try { fs.chmodSync(sockPath, 0o600); } catch { /* ignore */ }
+
+  return {
+    sockPath,
+    broadcastEvent(event) {
+      // Fire-and-forget to every client. One slow reader must not throttle
+      // the daemon; we let the OS socket buffer absorb bursts and drop on
+      // the individual client if that client fills.
+      const line = _serializeFrame(event);
+      for (const client of clients) {
+        try { client.write(line); }
+        catch (err) { try { process.stderr.write(`[socket-server] write to ${client.id} failed: ${err.message}\n`); } catch {} }
+      }
+    },
+    attachedCount: () => clients.size,
+    async close() {
+      // Close all client sockets first so they drain, then stop listening.
+      for (const client of Array.from(clients)) {
+        try { client.end(); } catch { /* ignore */ }
+      }
+      await new Promise(res => server.close(() => res()));
+      try { fs.unlinkSync(sockPath); } catch { /* ignore */ }
+    },
+  };
+}
+
+// ── attached client (per-connection state) ───────────────────────────
+
+let _nextAttachId = 1;
+
+/**
+ * @typedef {{ id: string, write: (line: string) => void, end: () => void }} AttachedClient
+ */
+
+function _createAttachedClient(sock, sessionId, onCommand) {
+  const attachId = `att_${Date.now().toString(36)}_${(_nextAttachId++).toString(36)}`;
+  let helloSeen = false;
+  let buf = '';
+
+  sock.setEncoding('utf-8');
+  sock.on('data', chunk => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf(NL)) !== -1) {
+      const line = buf.slice(0, nl);
+      buf = buf.slice(nl + 1);
+      if (line.trim().length === 0) continue;
+      _handleFrame(line).catch(err => {
+        try { process.stderr.write(`[socket-server] frame handler crashed: ${err.message}\n`); } catch {}
+      });
+    }
+  });
+  sock.on('error', err => {
+    try { process.stderr.write(`[socket-server] ${attachId} socket error: ${err.message}\n`); } catch {}
+  });
+
+  async function _handleFrame(line) {
+    let msg;
+    try { msg = JSON.parse(line); }
+    catch { _sendError('invalid_json', 'frame is not valid JSON'); return; }
+    if (!msg || typeof msg.type !== 'string') {
+      _sendError('invalid_frame', 'missing type'); return;
+    }
+
+    if (!helloSeen && msg.type !== 'hello') {
+      _sendError('hello_required', 'first frame must be hello'); return;
+    }
+
+    switch (msg.type) {
+      case 'hello': {
+        helloSeen = true;
+        const lastSeq = Number(msg.last_seq) || 0;
+        //  — input lock: first attach implicitly becomes holder;
+        // later attaches join as watchers. The state is stored in
+        // input-lock.mjs; the changed event is emitted from THAT module
+        // (via wireEmit()) so it also fans out through the tap and hits
+        // the event log for later attaches to replay.
+        const lockInfo = onAttachJoined(attachId);
+        _send({
+          type: 'hello_ok', v: 1,
+          data: {
+            attach_id: attachId,
+            session_id: sessionId,
+            input_lock: { holder: lockInfo.holder, kind: lockInfo.kind },
+          },
+        });
+        await _replaySince(lastSeq);
+        _send({
+          seq: 0, ts: new Date().toISOString(), type: 'attach_joined',
+          session_id: sessionId, v: 1,
+          data: {
+            attach_id: attachId, kind: 'local',
+            human_hint: msg.human_hint || null,
+            input_role: lockInfo.kind,   // 'holder' | 'watch'
+          },
+        });
+        return;
+      }
+      //  — input lock commands. Both handled internally by the
+      // shared input-lock.mjs state; the resulting input_lock_changed
+      // event is emitted from that module (via wireEmit) so all attaches
+      // see the transition, including the daemon's local renderer.
+      case 'take_input_lock': {
+        const out = takeInputLock(attachId);
+        _send({
+          seq: 0, ts: new Date().toISOString(), type: 'input_lock_ack',
+          session_id: sessionId, v: 1,
+          data: { in_reply_to: msg.reply_to || null, ...out },
+        });
+        return;
+      }
+      case 'release_input_lock': {
+        const out = releaseInputLock(attachId);
+        _send({
+          seq: 0, ts: new Date().toISOString(), type: 'input_lock_ack',
+          session_id: sessionId, v: 1,
+          data: { in_reply_to: msg.reply_to || null, ...out },
+        });
+        return;
+      }
+
+      case 'bye': {
+        onAttachLeft(attachId);
+        // Serialize attach_left, then end() only after the write drains.
+        // Immediate sock.end() after sock.write() races the flush on some
+        // kernels — the FIN can go out before the frame's last byte lands
+        // in the client's read buffer, so the client sees close-without-
+        // attach_left. Use the write completion callback to sequence.
+        const frame = _serializeFrame({
+          seq: 0, ts: new Date().toISOString(), type: 'attach_left',
+          session_id: sessionId, v: 1, data: { attach_id: attachId, reason: 'bye' },
+        });
+        try {
+          sock.write(frame, () => { try { sock.end(); } catch {} });
+        } catch {
+          try { sock.end(); } catch {}
+        }
+        return;
+      }
+      case 'approve':
+      case 'deny': {
+        const handler = onCommand[msg.type];
+        if (typeof handler !== 'function') {
+          _sendError('not_implemented', `command ${msg.type} has no handler`, msg.reply_to);
+          return;
+        }
+        try { await handler(msg.data || {}, attachId); }
+        catch (err) { _sendError('handler_failed', err.message, msg.reply_to); }
+        return;
+      }
+      case 'interrupt':
+      case 'send_message':
+      case 'switch_model': {
+        //  — typing-class commands require the input lock. Watch-
+        // mode attaches get a `not_input_holder` error and can request
+        // the lock via take_input_lock (steal-with-grace).
+        if (!isHolder(attachId)) {
+          _sendError('not_input_holder', `command ${msg.type} requires the input lock; send take_input_lock first`, msg.reply_to);
+          return;
+        }
+        const handler = onCommand[msg.type];
+        if (typeof handler !== 'function') {
+          _sendError('not_implemented', `command ${msg.type} is not wired yet (deferred slice)`, msg.reply_to);
+          return;
+        }
+        try { await handler(msg.data || {}, attachId); }
+        catch (err) { _sendError('handler_failed', err.message, msg.reply_to); }
+        return;
+      }
+      case 'wake': {
+        const handler = onCommand[msg.type];
+        if (typeof handler !== 'function') {
+          _sendError('not_implemented', `command ${msg.type} is not wired yet (deferred slice)`, msg.reply_to);
+          return;
+        }
+        try { await handler(msg.data || {}, attachId); }
+        catch (err) { _sendError('handler_failed', err.message, msg.reply_to); }
+        return;
+      }
+      default:
+        _sendError('unknown_type', `unknown command: ${msg.type}`, msg.reply_to);
+    }
+  }
+
+  async function _replaySince(lastSeq) {
+    // Seed from snapshot (if any) so long-running sessions don't stream 100k
+    // events at attach time. Then stream events with seq > snapshot.seq (or
+    // > lastSeq, whichever's higher).
+    let sinceSeq = lastSeq;
+    const snap = await readLatestSnapshot({ sessionId }).catch(() => null);
+    if (snap && typeof snap.seq === 'number' && snap.seq > sinceSeq) {
+      _send({
+        seq: 0, ts: new Date().toISOString(), type: 'snapshot',
+        session_id: sessionId, v: 1, data: { seq: snap.seq, state: snap.state },
+      });
+      sinceSeq = snap.seq;
+    }
+    let firstSeq = null, lastSeqSeen = sinceSeq;
+    const batch = [];
+    for await (const evt of readEvents({ sessionId, sinceSeq })) {
+      if (firstSeq == null) firstSeq = evt.seq;
+      batch.push(evt);
+      lastSeqSeen = evt.seq;
+    }
+    if (batch.length > 0) {
+      _send({ seq: 0, ts: new Date().toISOString(), type: 'replay_batch_start',
+              session_id: sessionId, v: 1, data: { from_seq: firstSeq, to_seq: lastSeqSeen } });
+      for (const evt of batch) _send(evt);
+      _send({ seq: 0, ts: new Date().toISOString(), type: 'replay_batch_end',
+              session_id: sessionId, v: 1, data: { from_seq: firstSeq, to_seq: lastSeqSeen } });
+    }
+  }
+
+  function _send(obj) {
+    try { sock.write(_serializeFrame(obj)); }
+    catch { /* silent — client will close and we'll clean up */ }
+  }
+
+  function _sendError(code, message, in_reply_to) {
+    _send({
+      seq: 0, ts: new Date().toISOString(), type: 'command_error',
+      session_id: sessionId, v: 1,
+      data: { code, message, ...(in_reply_to ? { in_reply_to } : {}) },
+    });
+  }
+
+  return {
+    id: attachId,
+    write: line => sock.write(line),
+    end: () => sock.end(),
+  };
+}
+
+function _serializeFrame(obj) {
+  return JSON.stringify(obj) + NL;
+}

package/src/daemon/stop-daemon.mjs

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { daemonSessionDir } from '../core/paths.mjs';
+
+export async function stopDaemonSession(sessionId) {
+  if (!sessionId) {
+    process.stderr.write('Usage: bahulam stop <session-id>\n');
+    return;
+  }
+  const pidFile = join(daemonSessionDir(sessionId), 'daemon.pid');
+  try {
+    const pid = parseInt((await readFile(pidFile, 'utf-8')).trim(), 10);
+    process.kill(pid, 'SIGTERM');
+    process.stderr.write(`Sent SIGTERM to daemon ${sessionId} (pid ${pid})\n`);
+  } catch (err) {
+    process.stderr.write(`Failed to stop daemon ${sessionId}: ${err.message}\n`);
+  }
+}

package/src/permissions/checker.mjs

@@ -17,7 +17,7 @@ export function createPermissionChecker(config = {}) {
         mode,
         async check(toolName, input) {
             // Always run injection check on Bash commands
-            if (toolName === 'Bash' && input?.command) {
+            if (toolName === 'shell' && input?.command) {
                 const injection = checkInjection(input.command);
                 if (!injection.safe) {
                     return false; // block dangerous commands
@@ -25,8 +25,8 @@ export function createPermissionChecker(config = {}) {
             }
 
             // Always validate file paths for file operations
-            if (['Edit', 'Write', 'Read', 'MultiEdit'].includes(toolName) && input?.file_path) {
-                const pathResult = validatePath(input.file_path, { write: toolName !== 'Read' });
+            if (['edit_file', 'write_file', 'read_file', 'MultiEdit'].includes(toolName) && input?.file_path) {
+                const pathResult = validatePath(input.file_path, { write: toolName !== 'read_file' });
                 if (!pathResult.safe) {
                     return false; // block unsafe paths
                 }
@@ -35,14 +35,14 @@ export function createPermissionChecker(config = {}) {
             switch (mode) {
                 case 'bypassPermissions': return true;
                 case 'acceptEdits':
-                    // Allow file ops, block Bash/Agent unless rl available
-                    if (toolName === 'Bash' || toolName === 'Agent') {
+                    // Allow file ops, block shell/Agent unless rl available
+                    if (toolName === 'shell' || toolName === 'Agent') {
                         return !requiresPermission(toolName) || !!config.bypassBash;
                     }
                     return true;
                 case 'auto': return true; // AI decides
                 case 'dontAsk': return false; // deny everything not pre-approved
-                case 'plan': return toolName === 'Read' || toolName === 'Glob' || toolName === 'Grep';
+                case 'plan': return toolName === 'read_file' || toolName === 'list_files' || toolName === 'search_code' || toolName === 'grep';
                 case 'default':
                 default:
                     // In default mode, safe tools pass through

package/src/permissions/prompt.mjs

@@ -34,12 +34,12 @@ export async function promptPermission(toolName, input, rl) {
  */
 export function formatToolSummary(toolName, input) {
     switch (toolName) {
-        case 'Bash':
-            return `Bash: ${truncate(input.command || '', 60)}`;
-        case 'Edit':
-            return `Edit: ${input.file_path || 'unknown file'}`;
-        case 'Write':
-            return `Write: ${input.file_path || 'unknown file'} (${(input.content || '').length} chars)`;
+        case 'shell':
+            return `shell: ${truncate(input.command || '', 60)}`;
+        case 'edit_file':
+            return `edit_file: ${input.file_path || 'unknown file'}`;
+        case 'write_file':
+            return `write_file: ${input.file_path || 'unknown file'} (${(input.content || '').length} chars)`;
         case 'MultiEdit':
             return `MultiEdit: ${input.file_path || 'unknown file'} (${(input.edits || []).length} edits)`;
         case 'Agent':
@@ -61,7 +61,8 @@ export function formatToolSummary(toolName, input) {
  */
 export function requiresPermission(toolName) {
     const SAFE_TOOLS = new Set([
-        'Read', 'Glob', 'Grep', 'LS', 'ToolSearch',
+        'read_file', 'list_files', 'search_code',
+        'grep', 'search_files', 'LS', 'ToolSearch',
         'AskUser', 'CronList', 'TodoWrite',
     ]);
     return !SAFE_TOOLS.has(toolName);

package/src/skills/installer.mjs

@@ -119,12 +119,20 @@ export class SkillInstaller {
             fs.mkdirSync(skillsDir, { recursive: true });
 
             const plans = [];
+            const seenNames = new Set();
             for (const skillDir of skillDirs) {
                 rejectSymlinks(skillDir);
                 const content = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8');
                 const name = parseSkill(content, path.basename(skillDir)).name;
                 if (onlyNames && !onlyNames.includes(name)) continue;
                 if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) throw new Error(`Unsafe skill name: ${name}`);
+                // Source repos sometimes ship multiple SKILL.md bundles that all
+                // parse to the same name (e.g. one variant per agent tool).
+                // Silently keep only the FIRST occurrence — otherwise we'd copy
+                // N bundles into the same destination and the last write would
+                // win invisibly.
+                if (seenNames.has(name)) continue;
+                seenNames.add(name);
                 const destination = path.join(skillsDir, name);
                 if (fs.existsSync(destination)) {
                     if (!force) throw new Error(`Skill already installed: ${name} (use --force to replace)`);

package/src/terminal/ansi.mjs

@@ -600,21 +600,80 @@ function inlineMarkdown(text) {
 /**
  * Render a unified diff with +/- color highlighting.
  */
-export function renderDiff(diffText) {
+// Parses `@@ -old_start,old_count +new_start,new_count @@` from a unified
+// diff hunk header. Missing counts default to 1 (per unified-diff spec).
+const _HUNK_RE = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+
+function _padLineNo(n, width) {
+  return n === null ? ' '.repeat(width) : String(n).padStart(width);
+}
+
+/**
+ * Render a unified diff with GitHub-PR-style single-column line numbers.
+ *
+ *   12   context line
+ *   13 - removed line
+ *   13 + added line
+ *   14   context line
+ *
+ * Deletions show the OLD-side line number; additions and context show the
+ * NEW-side number. Hunk headers (`@@ ... @@`) are kept as visual section
+ * markers and seed the counters. Pass `{ numbers: false }` to fall back to
+ * the plain colored-only form.
+ */
+export function renderDiff(diffText, { numbers = true } = {}) {
   if (!diffText) return '';
   const lines = diffText.split('\n');
   const out = [];
+  let oldLn = null;
+  let newLn = null;
+  // Width the gutter to the largest number that will appear in this diff,
+  // clamped to 4 so short diffs still line up cleanly. Prevents a single
+  // huge line number from pushing the whole gutter wide.
+  let gutterWidth = 4;
+  if (numbers) {
+    for (const line of lines) {
+      const m = line.match(_HUNK_RE);
+      if (m) {
+        const maxNum = Math.max(parseInt(m[1], 10), parseInt(m[2], 10));
+        gutterWidth = Math.max(gutterWidth, String(maxNum + 200).length);
+      }
+    }
+  }
+
   for (const line of lines) {
     if (line.startsWith('+++') || line.startsWith('---')) {
       out.push(c.bold(line));
-    } else if (line.startsWith('@@')) {
+      continue;
+    }
+    const m = line.match(_HUNK_RE);
+    if (m) {
+      oldLn = parseInt(m[1], 10);
+      newLn = parseInt(m[2], 10);
       out.push(c.brand(line));
-    } else if (line.startsWith('+')) {
-      out.push(c.green(line));
+      continue;
+    }
+    if (!numbers || oldLn === null) {
+      if (line.startsWith('+')) out.push(c.green(line));
+      else if (line.startsWith('-')) out.push(c.red(line));
+      else out.push(c.gray(line));
+      continue;
+    }
+    if (line.startsWith('+')) {
+      out.push(`${c.gray(_padLineNo(newLn, gutterWidth))} ${c.green(line)}`);
+      newLn += 1;
     } else if (line.startsWith('-')) {
-      out.push(c.red(line));
+      out.push(`${c.gray(_padLineNo(oldLn, gutterWidth))} ${c.red(line)}`);
+      oldLn += 1;
+    } else if (line.startsWith('\\')) {
+      // "" — meta, no line-number applies.
+      out.push(`${' '.repeat(gutterWidth)} ${c.dim(line)}`);
     } else {
-      out.push(c.gray(line));
+      // Context (line starts with a single space per unified-diff spec,
+      // or is truly empty for a blank context line).
+      out.push(`${c.gray(_padLineNo(newLn, gutterWidth))} ${c.gray(line)}`);
+      oldLn += 1;
+      newLn += 1;
     }
   }
   return out.join('\n');
@@ -668,9 +727,26 @@ export function table(headers, rows) {
 // ── Elapsed Timer ──
 
 export function formatElapsed(startMs) {
-  const s = Math.floor((Date.now() - startMs) / 1000);
-  if (s < 60) return `${s}s`;
-  return `${Math.floor(s / 60)}m${s % 60}s`;
+  return formatSeconds((Date.now() - startMs) / 1000);
+}
+
+/**
+ * Human-readable duration from a numeric seconds value. Same shape as
+ * formatElapsed (`1h:35m:19s` / `35m:19s` / `19s`) so every duration in
+ * the UI reads the same. Sub-second values fall back to one decimal so
+ * fast tool calls don't collapse to `0s`.
+ */
+export function formatSeconds(seconds) {
+  const s = Number(seconds);
+  if (!Number.isFinite(s) || s < 0) return '0s';
+  if (s < 1) return `${s.toFixed(1)}s`;
+  const whole = Math.floor(s);
+  const h = Math.floor(whole / 3600);
+  const m = Math.floor((whole % 3600) / 60);
+  const sec = whole % 60;
+  if (h > 0) return `${h}h:${m}m:${sec}s`;
+  if (m > 0) return `${m}m:${sec}s`;
+  return `${sec}s`;
 }
 
 // ── Format Cost ──

package/src/terminal/main.mjs

@@ -232,6 +232,14 @@ async function main() {
     bahulam init                   Scaffold .bahulam config, memory, hooks, tasks
     bahulam version                Show version
 
+  \x1b[1mDaemon:\x1b[0m
+    bahulam list               List detached daemon sessions
+    bahulam attach <id>        Attach to a running daemon
+    bahulam stop <id>          Stop a running daemon
+    bahulam pair               Pair a device for remote access
+    bahulam remote enable      Enable relay connection
+    bahulam remote disable     Disable relay connection (kill switch)
+
   \x1b[1mAnalytics:\x1b[0m
     bahulam sessions               List recent local sessions
     bahulam stats                  Show aggregate local session stats
@@ -285,12 +293,98 @@ async function main() {
     return;
   }
 
-  // ── Headless mode (benchmarks, automation) ──
+  // ── Daemon subcommands (daemon) ──
+
+  if (subcommand === 'list') {
+    const { listDaemonSessions } = await import('../daemon/session-list.mjs');
+    await listDaemonSessions();
+    return;
+  }
+
+  if (subcommand === 'attach') {
+    const { attachToSession } = await import('../daemon/attach-client.mjs');
+    await attachToSession(subcommandArgs[0]);
+    return;
+  }
+
+  if (subcommand === 'stop') {
+    const { stopDaemonSession } = await import('../daemon/stop-daemon.mjs');
+    await stopDaemonSession(subcommandArgs[0]);
+    return;
+  }
+
+  if (subcommand === 'pair') {
+    const { runPairCommand } = await import('../commands/pair.mjs');
+    await runPairCommand(subcommandArgs);
+    return;
+  }
+
+  if (subcommand === 'device') {
+    const { runDeviceCommand } = await import('../commands/device.mjs');
+    const code = await runDeviceCommand(subcommandArgs);
+    process.exit(code || 0);
+  }
+
+  if (subcommand === 'remote') {
+    const { runRemoteCommand } = await import('../commands/remote.mjs');
+    await runRemoteCommand(subcommandArgs);
+    return;
+  }
+
+  //  auto-daemon spawn.
+  //   bahulam daemonize [prompt]  → fork a detached bahulam child with
+  //   the socket server up. Parent waits briefly for the child's session
+  //   id to appear, prints it, and exits. Attach later with `bahulam
+  //   attach <sess_id>` or from a paired device via the relay.
+  if (subcommand === 'daemonize') {
+    const { spawnDetachedDaemon } = await import('../daemon/daemonize.mjs');
+    const initialPrompt = subcommandArgs.join(' ').trim();
+    const { pid, waitForSession } = spawnDetachedDaemon({
+      cwd: process.cwd(),
+      prompt: initialPrompt || null,
+    });
+    process.stderr.write(`\x1b[2mdaemon spawned pid=${pid}, waiting for session id…\x1b[0m\n`);
+    const sid = await waitForSession();
+    if (sid) {
+      process.stderr.write(`\x1b[32m✓\x1b[0m ${sid}\n`);
+      process.stderr.write(`  \x1b[2mattach:\x1b[0m bahulam attach ${sid}\n`);
+      process.stderr.write(`  \x1b[2mstop:  \x1b[0m bahulam stop ${sid}\n`);
+      process.exit(0);
+    } else {
+      process.stderr.write(`\x1b[33m! daemon spawned (pid ${pid}) but no session id visible after 15s. Check \`bahulam list\`.\x1b[0m\n`);
+      process.exit(2);
+    }
+  }
+
+  //  auto-attach when a live daemon is bound to this cwd.
+  // Opt-in via BAHULAM_AUTO_ATTACH=1 so existing muscle memory (bahulam →
+  // fresh REPL) isn't disrupted for users who haven't opted into the daemon
+  // model. `bahulam --no-attach` bypasses even with the env var set.
+  const wantsAutoAttach = process.env.BAHULAM_AUTO_ATTACH === '1' && !process.argv.includes('--no-attach');
+  if (wantsAutoAttach && !subcommand) {
+    const { findSessionForCwd } = await import('../daemon/daemonize.mjs');
+    const existing = await findSessionForCwd(process.cwd());
+    if (existing) {
+      process.stderr.write(`\x1b[2mattaching to existing daemon ${existing} (BAHULAM_AUTO_ATTACH)…\x1b[0m\n`);
+      const { attachToSession } = await import('../daemon/attach-client.mjs');
+      const code = await attachToSession(existing);
+      process.exit(code || 0);
+    }
+  }
+
+  // ── Headless mode (benchmarks, automation, daemonize) ──
   const args = parseArgs(process.argv.slice(2));
-  if (args.prompt && (process.argv.includes('--headless') || !process.stdin.isTTY)) {
+  // Slice D: when this process is a spawned daemon (via
+  // `bahulam daemonize`), pull the initial prompt from the env var
+  // rather than argv — child was spawned with stdio: 'ignore' and no
+  // shell args. BAHULAM_DAEMON_SPAWNED=1 is set by daemonize.mjs.
+  const daemonSpawned = process.env.BAHULAM_DAEMON_SPAWNED === '1';
+  const daemonPrompt = daemonSpawned ? (process.env.BAHULAM_DAEMON_INITIAL_PROMPT || '').trim() : '';
+  const effectivePrompt = args.prompt || (daemonSpawned && daemonPrompt) || '';
+  if (effectivePrompt && (daemonSpawned || process.argv.includes('--headless') || !process.stdin.isTTY)) {
     const { runHeadless } = await import('../core/headless.mjs');
     await runHeadless({
-      instruction: args.prompt,
+      instruction: effectivePrompt,
       model: args.model,
       timeout: args.timeout || (args.maxTurns ? args.maxTurns * 60 : 600),
       verbose: args.verbose,