open-claude-p 1.0.0

package/src/completion/detector.js

@@ -0,0 +1,163 @@
+// Response-completion detector.
+//
+// Combines three signals to decide when a request's response is finished:
+//
+//   1. Sentinel match (gated). A sentinel event with the request's nonce
+//      counts only if `assistant-region-entered` has already fired,
+//      ignoring the pre-response echo of the prompt input (see §7.1).
+//      After a sentinel match we still wait `idleMs` for any trailing
+//      output before declaring completion.
+//
+//   2. Idle silence. If at least one assistant-text event has fired and
+//      `idleMs` elapses without further events, complete with reason
+//      'idle' (defensive fallback when the sentinel is dropped).
+//
+//   3. Hard timeout. Always completes after `maxResponseMs` to bound
+//      worst-case wait.
+//
+// `cancel()` short-circuits to completion with `reason='cancelled'`,
+// `isError=true`.
+//
+// Completion is reported by the promise returned from `done()`.
+
+export class CompletionDetector {
+  /**
+   * @param {object} opts
+   * @param {string} opts.nonce             per-request sentinel nonce
+   * @param {number} [opts.idleMs=1500]     idle silence after a sentinel
+   *                                        match, before declaring done
+   * @param {number} [opts.preIdleMs=8000]  idle silence BEFORE sentinel,
+   *                                        used as a defensive fallback
+   *                                        when the model drops the marker.
+   * @param {number} [opts.maxResponseMs=60000]
+   * @param {number} [opts.maxTurns]        max number of assistant turns
+   *                                        before the request is aborted
+   *                                        (shim-enforced `--max-turns`).
+   *                                        Each `⏺` region counts as one
+   *                                        turn; when the (N+1)th turn
+   *                                        opens, the request is aborted
+   *                                        with reason 'max-turns'.
+   */
+  constructor({
+    nonce,
+    idleMs = 1500,
+    preIdleMs = 8000,
+    maxResponseMs = 60000,
+    maxTurns,
+  } = {}) {
+    if (!nonce) throw new Error('CompletionDetector: nonce is required');
+    this.nonce = nonce;
+    this.idleMs = idleMs;
+    this.preIdleMs = preIdleMs;
+    this.maxResponseMs = maxResponseMs;
+    this.maxTurns = Number.isFinite(maxTurns) && maxTurns >= 0 ? maxTurns : null;
+
+    this.startTime = Date.now();
+    this.regionEntered = false;
+    this.hadAssistantText = false;
+    this.sentinelMatched = false;
+    this.turnsEntered = 0;
+    this.lastEventTime = this.startTime;
+
+    this.completion = null;
+    this._resolve = null;
+    this._promise = new Promise((r) => { this._resolve = r; });
+
+    this._tick = setInterval(() => this._onTick(), 100);
+    this._hardTimeout = setTimeout(
+      () => this._complete('timeout', true),
+      this.maxResponseMs,
+    );
+  }
+
+  /**
+   * Mark generic activity (e.g. a raw PTY data chunk that produced no
+   * events). Without this, a slow-streaming response that emits no
+   * intermediate events between `assistant-region-entered` and `sentinel`
+   * can trip the idle fallback prematurely — for example when the upstream
+   * CLI is rendering long conversation history during a `--resume`.
+   */
+  markActivity() {
+    if (this.completion) return;
+    this.lastEventTime = Date.now();
+  }
+
+  /** Feed a parsed event into the detector. */
+  onEvent(e) {
+    if (this.completion) return;
+    this.lastEventTime = Date.now();
+
+    if (e.type === 'assistant-region-entered') {
+      this.regionEntered = true;
+      this.hadAssistantText = true;
+      this.turnsEntered += 1;
+      if (this.maxTurns !== null && this.turnsEntered > this.maxTurns) {
+        this._complete('max-turns', true);
+      }
+      return;
+    }
+
+    if (
+      e.type === 'sentinel' &&
+      e.nonce === this.nonce &&
+      this.regionEntered
+    ) {
+      // Any post-region sentinel match counts. We do NOT complete here
+      // because, in `--resume` workflows, both the prompt-echo and the
+      // model's real response can carry the same nonce. Instead we just
+      // flip sentinelMatched and let the tick-based idle window decide:
+      // completion fires only after `idleMs` of true silence — which means
+      // all subsequent sentinels (including any later "real" one) have
+      // already arrived. The text extractor then uses the LAST sentinel
+      // occurrence in the buffer to find the response.
+      this.sentinelMatched = true;
+    }
+  }
+
+  /**
+   * Cancel from the outside (AbortSignal, SIGINT, upstream exit, …).
+   * @param {string} [reason='cancelled']
+   */
+  cancel(reason = 'cancelled') {
+    this._complete(reason, true);
+  }
+
+  /** Resolves once a completion decision has been reached. */
+  done() {
+    return this._promise;
+  }
+
+  // ── internal ─────────────────────────────────────────────────────────
+  _onTick() {
+    if (this.completion) return;
+    const idleFor = Date.now() - this.lastEventTime;
+    if (this.sentinelMatched) {
+      // Once we've seen at least one post-region sentinel, complete after
+      // `idleMs` of true silence (any chunk resets via markActivity()).
+      if (idleFor >= this.idleMs) {
+        this._complete('sentinel', false);
+      }
+      return;
+    }
+    // Pre-sentinel fallback: only valid once we've seen any assistant
+    // signal, with the longer `preIdleMs` threshold so that brief render
+    // pauses (common during `--resume`) do not trip premature completion.
+    if (this.hadAssistantText) {
+      if (idleFor >= this.preIdleMs) {
+        this._complete('idle', false);
+      }
+    }
+  }
+
+  _complete(reason, isError) {
+    if (this.completion) return;
+    this.completion = { reason, isError };
+    clearInterval(this._tick);
+    clearTimeout(this._hardTimeout);
+    this._resolve({
+      reason,
+      isError,
+      durationMs: Date.now() - this.startTime,
+    });
+  }
+}

package/src/daemon/client.js

@@ -0,0 +1,172 @@
+// Daemon client — connects to the running daemon or starts one.
+//
+// sendToDaemon(sockPath, req, daemonOpts, key):
+//   1. Try to connect to an existing daemon (IDLE state).
+//   2. If no daemon: read state file for resumeSessionId (INACTIVE state),
+//      spawn daemon, wait for ready signal, retry.
+//   3. Send request JSON, receive result JSON.
+
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { OCP_DIR, ensureOcpDir, readState } from './socket.js';
+
+const DEFAULT_MAX_DAEMONS = 30;
+
+const SERVER_JS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'server.js');
+
+/**
+ * @param {string} sockPath
+ * @param {object} req        request body forwarded to driver.runOneShot
+ * @param {object} daemonOpts options passed to the daemon on first start
+ * @param {string} key        daemon key (for state file lookup)
+ * @returns {Promise<object>} result from the daemon
+ */
+export async function sendToDaemon(sockPath, req, daemonOpts, key) {
+  await ensureOcpDir();
+
+  // Happy path — daemon already IDLE.
+  try {
+    return await sendOnSocket(sockPath, req);
+  } catch (e) {
+    if (e.code !== 'ENOENT' && e.code !== 'ECONNREFUSED') throw e;
+  }
+
+  // No daemon running — check for INACTIVE state (saved sessionId).
+  const state = await readState(key);
+  const resumeSessionId = state?.sessionId ?? null;
+
+  await startDaemon(sockPath, key, { ...daemonOpts, resumeSessionId });
+
+  return await sendOnSocket(sockPath, req);
+}
+
+// ── internals ─────────────────────────────────────────────────────────────
+
+// Cap the response we'll buffer from the daemon. The daemon is same-uid
+// trust but a corrupted / malicious / squatting socket could trickle MB
+// of bytes without ending and OOM the client. 64 MiB is well above any
+// legitimate response (events array + stalledOutputTail + diagnostics)
+// while bounding the worst case.
+function envPositiveIntLocal(name, fallback) {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+const MAX_DAEMON_RESPONSE_BYTES = envPositiveIntLocal('OCP_DAEMON_MAX_RESPONSE_BYTES', 64 * 1024 * 1024);
+
+function sendOnSocket(sockPath, req) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(sockPath);
+    let buf = '';
+    let recv = 0;
+    let killed = false;
+
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+      socket.write(JSON.stringify(req));
+      socket.end(); // signal end of request (server reads until 'end')
+    });
+    socket.on('data', (c) => {
+      if (killed) return;
+      // `setEncoding('utf8')` makes `c` a string of code units, which
+      // can be up to 4× lighter than the actual byte cost of multibyte
+      // characters. Use Buffer.byteLength so the cap is an honest byte
+      // cap, not a code-unit approximation.
+      recv += Buffer.byteLength(c, 'utf8');
+      if (recv > MAX_DAEMON_RESPONSE_BYTES) {
+        killed = true;
+        try { socket.destroy(); } catch {}
+        const e = new Error(`daemon response exceeded ${MAX_DAEMON_RESPONSE_BYTES} bytes; refusing to buffer further`);
+        e.code = 'ERR_DAEMON_RESPONSE_TOO_LARGE';
+        reject(e);
+        return;
+      }
+      buf += c;
+    });
+    socket.on('end', () => {
+      if (killed) return;
+      try {
+        const result = JSON.parse(buf.trim());
+        if (result.error) {
+          const err = new Error(result.error);
+          err.fromDaemon = true;
+          reject(err);
+        } else {
+          resolve(result);
+        }
+      } catch (e) {
+        // A same-uid peer squatting on the socket path can write any
+        // bytes including C0/C1/DEL/ANSI sequences; JSON.parse's error
+        // message quotes a snippet of that buffer, which would land in
+        // the user's terminal via the CLI's stderr printer and could
+        // re-emit cursor moves or BEL. Scrub before embedding.
+        const rawMsg = e?.message ?? String(e);
+        const safeMsg = String(rawMsg).replace(/[\x00-\x1f\x7f\x80-\x9f]/g, '?').slice(0, 512);
+        reject(new Error(`daemon response parse failed: ${safeMsg}`));
+      }
+    });
+    socket.on('error', reject);
+  });
+}
+
+async function countRunningDaemons() {
+  try {
+    const files = await readdir(OCP_DIR);
+    return files.filter((f) => f.startsWith('d-') && f.endsWith('.sock')).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function startDaemon(sockPath, key, daemonOpts) {
+  // Number(env) → NaN for non-numeric input ("abc", "") and the
+  // `running >= NaN` check silently disables the cap. Coerce via the
+  // same positive-int helper used elsewhere so garbage values fall
+  // back to DEFAULT_MAX_DAEMONS instead of unbounded growth.
+  const rawLimit = process.env.OCP_MAX_DAEMONS;
+  const parsed = Number(rawLimit);
+  const limit = (Number.isFinite(parsed) && parsed > 0) ? Math.floor(parsed) : DEFAULT_MAX_DAEMONS;
+  const running = await countRunningDaemons();
+  if (running >= limit) {
+    throw new Error(
+      `terminal limit reached: ${running}/${limit} sessions are active or idle.\n` +
+      `Stop unused sessions or raise the limit with OCP_MAX_DAEMONS=<n>.`,
+    );
+  }
+
+  const child = spawn(
+    process.execPath,
+    [SERVER_JS, sockPath, key, JSON.stringify(daemonOpts)],
+    {
+      detached: true,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    },
+  );
+
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error('daemon start timeout (10s)')),
+      10_000,
+    );
+    let buf = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (c) => {
+      buf += c;
+      if (buf.includes('ready')) {
+        clearTimeout(timer);
+        resolve();
+      }
+    });
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('exit', (code) => {
+      if (code !== 0 && code !== null) {
+        clearTimeout(timer);
+        reject(new Error(`daemon exited early (code ${code})`));
+      }
+    });
+  });
+
+  child.unref(); // let daemon outlive this process
+}

package/src/daemon/server.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Daemon server — manages a single claude PTY and keeps it alive between
+// ocp invocations.
+//
+// Lifecycle states (as seen from outside):
+//   ACTIVE   — currently processing a request
+//   IDLE     — PTY running in background, waiting for next command (timer active)
+//   INACTIVE — daemon exited, sessionId saved to state file for --resume
+//
+// Started by src/daemon/client.js. Do not run directly.
+// argv: <socketPath> <key> <daemonOptsJSON>
+
+import net from 'node:net';
+import { unlink, chmod } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { createDriver } from '../index.js';
+import { writeState, clearState, resolveCwd } from './socket.js';
+import { recordSession } from '../session-log.js';
+
+const [,, socketPath, key, optsJson] = process.argv;
+if (!socketPath || !key) { process.stderr.write('daemon: missing args\n'); process.exit(1); }
+
+// A long-lived daemon must not die to an unhandled rejection — log and
+// exit cleanly so the next client invocation spawns a fresh one rather
+// than connecting to a half-dead socket.
+process.on('unhandledRejection', (r) => {
+  process.stderr.write(`[ocp-daemon] unhandled rejection: ${r?.stack || r?.message || r}\n`);
+  process.exit(1);
+});
+process.on('uncaughtException', (e) => {
+  process.stderr.write(`[ocp-daemon] uncaught exception: ${e?.stack || e?.message || e}\n`);
+  process.exit(1);
+});
+
+// Refuse to honour the global argv-sanitizer opt-out inside the daemon.
+// The daemon is long-lived and shared across invocations — letting it
+// inherit OCP_ALLOW_UNSAFE_ARGV from whichever shell first started it
+// creates a surprise-bypass for subsequent unrelated clients. Callers
+// that genuinely need the opt-out must run with OCP_NO_DAEMON=1 to take
+// the direct path.
+delete process.env.OCP_ALLOW_UNSAFE_ARGV;
+
+const opts = JSON.parse(optsJson ?? '{}');
+
+function envPositiveInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+// Default 10-minute idle timeout. Each incoming request resets the timer.
+// Guard against malformed env (NaN / negative / empty) collapsing the timer
+// to zero and defeating the daemon's purpose.
+const IDLE_MS = envPositiveInt('OCP_DAEMON_IDLE_MS', 600_000);
+
+// Cap a single IPC request body. A same-user process flooding the socket
+// could otherwise OOM the daemon by streaming bytes without ever ending
+// the message.
+const MAX_REQ_BYTES = envPositiveInt('OCP_DAEMON_MAX_REQ_BYTES', 4 * 1024 * 1024);
+const SOCKET_IDLE_MS = envPositiveInt('OCP_DAEMON_SOCKET_TIMEOUT_MS', 30_000);
+// Total lifetime cap on a single connection — guards against slow-loris
+// where a peer trickles bytes just often enough to keep idle timeout
+// from firing. Five minutes is far longer than any legitimate request.
+const SOCKET_MAX_LIFETIME_MS = envPositiveInt('OCP_DAEMON_SOCKET_MAX_LIFETIME_MS', 300_000);
+
+// Pool size = max number of warm PTYs the daemon can park concurrently.
+// Set to MAX_PARALLEL so concurrent fresh requests (no resume/session-id)
+// can all park their PTYs on release rather than being killed because the
+// pool was full — the next round of fresh calls then gets warm reuse.
+// The pool TTL is set longer than the daemon's idle timer so the pool
+// never kills the PTY independently — the daemon's own timer controls
+// shutdown.
+const MAX_PARALLEL = envPositiveInt('OCP_DAEMON_MAX_PARALLEL', 8);
+const driver = createDriver({
+  claudeBin: opts.claudeBin,
+  cwd: opts.cwd,
+  debug: opts.debug,
+  poolSize: MAX_PARALLEL,
+  poolMaxAgeMs: IDLE_MS + 60_000,
+  initialSessionId: opts.resumeSessionId ?? null,
+});
+
+let lastSessionId = opts.resumeSessionId ?? null;
+let idleTimer;
+
+function resetIdle() {
+  clearTimeout(idleTimer);
+  idleTimer = setTimeout(async () => {
+    // IDLE → INACTIVE: save session for future --resume, then exit.
+    await saveStateAndExit();
+  }, IDLE_MS);
+  if (idleTimer.unref) idleTimer.unref();
+}
+
+async function saveStateAndExit() {
+  if (lastSessionId) {
+    await writeState(key, { sessionId: lastSessionId, exitedAt: Date.now() }).catch(() => {});
+  }
+  await driver.close().catch(() => {});
+  try { await unlink(socketPath); } catch {}
+  process.exit(0);
+}
+
+process.on('SIGTERM', saveStateAndExit);
+process.on('SIGINT',  saveStateAndExit);
+
+resetIdle();
+
+// Per-session-key serialisation. The original design used a single
+// global `pending` chain, which forced concurrent fresh `ocp` calls in
+// the same directory to wait for each other even though they had no
+// session relationship. The user-visible symptom was "I opened two
+// terminals and ran `ocp` in each, the second hangs until the first
+// finishes". Replace with a per-key Map:
+//
+//   - `resume:<sessionId>` — `--resume <id>` requests serialise per id
+//   - `session:<sessionId>` — `--session-id <id>` requests serialise per id
+//   - `continue` — `--continue` requests serialise (single shared context)
+//   - `fresh:<uuid>` — plain `ocp "..."` calls each get a unique key →
+//     never collide → run in parallel up to MAX_PARALLEL
+//
+// MAX_PENDING is the cross-cutting ceiling so a runaway same-uid peer
+// can't spawn unbounded in-flight runs.
+const pendingByKey = new Map();
+let pendingCount = 0;
+const MAX_PENDING = envPositiveInt('OCP_DAEMON_MAX_PENDING', 16);
+
+function keyForRequest(req) {
+  if (req?.resume) return `resume:${req.resume}`;
+  if (req?.sessionId) return `session:${req.sessionId}`;
+  if (req?.continue) return 'continue';
+  return `fresh:${randomUUID()}`;
+}
+
+const server = net.createServer((socket) => {
+  resetIdle(); // IDLE → ACTIVE: reset timer on new connection
+  let buf = '';
+  let recv = 0;
+  let killed = false;
+  socket.setEncoding('utf8');
+  socket.setTimeout(SOCKET_IDLE_MS, () => { killed = true; socket.destroy(); });
+  const lifetimeKill = setTimeout(() => {
+    killed = true;
+    try { socket.destroy(); } catch {}
+  }, SOCKET_MAX_LIFETIME_MS);
+  if (lifetimeKill.unref) lifetimeKill.unref();
+  socket.once('close', () => clearTimeout(lifetimeKill));
+  socket.on('data', (c) => {
+    if (killed) return;
+    recv += c.length;
+    if (recv > MAX_REQ_BYTES) { killed = true; socket.destroy(); return; }
+    buf += c;
+  });
+  socket.on('end', async () => {
+    if (killed) return;
+    let req;
+    try { req = JSON.parse(buf); } catch {
+      // Do not echo the parse-error message back — it may contain a
+      // byte-offset into attacker-controlled input. A generic code is
+      // enough for legitimate clients to retry.
+      socket.write(JSON.stringify({ error: 'bad json' }) + '\n');
+      socket.end(); return;
+    }
+    // Per-request cwd must match the cwd this daemon was spawned for.
+    // Otherwise a same-uid peer could reuse our socket to spawn claude
+    // in a different directory and influence which `~/.claude/projects/`
+    // files get written.
+    //
+    // Both sides are normalised via realpath so a symlink path and its
+    // target compare equal. A missing req.cwd is rejected outright
+    // (legitimate clients always set it) so an attacker cannot bypass
+    // by simply omitting the field.
+    const boundCwd = resolveCwd(opts.cwd);
+    if (req.cwd === undefined) {
+      socket.write(JSON.stringify({ error: 'cwd required' }) + '\n');
+      socket.end(); return;
+    }
+    if (resolveCwd(req.cwd) !== boundCwd) {
+      socket.write(JSON.stringify({ error: 'cwd mismatch' }) + '\n');
+      socket.end(); return;
+    }
+    // Mirror the cwd check for claudeBin — a same-uid peer connecting
+    // directly to our socket could otherwise issue requests intended
+    // for a DIFFERENT claude binary and silently get this daemon's
+    // bound one instead. The daemonKey already includes claudeBin so
+    // legitimate clients land on different sockets; this catches the
+    // direct-socket bypass.
+    const boundBin = opts.claudeBin || 'claude';
+    if (req.claudeBin !== undefined && req.claudeBin !== boundBin) {
+      socket.write(JSON.stringify({ error: 'claudeBin mismatch' }) + '\n');
+      socket.end(); return;
+    }
+    if (pendingCount >= MAX_PENDING) {
+      socket.write(JSON.stringify({ error: 'busy' }) + '\n');
+      socket.end(); return;
+    }
+    pendingCount += 1;
+
+    const processRequest = async () => {
+      try {
+        resetIdle();
+
+        const result = await driver.runOneShot(req);
+        if (result.sessionId) lastSessionId = result.sessionId;
+
+        // Active conversation running — no need for the INACTIVE state file.
+        await clearState(key).catch(() => {});
+
+        // Per-turn log under <cwd>/.ocp/<sessionId>/. Best-effort; any
+        // failure is captured inside recordSession and never propagates.
+        recordSession({
+          cwd: req.cwd,
+          sessionId: result.sessionId,
+          prompt: req.prompt,
+          response: result.text,
+          meta: {
+            isError: result.isError,
+            completionReason: result.completionReason,
+            durationMs: result.durationMs,
+            cost: result.cost,
+          },
+          events: result.events,
+        }).catch(() => {});
+
+        socket.write(JSON.stringify({
+          text: result.text,
+          sessionId: result.sessionId,
+          isError: result.isError,
+          completionReason: result.completionReason,
+          durationMs: result.durationMs,
+          cost: result.cost,
+          events: result.events,
+          diagnostics: result.diagnostics,
+        }) + '\n');
+      } catch (e) {
+        // Log full error locally; return only a generic code to the peer
+        // so absolute paths / homedir / internal symbols don't leak via IPC.
+        process.stderr.write(`[ocp-daemon] request failed: ${e.stack || e.message}\n`);
+        socket.write(JSON.stringify({ error: 'request failed' }) + '\n');
+      }
+      socket.end();
+      // ACTIVE → IDLE: idle timer was reset at start of this handler
+    };
+
+    const sessionKey = keyForRequest(req);
+    const prev = pendingByKey.get(sessionKey) ?? Promise.resolve();
+    const next = prev
+      .then(processRequest)
+      .catch((e) => process.stderr.write(`[ocp-daemon] queue handler crashed: ${e?.stack || e?.message}\n`))
+      .finally(() => {
+        // Only delete the slot if we're still the tail — a queued
+        // sibling may have already chained off `next`.
+        if (pendingByKey.get(sessionKey) === next) pendingByKey.delete(sessionKey);
+        pendingCount -= 1;
+      });
+    pendingByKey.set(sessionKey, next);
+  });
+});
+
+server.listen(socketPath, async () => {
+  // Restrict the unix socket to the owning user — defense in depth on
+  // multi-user hosts so other local accounts cannot inject argv via IPC.
+  try { await chmod(socketPath, 0o600); } catch {}
+  // Signal parent (client.js) that the socket is ready.
+  process.stdout.write('ready\n');
+});

package/src/daemon/socket.js

@@ -0,0 +1,78 @@
+// Shared utilities: socket path, state file, daemon key.
+//
+// One daemon per (cwd, claudeBin) pair. Per-request options like --model
+// are forwarded in the request body and handled by the pool internally.
+
+import os from 'node:os';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+import { mkdir, readFile, writeFile, unlink, chmod, stat } from 'node:fs/promises';
+
+export const OCP_DIR = path.join(os.homedir(), '.ocp');
+
+export async function ensureOcpDir() {
+  await mkdir(OCP_DIR, { recursive: true, mode: 0o700 });
+  // mkdir with `recursive: true` does NOT apply mode to an existing dir,
+  // so chmod separately in case it was created earlier with default perms.
+  try { await chmod(OCP_DIR, 0o700); } catch {}
+  // If the directory exists but is owned by another uid (e.g. a prior
+  // sudo invocation), every later write fails silently and ocp keeps
+  // falling back to direct mode on every call with no diagnosis. Surface
+  // the actual cause once, fast.
+  if (process.getuid) {
+    try {
+      const st = await stat(OCP_DIR);
+      if (st.uid !== process.getuid()) {
+        throw new Error(
+          `~/.ocp is owned by uid ${st.uid}, not ${process.getuid()}. ` +
+          `Run \`sudo chown -R $USER ~/.ocp\` (or remove the directory) and retry.`,
+        );
+      }
+    } catch (e) {
+      if (e.message?.startsWith('~/.ocp is owned')) throw e;
+      // stat ENOENT is impossible right after mkdir; other errors fall through.
+    }
+  }
+}
+
+export function resolveCwd(cwd) {
+  const target = cwd ?? process.cwd();
+  try { return realpathSync(target); }
+  catch { return path.resolve(target); }
+}
+
+/** Stable key that identifies a daemon instance. */
+export function daemonKey({ cwd, claudeBin } = {}) {
+  return JSON.stringify({
+    cwd: resolveCwd(cwd),
+    claudeBin: claudeBin ?? 'claude',
+  });
+}
+
+function hashOf(key) {
+  return crypto.createHash('sha1').update(key).digest('hex').slice(0, 8);
+}
+
+/** Unix socket path for a given daemon key. */
+export function socketPath(key) {
+  return path.join(OCP_DIR, `d-${hashOf(key)}.sock`);
+}
+
+/** State file path — written when daemon goes INACTIVE, read on next start. */
+export function statePath(key) {
+  return path.join(OCP_DIR, `s-${hashOf(key)}.json`);
+}
+
+export async function readState(key) {
+  try { return JSON.parse(await readFile(statePath(key), 'utf8')); } catch { return null; }
+}
+
+export async function writeState(key, state) {
+  await ensureOcpDir();
+  await writeFile(statePath(key), JSON.stringify(state), { encoding: 'utf8', mode: 0o600 });
+}
+
+export async function clearState(key) {
+  try { await unlink(statePath(key)); } catch {}
+}