chainlesschain 0.162.158 → 0.162.159

package/src/lib/background-agent-supervisor.js

@@ -8,6 +8,7 @@ import {
   readdirSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { randomBytes } from "node:crypto";
@@ -61,12 +62,57 @@ export function logPath(id) {
   return join(backgroundAgentsDir(), `${safeId(id)}.log`);
 }
 
+const TERMINAL_STATUSES = new Set(["completed", "failed", "stopped", "lost"]);
+
 export function writeBackgroundAgentState(state) {
   const target = statePath(state.id);
+  // Field-aware merge against the freshest on-disk state. The state file has
+  // multiple concurrent read-modify-write writers (launcher, worker heartbeat/
+  // turn/finalize, rename/pin/stop from other processes) with last-writer-wins
+  // semantics — a writer holding a stale snapshot used to clobber a terminal
+  // status back to "running" (phantom session, real exit code lost) or roll a
+  // fresh rename back to the old title. Two invariants restore convergence:
+  //   1. a terminal status wins over a racing "running" snapshot — there is no
+  //      legitimate same-id terminal→running transition (resume mints a NEW
+  //      id, and the worker's own writeHeartbeat already refuses to resurrect);
+  //   2. the newest rename/pin (by renamedAt/pinnedAt) wins regardless of
+  //      which writer's snapshot carries it.
+  // The read happens immediately before the atomic rename, shrinking the
+  // clobber window from "any caller's RMW span" to microseconds; rename/pin
+  // additionally verify-and-retry on top of this.
+  let next = state;
+  const current = readBackgroundAgentState(state.id);
+  if (current) {
+    if (TERMINAL_STATUSES.has(current.status) && next.status === "running") {
+      next = {
+        ...next,
+        status: current.status,
+        endedAt: current.endedAt ?? next.endedAt ?? null,
+        exitCode: current.exitCode ?? next.exitCode ?? null,
+        ...(current.signal !== undefined ? { signal: current.signal } : {}),
+        ...(current.error !== undefined ? { error: current.error } : {}),
+        ...(current.lostReason !== undefined
+          ? { lostReason: current.lostReason }
+          : {}),
+        ...(current.stoppedByUser !== undefined
+          ? { stoppedByUser: current.stoppedByUser }
+          : {}),
+        // terminal sessions have no live phase or transport endpoint
+        phase: null,
+        transport: null,
+      };
+    }
+    if (Number(current.renamedAt || 0) > Number(next.renamedAt || 0)) {
+      next = { ...next, title: current.title, renamedAt: current.renamedAt };
+    }
+    if (Number(current.pinnedAt || 0) > Number(next.pinnedAt || 0)) {
+      next = { ...next, pinned: current.pinned, pinnedAt: current.pinnedAt };
+    }
+  }
   const tmp = `${target}.${process.pid}.tmp`;
-  writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
   renameSync(tmp, target);
-  return state;
+  return next;
 }
 
 export function readBackgroundAgentState(id) {
@@ -177,6 +223,34 @@ export function renameBackgroundAgent(id, title, options = {}) {
   return next;
 }
 
+/**
+ * Pin/unpin a session for the dashboard (`cc daemon view`) — pinned sessions
+ * sort first inside their group. Same read-modify-write + verify-retry dance
+ * as rename: the worker's periodic state merges can clobber a write that
+ * lands inside its read→write window.
+ */
+export function setBackgroundAgentPinned(id, pinned, options = {}) {
+  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+    now: options.now,
+    heartbeatStaleMs: options.heartbeatStaleMs,
+  });
+  if (!state) throw new Error(`Background agent not found: ${id}`);
+  const value = pinned === true;
+  const pinnedAt = typeof options.now === "number" ? options.now : Date.now();
+  let next = { ...state, pinned: value, pinnedAt };
+  for (let attempt = 0; attempt < 4; attempt++) {
+    writeBackgroundAgentState(next);
+    sleepSyncMs(15);
+    const current = readBackgroundAgentState(id) || next;
+    if (current.pinned === value) {
+      return { ...current, pinned: value, pinnedAt };
+    }
+    next = { ...current, pinned: value, pinnedAt };
+  }
+  writeBackgroundAgentState(next);
+  return next;
+}
+
 /**
  * Build the follow-up argv template for interactive attach turns: the launch
  * argv minus every token that carried the FIRST turn's prompt (positional
@@ -258,6 +332,33 @@ export function resumeBackgroundAgent(id, prompt, options = {}) {
   });
 }
 
+/**
+ * Fail fast on an unusable cwd. Without this, spawn() surfaces a bad cwd as
+ * an ASYNC 'error' event on the detached child — which nothing listened to
+ * (uncaught exception with no context) — and the pre-written state/job files
+ * stayed behind as a phantom "running" session. Deleted, file-replaced, and
+ * unmounted paths all land here with one clear message.
+ */
+function assertUsableCwd(cwd) {
+  let reason = null;
+  if (!cwd) {
+    reason = "no working directory given";
+  } else if (!existsSync(cwd)) {
+    reason = "directory does not exist (deleted or unmounted?)";
+  } else {
+    try {
+      if (!statSync(cwd).isDirectory()) reason = "path is not a directory";
+    } catch (err) {
+      reason = `directory is not accessible (${err.code || err.message})`;
+    }
+  }
+  if (reason) {
+    throw new Error(
+      `Cannot launch background agent: cwd "${cwd ?? ""}" — ${reason}`,
+    );
+  }
+}
+
 export function launchBackgroundAgent({
   argv,
   cwd,
@@ -266,6 +367,7 @@ export function launchBackgroundAgent({
   cliEntry,
   followUpArgv,
 }) {
+  assertUsableCwd(cwd);
   const id = createBackgroundAgentId();
   const dir = backgroundAgentsDir();
   const jobFile = join(dir, `${id}.job.${process.pid}.json`);
@@ -317,6 +419,28 @@ export function launchBackgroundAgent({
     rmSync(statePath(id), { force: true });
     throw error;
   }
+  // Async spawn failures (EPERM, cwd raced away between the check and the
+  // spawn, …) arrive as an 'error' event on the detached child. Reap them
+  // into the state file instead of leaving a phantom "running" session and
+  // an uncaught exception.
+  if (typeof child.on === "function") {
+    child.on("error", (error) => {
+      try {
+        rmSync(jobFile, { force: true });
+        const current = readBackgroundAgentState(id);
+        if (current && current.status === "running") {
+          writeBackgroundAgentState({
+            ...current,
+            status: "failed",
+            endedAt: Date.now(),
+            lostReason: `spawn-error: ${error.code || error.message}`,
+          });
+        }
+      } catch {
+        /* best-effort */
+      }
+    });
+  }
   child.unref();
   const current = readBackgroundAgentState(id) || state;
   const withPid = {

package/src/lib/channels/channel-manager.js

@@ -0,0 +1,126 @@
+/**
+ * Inbound channels — external events entering a running agent session
+ * (gap-2026-07-11 P0#5; Claude-Code "channels" parity, self-hosted).
+ *
+ * `cc agent --channels webhook,telegram` starts channel listeners whose
+ * events become user turns in the interactive session (queued behind any
+ * in-flight turn by the REPL's pending-line queue). Every channel enforces a
+ * trust boundary: webhook = bearer token + loopback-only by default;
+ * telegram = explicit chat-id allowlist (deny-all when unset).
+ *
+ * Outbound replies reuse the existing notifier stack (`notify` agent tool /
+ * NotificationManager) — the inbound event's metadata tells the model which
+ * channel and sender to address.
+ */
+
+import { logger } from "../logger.js";
+
+export const CHANNEL_KINDS = ["webhook", "telegram"];
+
+/**
+ * Parse `--channels` input: "webhook,telegram", "webhook:18901", or an array.
+ * @returns {Array<{kind:string, arg:string|null}>}
+ */
+export function parseChannelSpecs(input) {
+  const items = Array.isArray(input)
+    ? input
+    : String(input || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+  return items.map((item) => {
+    const idx = item.indexOf(":");
+    const kind = (idx === -1 ? item : item.slice(0, idx)).toLowerCase();
+    const arg = idx === -1 ? null : item.slice(idx + 1);
+    if (!CHANNEL_KINDS.includes(kind)) {
+      throw new Error(
+        `Unknown channel "${kind}" — supported: ${CHANNEL_KINDS.join(", ")}`,
+      );
+    }
+    return { kind, arg };
+  });
+}
+
+/**
+ * Render a channel event as the user-turn text. The channel/sender prefix
+ * keeps provenance visible to the model AND guarantees the line can never be
+ * mistaken for a REPL slash command or `!` shell escape, no matter what the
+ * external sender wrote.
+ */
+export function formatChannelEvent(event) {
+  const channel = event?.channel || "channel";
+  const sender = event?.sender ? ` from ${event.sender}` : "";
+  const text = String(event?.text ?? "").trim();
+  return `[channel:${channel}${sender}] ${text}`;
+}
+
+/**
+ * Start every requested channel. Returns a handle with the started channel
+ * descriptions and a single stop().
+ *
+ * @param {string|string[]} specsInput --channels value
+ * @param {object} opts
+ * @param {(event) => void} opts.onEvent   called for each inbound event
+ * @param {object} [opts.config]           loadConfig().channels subtree
+ * @param {object} [opts.deps]             channel starters (tests inject)
+ */
+export async function startChannels(specsInput, opts = {}) {
+  const specs = parseChannelSpecs(specsInput);
+  if (specs.length === 0) {
+    throw new Error("--channels given but no channel names parsed");
+  }
+  const config = opts.config || {};
+  const log = opts.log || ((msg) => logger.info(msg));
+  const deps = opts.deps || {};
+
+  const started = [];
+  const stopAll = () => {
+    for (const c of started) {
+      try {
+        c.stop?.();
+      } catch {
+        /* best-effort */
+      }
+    }
+  };
+
+  try {
+    for (const spec of specs) {
+      if (spec.kind === "webhook") {
+        const { startWebhookChannel } =
+          deps.webhook || (await import("./webhook-channel.js"));
+        const cfg = config.webhook || {};
+        const handle = await (
+          deps.webhook?.startWebhookChannel || startWebhookChannel
+        )({
+          ...cfg,
+          port: spec.arg ? Number(spec.arg) : cfg.port,
+          onEvent: opts.onEvent,
+          log,
+        });
+        started.push({ kind: "webhook", describe: handle.describe, ...handle });
+      } else if (spec.kind === "telegram") {
+        const { startTelegramChannel } =
+          deps.telegram || (await import("./telegram-channel.js"));
+        const cfg = config.telegram || {};
+        const handle = await (
+          deps.telegram?.startTelegramChannel || startTelegramChannel
+        )({
+          ...cfg,
+          onEvent: opts.onEvent,
+          log,
+        });
+        started.push({
+          kind: "telegram",
+          describe: handle.describe,
+          ...handle,
+        });
+      }
+    }
+  } catch (err) {
+    stopAll(); // never leave half the channels listening after a failure
+    throw err;
+  }
+
+  return { channels: started, stop: stopAll };
+}

package/src/lib/channels/telegram-channel.js

@@ -0,0 +1,112 @@
+/**
+ * Telegram inbound channel — long-polls the Bot API (`getUpdates`) so no
+ * public endpoint is needed, and turns allowed chats' messages into session
+ * events.
+ *
+ * Trust boundary: `allowFrom` (array of chat ids) is REQUIRED — an inbound
+ * channel with no allowlist would let anyone who finds the bot drive the
+ * agent, so an empty/missing allowlist denies every update (fail closed).
+ *
+ * Replies: `handle.reply(event, text)` posts a sendMessage back to the
+ * event's chat. fetch is injectable for tests.
+ */
+
+const POLL_TIMEOUT_S = 25;
+const ERROR_BACKOFF_MS = 5000;
+
+export async function startTelegramChannel(options = {}) {
+  const {
+    botToken = process.env.TELEGRAM_BOT_TOKEN,
+    allowFrom,
+    onEvent,
+    log = () => {},
+    fetchImpl = globalThis.fetch,
+    pollTimeoutS = POLL_TIMEOUT_S,
+    // Real macrotask pause between polls. The server-side long-poll dominates
+    // in production; this exists so a fast-resolving fetch (tests, HTTP-level
+    // failures) can never turn the loop into a microtask chain that starves
+    // the event loop (timers, stop()) entirely.
+    pollPauseMs = 50,
+  } = options;
+
+  if (!botToken) {
+    throw new Error(
+      "telegram channel needs a bot token (channels.telegram.botToken or TELEGRAM_BOT_TOKEN)",
+    );
+  }
+  const allowed = new Set((allowFrom || []).map((id) => String(id)));
+  if (allowed.size === 0) {
+    throw new Error(
+      "telegram channel needs channels.telegram.allowFrom (chat-id allowlist) — refusing to listen to everyone",
+    );
+  }
+
+  const api = (method) => `https://api.telegram.org/bot${botToken}/${method}`;
+  let stopped = false;
+  let offset = 0;
+
+  async function poll() {
+    while (!stopped) {
+      try {
+        const res = await fetchImpl(api("getUpdates"), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ timeout: pollTimeoutS, offset }),
+        });
+        const data = await res.json();
+        if (!data?.ok || !Array.isArray(data.result)) {
+          throw new Error(data?.description || `getUpdates HTTP ${res.status}`);
+        }
+        for (const update of data.result) {
+          offset = Math.max(offset, Number(update.update_id) + 1);
+          const msg = update.message || update.edited_message;
+          const chatId = msg?.chat?.id;
+          const text = typeof msg?.text === "string" ? msg.text.trim() : "";
+          if (!chatId || !text) continue;
+          if (!allowed.has(String(chatId))) continue; // fail closed
+          try {
+            onEvent?.({
+              channel: "telegram",
+              sender: String(chatId),
+              text,
+              meta: { updateId: update.update_id },
+            });
+          } catch {
+            /* downstream owns its failures */
+          }
+        }
+      } catch (err) {
+        if (stopped) return;
+        log(`channel telegram poll error: ${err.message} — backing off`);
+        await new Promise((r) => setTimeout(r, ERROR_BACKOFF_MS));
+      }
+      if (!stopped) {
+        await new Promise((r) => setTimeout(r, pollPauseMs));
+      }
+    }
+  }
+  const pollPromise = poll();
+
+  log(`channel telegram polling (allowlist: ${[...allowed].join(", ")})`);
+
+  return {
+    kind: "telegram",
+    describe: `telegram (${allowed.size} allowed chat${allowed.size === 1 ? "" : "s"})`,
+    async reply(event, text) {
+      const res = await fetchImpl(api("sendMessage"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ chat_id: event.sender, text }),
+      });
+      const data = await res.json();
+      if (!data?.ok) {
+        throw new Error(data?.description || `sendMessage HTTP ${res.status}`);
+      }
+      return true;
+    },
+    stop: () => {
+      stopped = true;
+      return pollPromise.catch(() => {});
+    },
+  };
+}

package/src/lib/channels/webhook-channel.js

@@ -0,0 +1,140 @@
+/**
+ * Webhook inbound channel — a tiny loopback HTTP listener that turns
+ * authenticated POSTs into session events.
+ *
+ *   POST /v1/event
+ *   Authorization: Bearer <token>
+ *   { "text": "deploy finished", "sender": "ci", "meta": {...} }
+ *
+ * Trust boundary:
+ * - bearer token REQUIRED on every request; without a configured token a
+ *   random one is generated and printed once at startup (pairing secret).
+ * - binds 127.0.0.1 unless `allowExternal: true` is explicitly configured
+ *   (same LAN/loopback posture as remote-control direct pairing).
+ * - optional `allowlist` of sender ids — configured ⇒ only those senders.
+ * - body capped at 64 KB; JSON only.
+ */
+
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+function tokenMatches(expected, got) {
+  const a = Buffer.from(String(expected));
+  const b = Buffer.from(String(got || ""));
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export async function startWebhookChannel(options = {}) {
+  const {
+    port = 18901,
+    host = "127.0.0.1",
+    allowExternal = false,
+    allowlist,
+    onEvent,
+    log = () => {},
+  } = options;
+
+  const isLoopback =
+    host === "127.0.0.1" || host === "::1" || host === "localhost";
+  if (!isLoopback && allowExternal !== true) {
+    throw new Error(
+      `webhook channel refuses to bind non-loopback host "${host}" without channels.webhook.allowExternal=true`,
+    );
+  }
+
+  const token = options.token || randomBytes(24).toString("base64url");
+  const generated = !options.token;
+
+  const server = createServer((req, res) => {
+    const respond = (status, body) => {
+      res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+
+    if (req.method !== "POST" || req.url !== "/v1/event") {
+      return respond(404, { error: "not found" });
+    }
+    const auth = String(req.headers.authorization || "");
+    const got = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+    if (!tokenMatches(token, got)) {
+      return respond(401, { error: "unauthorized" });
+    }
+
+    let size = 0;
+    const chunks = [];
+    let aborted = false;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        aborted = true;
+        respond(413, { error: "body too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (aborted) return;
+      let payload;
+      try {
+        payload = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+      } catch {
+        return respond(400, { error: "invalid JSON" });
+      }
+      const text = typeof payload?.text === "string" ? payload.text.trim() : "";
+      if (!text) return respond(400, { error: "missing text" });
+      const sender =
+        typeof payload.sender === "string" ? payload.sender : "webhook";
+      if (Array.isArray(allowlist) && allowlist.length > 0) {
+        if (!allowlist.includes(sender)) {
+          return respond(403, { error: "sender not in allowlist" });
+        }
+      }
+      try {
+        onEvent?.({
+          channel: "webhook",
+          sender,
+          text,
+          meta:
+            payload.meta && typeof payload.meta === "object"
+              ? payload.meta
+              : undefined,
+        });
+      } catch {
+        /* the session queue owns downstream failures */
+      }
+      respond(202, { ok: true });
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, resolve);
+  });
+  server.unref?.();
+
+  const actualPort = server.address()?.port ?? port;
+  const url = `http://${host}:${actualPort}/v1/event`;
+  log(
+    `channel webhook listening on ${url}` +
+      (generated ? ` (generated token: ${token})` : ""),
+  );
+
+  return {
+    kind: "webhook",
+    url,
+    port: actualPort,
+    token,
+    describe: `webhook ${url}`,
+    stop: () =>
+      new Promise((resolve) => {
+        try {
+          server.close(() => resolve());
+        } catch {
+          resolve();
+        }
+      }),
+  };
+}