@jive-sh/skill-sync 0.3.2-latest-darwin-x64 → 0.3.2

package/src/internal/config.ts

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { homedir, hostname, userInfo } from "node:os";
+import { join, relative, sep } from "node:path";
+
+/**
+ * Per-machine settings and sync state, both under `~/.jive/`. The sync token is not here: it lives only in
+ * the running daemon's memory.
+ *
+ * A file rather than environment variables: the endpoint and which machine this is differ per computer
+ * and have to survive a login, which is exactly what a config file is for and exactly what an environment
+ * variable is not. Which folders to sync is not in here: they are detected, and the choice to leave one
+ * out is kept on the server so the dashboard can change it and a reinstalled daemon still remembers it.
+ */
+
+const JIVE_HOME = join(homedir(), ".jive");
+export const CONFIG_PATH = join(JIVE_HOME, "skill-sync.json");
+const STATE_PATH = join(JIVE_HOME, "skill-sync-state.json");
+/**
+ * Where versions before 0.3 kept the sync token. The token now lives only in the running daemon's memory,
+ * so the daemon deletes this file whenever it finds one: a credential left on disk is one anything that
+ * can read the home directory can copy.
+ */
+export const LEGACY_TOKEN_PATH = join(homedir(), ".skill-sync-token.json");
+/**
+ * How the CLI reaches the running daemon: a Unix socket in `~/.jive/`, or a named pipe on Windows. Only
+ * this user can open either, which is what lets the CLI hand the daemon work that involves the token.
+ */
+export const CONTROL_SOCKET = process.platform === "win32"
+  ? `\\\\.\\pipe\\jive-skill-sync-${userInfo().username}`
+  : join(JIVE_HOME, "skill-sync.sock");
+
+/** Managed by Claude's own cloud sync; see `Settings.exclude`. */
+const DEFAULT_EXCLUDE = ["synced"] as const;
+
+/** What `~/.jive/skill-sync.json` holds: nothing secret, so it can live in a file. */
+export interface Settings {
+  readonly endpoint: string;
+  /**
+   * Top-level directory names under each synced folder to leave alone.
+   *
+   * `synced` holds the skills Claude already pulls from the cloud itself. Syncing them here would mean
+   * two systems writing the same files, each undoing the other, and none of them are yours to edit.
+   */
+  readonly exclude: ReadonlyArray<string>;
+  /** Names this machine in conflict messages, so "who overwrote this" has an answer. */
+  readonly machine: string;
+}
+
+/** Settings plus the token, which exists only in the daemon's memory after a sign-in. */
+export interface Config extends Settings {
+  readonly token: string;
+}
+
+/** Sync progress for one folder. Each folder syncs with the server on its own, so each has its own. */
+export interface State {
+  /** Highest server sequence number already applied. */
+  cursor: number;
+  /** Last hash this machine agreed with the server on, per relative path. Absent means never synced. */
+  known: Record<string, string>;
+  /** The synced list as of last cycle, to notice a skill being added to it. */
+  skills?: string[];
+}
+
+/** Every folder's `State`, keyed by the folder's absolute path. */
+export type States = Record<string, State>;
+
+/**
+ * The settings, writing a template on first run. Undefined when the file lacks an endpoint or a machine
+ * name, which only happens if someone edited it.
+ */
+export function loadSettings(): Settings | undefined {
+  if (!existsSync(CONFIG_PATH)) {
+    mkdirSync(JIVE_HOME, { recursive: true });
+    writeFileSync(CONFIG_PATH, `${JSON.stringify({
+      endpoint: "https://skill-sync.jive.sh",
+      machine: machineName(),
+      exclude: DEFAULT_EXCLUDE,
+    }, null, 2)}\n`);
+  }
+  const settings = readJson<Partial<Settings>>(CONFIG_PATH);
+  if (!settings.endpoint || !settings.machine) return undefined;
+  return { endpoint: settings.endpoint, machine: settings.machine, exclude: settings.exclude ?? DEFAULT_EXCLUDE };
+}
+
+function readJson<T>(path: string): T {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return {} as T;
+  }
+}
+
+/**
+ * Every folder's sync state.
+ *
+ * Before folders were detected the file held one folder's `{ cursor, known }`, for the folder then named
+ * by `skillsDir` in the settings. That state is carried over to that folder: dropping it would make the
+ * folder look never-synced, and every file in it that differs from the server would become a conflict.
+ */
+export function loadStates(): States {
+  const stored = readJson<Partial<State> & { folders?: States }>(STATE_PATH);
+  if (stored.folders !== undefined) return stored.folders;
+  const legacyFolder = readJson<{ skillsDir?: string }>(CONFIG_PATH).skillsDir;
+  if (legacyFolder !== undefined && stored.cursor !== undefined && stored.known !== undefined) {
+    return { [legacyFolder]: { cursor: stored.cursor, known: stored.known } };
+  }
+  return {};
+}
+
+export function stateFor(states: States, folder: string): State {
+  states[folder] ??= { cursor: 0, known: {} };
+  return states[folder];
+}
+
+export function saveStates(states: States): void {
+  mkdirSync(JIVE_HOME, { recursive: true });
+  writeFileSync(STATE_PATH, `${JSON.stringify({ folders: states }, null, 2)}\n`);
+}
+
+/** `HOSTNAME` is not set on macOS, so the template was writing "unknown" on exactly this machine. */
+function machineName(): string {
+  return hostname().replace(/\.local$/, "").replace(/[^A-Za-z0-9-]+/g, "-") || "unknown";
+}
+
+/**
+ * The `skills` folder of every Claude home on this machine: `~/.claude` and each `~/.claude-<name>`.
+ *
+ * Every home is a candidate, whether or not it has a `skills` folder yet, so a Claude account added
+ * later joins without anyone listing it. Which of them actually sync is the user's choice on the
+ * dashboard; a folder that is synced and missing is created.
+ */
+export function detectFolders(): string[] {
+  return readdirSync(homedir())
+    .filter((entry) => entry === ".claude" || entry.startsWith(".claude-"))
+    .filter((entry) => statSync(join(homedir(), entry)).isDirectory())
+    .map((entry) => join(homedir(), entry, "skills"))
+    .sort();
+}
+
+export function hashBytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Suffix for the copy kept when an incoming change would have overwritten a local edit. */
+export const CONFLICT_SUFFIX = ".local";
+
+/**
+ * Every file under a synced folder, as paths relative to it with forward slashes.
+ *
+ * Normalised because the same skill synced from Windows and macOS must be one row, not two.
+ *
+ * Conflict copies are skipped. They are this machine's evidence of a collision, not content anyone else
+ * asked for, and syncing them spreads one machine's mess to every other machine.
+ */
+export function listLocalFiles(folder: string, exclude: ReadonlyArray<string> = DEFAULT_EXCLUDE): string[] {
+  if (!existsSync(folder)) return [];
+
+  const found: string[] = [];
+  const walk = (dir: string, top: boolean): void => {
+    for (const entry of readdirSync(dir)) {
+      if (entry.startsWith(".")) continue;
+      if (top && exclude.includes(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full, false);
+      else if (!entry.endsWith(CONFLICT_SUFFIX)) found.push(relative(folder, full).split(sep).join("/"));
+    }
+  };
+  walk(folder, true);
+  return found.sort();
+}

package/src/internal/control.ts

@@ -0,0 +1,123 @@
+import { createConnection, createServer, type Server, type Socket } from "node:net";
+import { chmodSync, rmSync } from "node:fs";
+import { CONTROL_SOCKET } from "./config";
+
+/**
+ * The channel between the CLI and the running daemon.
+ *
+ * The daemon owns the sync token: it receives it from the browser and keeps it only in memory, so it is
+ * never in a file and never passes through the CLI. The CLI's `login` and `logout` are requests to the
+ * daemon over this channel. Messages are newline-delimited JSON; each request gets events until one that
+ * ends it.
+ */
+
+export type ControlRequest =
+  | { readonly type: "login" }
+  | { readonly type: "logout" };
+
+export type ControlEvent =
+  /** Sign-in has started: the CLI opens this URL in the browser, where the passkey is verified. */
+  | { readonly type: "open"; readonly url: string }
+  | { readonly type: "signedIn"; readonly machine: string }
+  | { readonly type: "signedOut"; readonly revoked: boolean }
+  | { readonly type: "error"; readonly message: string };
+
+const isFinal = (event: ControlEvent): boolean => event.type !== "open";
+
+/** The daemon is not running, as opposed to running and refusing the request. */
+export class DaemonUnreachable extends Error {}
+
+/** Sends one request and calls `onEvent` for each event until the final one, which it resolves with. */
+export function request(message: ControlRequest, onEvent: (event: ControlEvent) => void): Promise<ControlEvent> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const socket = createConnection(CONTROL_SOCKET);
+    socket.on("connect", () => socket.write(`${JSON.stringify(message)}\n`));
+    socket.on("error", (cause: NodeJS.ErrnoException) => {
+      if (settled) return;
+      settled = true;
+      reject(cause.code === "ENOENT" || cause.code === "ECONNREFUSED"
+        ? new DaemonUnreachable(`the skill-sync daemon is not running (${cause.code} on ${CONTROL_SOCKET})`)
+        : cause);
+    });
+    readLines(socket, (line) => {
+      const event = JSON.parse(line) as ControlEvent;
+      onEvent(event);
+      if (isFinal(event) && !settled) {
+        settled = true;
+        socket.end();
+        resolve(event);
+      }
+    });
+    socket.on("close", () => {
+      if (!settled) {
+        settled = true;
+        reject(new Error("the daemon closed the connection without answering"));
+      }
+    });
+  });
+}
+
+/** One request being answered: send events, and end the conversation with a final one. */
+export interface Reply {
+  readonly send: (event: ControlEvent) => void;
+}
+
+/**
+ * Listens on the control socket. Resolves false, without listening, when another live daemon already
+ * holds it: two installs of skill-sync mean two daemons, and the second stands down rather than fight.
+ */
+export async function serve(handle: (message: ControlRequest, reply: Reply) => void): Promise<Server | false> {
+  if (await answers()) return false;
+  // Nothing answered, so a socket file left here is from a daemon that died; it would block the listen.
+  if (process.platform !== "win32") rmSync(CONTROL_SOCKET, { force: true });
+
+  const server = createServer((socket) => {
+    const reply: Reply = {
+      send: (event) => {
+        if (socket.writable) socket.write(`${JSON.stringify(event)}\n`);
+        if (isFinal(event)) socket.end();
+      },
+    };
+    readLines(socket, (line) => {
+      try {
+        handle(JSON.parse(line) as ControlRequest, reply);
+      } catch (cause) {
+        reply.send({ type: "error", message: cause instanceof Error ? cause.message : String(cause) });
+      }
+    });
+    socket.on("error", () => undefined); // A CLI that went away mid-request; nothing to tell it.
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(CONTROL_SOCKET, () => resolve());
+  });
+  // Only this user may talk to the daemon that holds their token.
+  if (process.platform !== "win32") chmodSync(CONTROL_SOCKET, 0o600);
+  return server;
+}
+
+/** Whether a live daemon is listening on the control socket. */
+function answers(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection(CONTROL_SOCKET);
+    socket.on("connect", () => {
+      socket.end();
+      resolve(true);
+    });
+    socket.on("error", () => resolve(false));
+  });
+}
+
+function readLines(socket: Socket, onLine: (line: string) => void): void {
+  let buffer = "";
+  socket.on("data", (chunk) => {
+    buffer += chunk.toString();
+    let newline: number;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line !== "") onLine(line);
+    }
+  });
+}

package/src/internal/folders.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { detectFolders, hashBytes, listLocalFiles, type Config } from "./config";
+import {
+  skillOf, type FileHash, type FolderPrefs, type FoldersRequest, type FoldersResponse, type LocalSkill, type ReconciliationRequest,
+} from "./wire";
+
+/**
+ * What this machine tells the service about its folders, and what it hears back.
+ *
+ * The daemon and the CLI both register, so this lives in one place: they must describe a folder the same
+ * way, or the dashboard would show whichever of them spoke last.
+ */
+
+/**
+ * The skills on disk in one folder, with each file's hash. Hashing every file on each check is cheap at
+ * skills' size, and it is what lets the dashboard show whether this folder's copy is the synced one.
+ */
+export function localSkills(folder: string, config: Config): LocalSkill[] {
+  const byName = new Map<string, FileHash[]>();
+  for (const path of listLocalFiles(folder, config.exclude)) {
+    const name = skillOf(path);
+    let hash: string;
+    try {
+      hash = hashBytes(readFileSync(join(folder, path)));
+    } catch {
+      continue; // Deleted between listing and reading; the next check reports the folder as it is.
+    }
+    byName.set(name, [...(byName.get(name) ?? []), { path, hash }]);
+  }
+  return [...byName].map(([name, files]) => ({ name, files }));
+}
+
+/** Everything registration sends, so a caller can tell when it has changed and is worth re-sending. */
+export function describe(config: Config): FoldersRequest {
+  return { folders: detectFolders().map((path) => ({ path, skills: localSkills(path, config) })) };
+}
+
+/** Registers this machine's folders and skills; returns the folders to sync and the skills in each. */
+export async function register(config: Config, request: FoldersRequest): Promise<ReadonlyArray<FolderPrefs>> {
+  const response = await fetch(`${config.endpoint}/folders`, {
+    method: "POST",
+    headers: authHeaders(config, { "content-type": "application/json" }),
+    body: JSON.stringify(request),
+  });
+  if (!response.ok) throw new Error(`POST /folders: ${response.status} ${await response.text()}`);
+  return (await response.json() as FoldersResponse).folders;
+}
+
+/** Sends merges to the audit log. A failure here is logged by the caller, never fatal to a sync. */
+export async function logReconciliations(config: Config, entries: ReadonlyArray<ReconciliationRequest>): Promise<void> {
+  for (const entry of entries) {
+    const response = await fetch(`${config.endpoint}/reconciliations`, {
+      method: "POST",
+      headers: authHeaders(config, { "content-type": "application/json" }),
+      body: JSON.stringify(entry),
+    });
+    if (!response.ok) throw new Error(`POST /reconciliations: ${response.status} ${await response.text()}`);
+  }
+}
+
+export function authHeaders(config: Config, extra: Record<string, string>): Record<string, string> {
+  return { authorization: `Bearer ${config.token}`, "x-skill-sync-machine": config.machine, ...extra };
+}

package/src/internal/notify.ts

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+
+/**
+ * A desktop notification, best effort.
+ *
+ * Best effort is the whole contract: a daemon that cannot tell you about a conflict is worse than one
+ * that cannot sync, but a daemon that *dies* because a notification helper is missing is worse than
+ * both. Every failure here is swallowed.
+ *
+ * This works because these daemons are registered per-user and run inside the logged-in session — a
+ * LaunchAgent, a `systemctl --user` unit, a scheduled task. A system-wide service would have no desktop
+ * to post to.
+ */
+
+/** No shell anywhere below: the arguments carry file paths, and a path is not a safe thing to interpolate. */
+function run(command: string, args: ReadonlyArray<string>): void {
+  try {
+    spawn(command, [...args], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    // Swallowed on purpose; see above.
+  }
+}
+
+export function notify(title: string, body: string): void {
+  switch (process.platform) {
+    case "darwin":
+      // AppleScript string literals take double quotes and backslashes as escapes, and nothing else.
+      return run("osascript", [
+        "-e",
+        `display notification "${escapeAppleScript(body)}" with title "${escapeAppleScript(title)}"`,
+      ]);
+    case "linux":
+      return run("notify-send", [title, body]);
+    case "win32":
+      return run("powershell", [
+        "-NoProfile", "-NonInteractive", "-Command",
+        "[reflection.assembly]::LoadWithPartialName('System.Windows.Forms') > $null;"
+        + "$n = New-Object System.Windows.Forms.NotifyIcon;"
+        + "$n.Icon = [System.Drawing.SystemIcons]::Warning; $n.Visible = $true;"
+        + `$n.ShowBalloonTip(10000, '${escapeSingleQuotes(title)}', '${escapeSingleQuotes(body)}', 'Warning')`,
+      ]);
+    default:
+      return;
+  }
+}
+
+function escapeAppleScript(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function escapeSingleQuotes(value: string): string {
+  return value.replace(/'/g, "''");
+}

package/src/internal/path.ts

@@ -0,0 +1,32 @@
+/**
+ * Validation for the one piece of untrusted input that becomes a filesystem path.
+ *
+ * Shared by the Worker and the daemon on purpose, and deliberately free of any Node import so the Worker
+ * can bundle it. Both ends check: the server so one compromised client cannot poison what every machine
+ * pulls, and the daemon because a server it does not control is not a thing to take paths from either.
+ *
+ * Without this, a pushed path of `../../.ssh/authorized_keys` is joined to the skills directory and
+ * written wherever the daemon's user can write.
+ */
+
+/** Long enough for any real nesting, short enough that nothing can be used to exhaust anything. */
+const MAX_LENGTH = 512;
+
+export function invalidPathReason(path: string): string | undefined {
+  if (path.length === 0 || path.length > MAX_LENGTH) return "path is empty or too long";
+  if (path.includes("\0")) return "path contains a null byte";
+  if (path.includes("\\")) return "path must use forward slashes";
+  if (path.startsWith("/")) return "path must be relative";
+  // A Windows drive letter is absolute on the machine that matters even though it has no leading slash.
+  if (/^[A-Za-z]:/.test(path)) return "path must be relative";
+
+  for (const segment of path.split("/")) {
+    if (segment === "") return "path has an empty segment";
+    if (segment === "." || segment === "..") return "path must not contain . or .. segments";
+  }
+  return undefined;
+}
+
+export function isValidPath(path: string): boolean {
+  return invalidPathReason(path) === undefined;
+}

package/src/internal/reconcile.ts

@@ -0,0 +1,166 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join } from "node:path";
+
+/**
+ * Merges two versions of one skill file with Claude, on this machine.
+ *
+ * A conflict used to mean "the server's copy wins and yours is set aside as `.local`", which left the
+ * merge to a person who might not notice for days, while every machine ran the losing half. Skills are
+ * prose that Claude reads, so Claude is the right one to merge them: it keeps every rule either side
+ * added and resolves the ones that disagree.
+ *
+ * Claude runs with no tools, no MCP servers and no settings: it receives the versions on stdin and
+ * answers with the merged file, so it cannot touch anything else. It runs as the Claude account whose
+ * folder is being merged (`CLAUDE_CONFIG_DIR` set to that folder's home), so it never creates or writes
+ * `~/.claude` — a home the user may have deleted on purpose.
+ */
+
+export interface Version {
+  readonly content: string;
+  /** Where this version came from, for the prompt: "this machine, edited …" or "MacBookPro, uploaded …". */
+  readonly label: string;
+}
+
+/** The merged file, and Claude's account of it for the audit log. */
+export interface Resolution {
+  readonly merged: string;
+  /** What differed between the two versions. */
+  readonly conflict: string;
+  /** What the merge kept, dropped or reworded. */
+  readonly resolution: string;
+}
+
+export interface Conflict {
+  readonly folder: string;
+  readonly path: string;
+  readonly local: Version;
+  readonly remote: Version;
+  /** The last version both sides agreed on, when there is one; it lets Claude see what each side changed. */
+  readonly base: string | null;
+}
+
+const BACKUP_ROOT = join(homedir(), ".jive", "skill-sync", "reconciled");
+/** A long skill is tens of thousands of tokens to write back out. */
+const TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * A merge shorter than this fraction of the longer input is refused as probably truncated: a model that
+ * stops early produces a file that looks fine and silently drops half the rules.
+ */
+const MIN_LENGTH_RATIO = 0.6;
+
+const SYSTEM_PROMPT = `You merge two versions of one file from a user's Claude skills folder into one.
+Answer in exactly this form and nothing else:
+<conflict>One or two plain sentences: what differs between the versions.</conflict>
+<resolution>One or two plain sentences: what the merge kept from each, and anything dropped or reworded.</resolution>
+<merged>
+The complete merged file, exactly as it should be saved. No code fences.
+</merged>
+Rules for the merge:
+- Keep every rule, example and fact that either version has, unless the other version clearly replaces it.
+- Where the two disagree, prefer the newer version's wording, and keep anything only the older one has.
+- If a base version is given, it is what both started from: use it to tell additions from deletions, and
+  honour a deletion made on one side when the other side did not edit that part.
+- Keep the file's frontmatter and structure.
+In <conflict> and <resolution>, call the two versions by the names they are given (for example "the copy in
+~/.claude-chaine/skills on MacBookPro" and "the synced copy"), never "Version A" or "Version B": these are
+read later by a person auditing the merge, who never saw this prompt.`;
+
+/**
+ * Both versions are copied out of the synced folder before anything is written, so a bad merge costs a
+ * file copy, not the user's work. Outside the folder so the copies are never synced or read as skills.
+ */
+export function backUp(conflict: Conflict): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dir = join(BACKUP_ROOT, stamp, basename(dirname(conflict.folder)), conflict.path);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "local"), conflict.local.content);
+  writeFileSync(join(dir, "remote"), conflict.remote.content);
+  if (conflict.base !== null) writeFileSync(join(dir, "base"), conflict.base);
+  return dir;
+}
+
+export async function reconcile(conflict: Conflict): Promise<Resolution> {
+  const sections = [
+    `File: ${conflict.path}`,
+    conflict.base === null ? "No base version: these two have never been in sync." : `=== the base version both started from:\n${conflict.base}`,
+    `=== ${conflict.local.label}:\n${conflict.local.content}`,
+    `=== ${conflict.remote.label}:\n${conflict.remote.content}`,
+    "Write the merged file now.",
+  ];
+  const answer = await runClaude(sections.join("\n\n-----\n\n"), dirname(conflict.folder));
+  const start = answer.indexOf("<merged>");
+  const end = answer.lastIndexOf("</merged>");
+  if (start === -1 || end <= start) throw new Error("Claude's answer had no <merged> section");
+  // The file is everything between the tags, minus the newline that follows the opening one.
+  const merged = answer.slice(start + "<merged>".length, end).replace(/^\r?\n/, "");
+  const conflictText = /<conflict>([\s\S]*?)<\/conflict>/.exec(answer)?.[1]?.trim() ?? "";
+  const resolutionText = /<resolution>([\s\S]*?)<\/resolution>/.exec(answer)?.[1]?.trim() ?? "";
+
+  const longest = Math.max(conflict.local.content.length, conflict.remote.content.length);
+  if (merged.trim().length === 0) throw new Error("Claude returned an empty merge");
+  if (merged.length < longest * MIN_LENGTH_RATIO) {
+    throw new Error(`the merge is ${merged.length} characters against ${longest}; refusing it as probably truncated`);
+  }
+  return {
+    merged: merged.endsWith("\n") ? merged : `${merged}\n`,
+    conflict: conflictText || "Claude did not describe the conflict.",
+    resolution: resolutionText || "Claude did not describe the resolution.",
+  };
+}
+
+/** `configDir` is the Claude home that owns the folder, e.g. `~/.claude-chaine` for `~/.claude-chaine/skills`. */
+function runClaude(input: string, configDir: string): Promise<string> {
+  const claude = findClaude();
+  if (claude === undefined) return Promise.reject(new Error("the claude CLI is not installed"));
+
+  // Always set, never inherited or left unset: unset, `claude` falls back to `~/.claude` and writes its
+  // session files, backups and caches there, recreating that home every time it is deleted.
+  const env = { ...process.env, CLAUDE_CONFIG_DIR: configDir };
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(claude, [
+      "-p", "--output-format", "json", "--tools", "", "--strict-mcp-config", "--setting-sources", "",
+      "--no-session-persistence", "--system-prompt", SYSTEM_PROMPT,
+    ], { env, cwd: homedir(), stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); });
+    const timer = setTimeout(() => child.kill("SIGTERM"), TIMEOUT_MS);
+
+    child.on("error", (cause) => { clearTimeout(timer); reject(cause); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      try {
+        const result = JSON.parse(stdout) as { is_error?: boolean; result?: string };
+        if (code !== 0 || result.is_error || typeof result.result !== "string") {
+          reject(new Error(`claude failed (exit ${code}): ${result.result ?? stderr.trim()}`));
+        } else {
+          resolve(result.result);
+        }
+      } catch {
+        reject(new Error(`claude failed (exit ${code}): ${stderr.trim() || stdout.slice(0, 300)}`));
+      }
+    });
+    child.stdin.end(input);
+  });
+}
+
+/**
+ * The daemon starts at login with the service manager's minimal PATH, which rarely includes where the
+ * Claude installer puts `claude`, so the usual install locations are checked too.
+ */
+function findClaude(): string | undefined {
+  const name = process.platform === "win32" ? "claude.exe" : "claude";
+  const fromPath = (process.env["PATH"] ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, name));
+  const known = [
+    join(homedir(), ".local", "bin", name),
+    join(homedir(), ".claude", "local", "claude"),
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+  ];
+  return [...fromPath, ...known].find((candidate) => existsSync(candidate));
+}