@primusclaw/connector 0.1.2 → 0.1.3

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // src/commands.ts
-import fs14 from "node:fs";
-import os5 from "node:os";
-import path15 from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseArgs } from "node:util";
+import fs16 from "node:fs";
+import os6 from "node:os";
+import path17 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { parseArgs as parseArgs2 } from "node:util";
 
 // src/audit.ts
 import fs from "node:fs";
@@ -335,11 +335,11 @@ var RevokedError = class extends Error {
   }
 };
 var HttpError = class extends Error {
-  constructor(status, code, path16) {
-    super(`${path16} answered ${status} ${code}`);
-    this.status = status;
+  constructor(status2, code, path18) {
+    super(`${path18} answered ${status2} ${code}`);
+    this.status = status2;
     this.code = code;
-    this.path = path16;
+    this.path = path18;
   }
   status;
   code;
@@ -363,8 +363,8 @@ var ClawClient = class {
       ...extra
     };
   }
-  async send(method, path16, body, signal) {
-    const url = this.o.server + path16;
+  async send(method, path18, body, signal) {
+    const url = this.o.server + path18;
     for (let attempt = 0; ; attempt++) {
       const headers = await this.headers(body === void 0 ? {} : { "content-type": "application/json" });
       let res;
@@ -376,7 +376,7 @@ var ClawClient = class {
           signal: signal ?? AbortSignal.timeout(this.o.requestTimeoutMs ?? 2e4)
         });
       } catch (e) {
-        throw new TransportError(`${method} ${path16}: ${errMessage(e)}`);
+        throw new TransportError(`${method} ${path18}: ${errMessage(e)}`);
       }
       if (res.status !== 401) return res;
       const err = await errorCode(res);
@@ -385,12 +385,12 @@ var ClawClient = class {
         this.o.tokens.invalidate();
         continue;
       }
-      throw new HttpError(401, err, path16);
+      throw new HttpError(401, err, path18);
     }
   }
-  async json(method, path16, body) {
-    const res = await this.send(method, path16, body);
-    if (!res.ok) throw new HttpError(res.status, await errorCode(res), path16);
+  async json(method, path18, body) {
+    const res = await this.send(method, path18, body);
+    if (!res.ok) throw new HttpError(res.status, await errorCode(res), path18);
     const parsed = await res.json().catch(() => null);
     return isObject(parsed) && isObject(parsed.data) ? parsed.data : {};
   }
@@ -428,21 +428,21 @@ var ClawClient = class {
     };
     try {
       arm();
-      const path16 = `/v1/remote-agents/connectors/${cid}/commands`;
+      const path18 = `/v1/remote-agents/connectors/${cid}/commands`;
       const headers = await this.headers({ accept: "text/event-stream", ...opts.lastEventId ? { "last-event-id": String(opts.lastEventId) } : {} });
       let res;
       try {
-        res = await this.f(this.o.server + path16, { headers, signal: stop.signal });
+        res = await this.f(this.o.server + path18, { headers, signal: stop.signal });
       } catch (e) {
-        throw new TransportError(timedOut ? `no response for ${opts.watchdogMs} ms` : `GET ${path16}: ${errMessage(e)}`);
+        throw new TransportError(timedOut ? `no response for ${opts.watchdogMs} ms` : `GET ${path18}: ${errMessage(e)}`);
       }
       if (res.status === 401) {
         const err = await errorCode(res);
         if (err === "revoked") throw new RevokedError();
         this.o.tokens.invalidate();
-        throw new HttpError(401, err, path16);
+        throw new HttpError(401, err, path18);
       }
-      if (!res.ok || !res.body) throw new HttpError(res.status, await errorCode(res), path16);
+      if (!res.ok || !res.body) throw new HttpError(res.status, await errorCode(res), path18);
       try {
         for await (const frame of readSse(res.body, arm)) yield frame;
       } catch (e) {
@@ -1307,7 +1307,7 @@ function hooksStatus(configDir) {
 }
 
 // src/connector.ts
-import fs13 from "node:fs";
+import fs14 from "node:fs";
 import { randomUUID as randomUUID2 } from "node:crypto";
 
 // src/attach.ts
@@ -1859,8 +1859,106 @@ function fitResumable(base, items, limit = REMOTE_AGENT_LIMITS.maxCapabilitiesBy
   }
 }
 
-// src/session.ts
+// src/health.ts
+import fs11 from "node:fs";
+import path12 from "node:path";
+
+// src/paths.ts
+import os4 from "node:os";
 import path11 from "node:path";
+function resolveDirs(env = process.env, home = os4.homedir()) {
+  const one = env.CLAW_CONNECTOR_HOME?.trim();
+  if (one) return { config: path11.join(one, "config"), state: path11.join(one, "state") };
+  const cfg = env.XDG_CONFIG_HOME?.trim() || path11.join(home, ".config");
+  const st = env.XDG_STATE_HOME?.trim() || path11.join(home, ".local", "state");
+  return { config: path11.join(cfg, "claw-connector"), state: path11.join(st, "claw-connector") };
+}
+var configFile = (d) => path11.join(d.config, "agents.toml");
+var credentialsFile = (d) => path11.join(d.config, "credentials.json");
+var identityFile = (d) => path11.join(d.state, "connector.json");
+var sessionsFile = (d) => path11.join(d.state, "sessions.json");
+var childrenFile = (d) => path11.join(d.state, "children.json");
+var pidFile = (d) => path11.join(d.state, "connector.pid");
+var pauseFile = (d) => path11.join(d.state, "paused");
+var auditFile = (d) => path11.join(d.state, "audit.jsonl");
+var outboxDir = (d) => path11.join(d.state, "outbox");
+var logDir = (d) => path11.join(d.state, "logs");
+var disconnectsFile = (d) => path11.join(d.state, "disconnects.jsonl");
+var needsLoginFile = (d) => path11.join(d.state, "needs-login.json");
+var supervisorPidFile = (d) => path11.join(d.state, "supervisor.pid");
+var runLogFile = (d) => path11.join(d.state, "run.log");
+var keepaliveFile = (d) => path11.join(d.state, "keepalive.sh");
+var serviceFile = (d) => path11.join(d.state, "service.json");
+
+// src/health.ts
+var MAX_BYTES = 128 * 1024;
+function recordDisconnect(dirs, d) {
+  const file = disconnectsFile(dirs);
+  try {
+    fs11.mkdirSync(path12.dirname(file), { recursive: true, mode: 448 });
+    const fd = fs11.openSync(file, "a+", 384);
+    let lines = null;
+    try {
+      fs11.writeSync(fd, JSON.stringify({ at: d.at ?? (/* @__PURE__ */ new Date()).toISOString(), reason: d.reason, ...d.detail ? { detail: d.detail.slice(0, 300) } : {} }) + "\n");
+      const size = fs11.fstatSync(fd).size;
+      if (size > MAX_BYTES) {
+        const buf = Buffer.alloc(size);
+        let got = 0;
+        while (got < size) {
+          const n = fs11.readSync(fd, buf, got, size - got, got);
+          if (n === 0) break;
+          got += n;
+        }
+        lines = buf.subarray(0, got).toString("utf8").split("\n").filter(Boolean);
+      }
+    } finally {
+      fs11.closeSync(fd);
+    }
+    if (lines) {
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs11.writeFileSync(tmp, lines.slice(Math.floor(lines.length / 2)).join("\n") + "\n", { mode: 384 });
+      fs11.renameSync(tmp, file);
+    }
+  } catch {
+  }
+}
+function recentDisconnects(dirs, n = 1) {
+  try {
+    const out = [];
+    for (const line of fs11.readFileSync(disconnectsFile(dirs), "utf8").split("\n").filter(Boolean).slice(-n)) {
+      try {
+        const v = JSON.parse(line);
+        if (isObject(v) && typeof v.at === "string" && typeof v.reason === "string") out.push({ at: v.at, reason: v.reason, ...typeof v.detail === "string" ? { detail: v.detail } : {} });
+      } catch {
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+function markNeedsLogin(dirs, reason) {
+  try {
+    fs11.mkdirSync(dirs.state, { recursive: true, mode: 448 });
+    fs11.writeFileSync(needsLoginFile(dirs), JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), reason: reason.slice(0, 300) }), { mode: 384 });
+  } catch {
+  }
+}
+function needsLogin(dirs) {
+  try {
+    const v = JSON.parse(fs11.readFileSync(needsLoginFile(dirs), "utf8"));
+    if (isObject(v) && typeof v.reason === "string") return { at: typeof v.at === "string" ? v.at : "", reason: v.reason };
+    return { at: "", reason: "unreadable needs-login.json" };
+  } catch (e) {
+    return e.code === "ENOENT" ? null : { at: "", reason: "unreadable needs-login.json" };
+  }
+}
+function clearNeedsLogin(dirs) {
+  fs11.rmSync(needsLoginFile(dirs), { force: true });
+}
+
+// src/session.ts
+import path13 from "node:path";
 
 // src/permissions.ts
 import { randomUUID } from "node:crypto";
@@ -2206,7 +2304,7 @@ var Session = class {
       sessionId: this.id,
       cwd: this.cwd,
       hooks: this.hooks(),
-      logFile: path11.join(this.env.logDir, `adapter-${this.agent.id}.log`),
+      logFile: path13.join(this.env.logDir, `adapter-${this.agent.id}.log`),
       version: this.env.version
     }).catch((e) => {
       throw new SessionRefusal("adapter_start_failed", errMessage(e));
@@ -2906,8 +3004,8 @@ var SessionManager = class {
 };
 
 // src/outbox.ts
-import fs11 from "node:fs";
-import path12 from "node:path";
+import fs12 from "node:fs";
+import path14 from "node:path";
 var DROPPABLE_TYPES = /* @__PURE__ */ new Set([
   "agent_message_chunk",
   "agent_thought_chunk",
@@ -2934,35 +3032,35 @@ var Outbox = class {
     this.dir = opts.dir;
     this.maxBytes = opts.maxBytesPerSession ?? 5 * 1024 * 1024;
     this.now = opts.now ?? Date.now;
-    fs11.mkdirSync(this.dir, { recursive: true, mode: 448 });
+    fs12.mkdirSync(this.dir, { recursive: true, mode: 448 });
     this.load();
   }
-  eventsFile = (sid) => path12.join(this.dir, `${safeName(sid)}.jsonl`);
-  metaFile = (sid) => path12.join(this.dir, `${safeName(sid)}.meta.json`);
+  eventsFile = (sid) => path14.join(this.dir, `${safeName(sid)}.jsonl`);
+  metaFile = (sid) => path14.join(this.dir, `${safeName(sid)}.meta.json`);
   writeMeta(sid) {
     const tmp = this.metaFile(sid) + ".tmp";
-    fs11.writeFileSync(tmp, JSON.stringify(this.meta.get(sid)), { mode: 384 });
-    fs11.renameSync(tmp, this.metaFile(sid));
+    fs12.writeFileSync(tmp, JSON.stringify(this.meta.get(sid)), { mode: 384 });
+    fs12.renameSync(tmp, this.metaFile(sid));
   }
   /** Rebuild the queue from disk. The highest sequence number ever used is the larger of the meta file and the log itself. */
   load() {
     const loaded = [];
     const bases = /* @__PURE__ */ new Set();
-    for (const name of fs11.readdirSync(this.dir)) {
+    for (const name of fs12.readdirSync(this.dir)) {
       if (name.endsWith(".meta.json")) bases.add(name.slice(0, -".meta.json".length));
       else if (name.endsWith(".jsonl")) bases.add(name.slice(0, -".jsonl".length));
     }
     for (const base of bases) {
       let meta = { lastSeq: 0, acked: 0 };
       try {
-        meta = JSON.parse(fs11.readFileSync(path12.join(this.dir, `${base}.meta.json`), "utf8"));
+        meta = JSON.parse(fs12.readFileSync(path14.join(this.dir, `${base}.meta.json`), "utf8"));
       } catch {
       }
       let sid = null;
-      const file = path12.join(this.dir, `${base}.jsonl`);
+      const file = path14.join(this.dir, `${base}.jsonl`);
       let text = "";
       try {
-        text = fs11.readFileSync(file, "utf8");
+        text = fs12.readFileSync(file, "utf8");
       } catch {
       }
       for (const line of text.split("\n")) {
@@ -2980,8 +3078,8 @@ var Outbox = class {
       if (sid === null) {
         sid = base;
         try {
-          if (this.now() - fs11.statSync(path12.join(this.dir, `${base}.meta.json`)).mtimeMs > TOMBSTONE_MS) {
-            for (const f of [`${base}.meta.json`, `${base}.jsonl`]) fs11.rmSync(path12.join(this.dir, f), { force: true });
+          if (this.now() - fs12.statSync(path14.join(this.dir, `${base}.meta.json`)).mtimeMs > TOMBSTONE_MS) {
+            for (const f of [`${base}.meta.json`, `${base}.jsonl`]) fs12.rmSync(path14.join(this.dir, f), { force: true });
             continue;
           }
         } catch {
@@ -3003,7 +3101,7 @@ var Outbox = class {
     meta.lastSeq = ev.seq;
     this.meta.set(sessionId, meta);
     const line = JSON.stringify(ev);
-    fs11.appendFileSync(this.eventsFile(sessionId), line + "\n", { mode: 384 });
+    fs12.appendFileSync(this.eventsFile(sessionId), line + "\n", { mode: 384 });
     if (ev.seq === 1) this.writeMeta(sessionId);
     this.queue.push(ev);
     this.bytes.set(sessionId, (this.bytes.get(sessionId) ?? 0) + line.length);
@@ -3032,8 +3130,8 @@ var Outbox = class {
     this.writeMeta(sessionId);
     const mine = this.queue.filter((e) => e.session_id === sessionId);
     const tmp = this.eventsFile(sessionId) + ".tmp";
-    fs11.writeFileSync(tmp, mine.map((e) => JSON.stringify(e) + "\n").join(""), { mode: 384 });
-    fs11.renameSync(tmp, this.eventsFile(sessionId));
+    fs12.writeFileSync(tmp, mine.map((e) => JSON.stringify(e) + "\n").join(""), { mode: 384 });
+    fs12.renameSync(tmp, this.eventsFile(sessionId));
   }
   /** The oldest events not yet acknowledged, in the order they were appended. */
   pending(max) {
@@ -3071,7 +3169,7 @@ var Outbox = class {
     this.writeMeta(sid);
     const left = this.queue.filter((e) => e.session_id === sid);
     if (left.length === 0) {
-      fs11.writeFileSync(this.eventsFile(sid), "", { mode: 384 });
+      fs12.writeFileSync(this.eventsFile(sid), "", { mode: 384 });
       this.bytes.set(sid, 0);
       if (this.closed.has(sid)) this.forget(sid);
     } else if (left.length < this.queue.length / 2 || meta.acked > 1e3) {
@@ -3090,48 +3188,27 @@ var Outbox = class {
    * repeat. What stays is the small meta file, a tombstone, removed after {@link TOMBSTONE_MS}.
    */
   forget(sid) {
-    fs11.rmSync(this.eventsFile(sid), { force: true });
+    fs12.rmSync(this.eventsFile(sid), { force: true });
     if (this.meta.has(sid)) this.writeMeta(sid);
     this.bytes.delete(sid);
     this.closed.delete(sid);
   }
 };
 
-// src/paths.ts
-import os4 from "node:os";
-import path13 from "node:path";
-function resolveDirs(env = process.env, home = os4.homedir()) {
-  const one = env.CLAW_CONNECTOR_HOME?.trim();
-  if (one) return { config: path13.join(one, "config"), state: path13.join(one, "state") };
-  const cfg = env.XDG_CONFIG_HOME?.trim() || path13.join(home, ".config");
-  const st = env.XDG_STATE_HOME?.trim() || path13.join(home, ".local", "state");
-  return { config: path13.join(cfg, "claw-connector"), state: path13.join(st, "claw-connector") };
-}
-var configFile = (d) => path13.join(d.config, "agents.toml");
-var credentialsFile = (d) => path13.join(d.config, "credentials.json");
-var identityFile = (d) => path13.join(d.state, "connector.json");
-var sessionsFile = (d) => path13.join(d.state, "sessions.json");
-var childrenFile = (d) => path13.join(d.state, "children.json");
-var pidFile = (d) => path13.join(d.state, "connector.pid");
-var pauseFile = (d) => path13.join(d.state, "paused");
-var auditFile = (d) => path13.join(d.state, "audit.jsonl");
-var outboxDir = (d) => path13.join(d.state, "outbox");
-var logDir = (d) => path13.join(d.state, "logs");
-
 // src/session-store.ts
-import fs12 from "node:fs";
-import path14 from "node:path";
+import fs13 from "node:fs";
+import path15 from "node:path";
 var SessionStore = class {
   constructor(file) {
     this.file = file;
     this.pendingFile = `${file}.pending`;
     try {
-      const raw = JSON.parse(fs12.readFileSync(this.pendingFile, "utf8"));
+      const raw = JSON.parse(fs13.readFileSync(this.pendingFile, "utf8"));
       if (Array.isArray(raw)) this.pending = raw.filter((p) => p && typeof p.session_id === "string" && typeof p.action_id === "string");
     } catch {
     }
     try {
-      const raw = JSON.parse(fs12.readFileSync(file, "utf8"));
+      const raw = JSON.parse(fs13.readFileSync(file, "utf8"));
       if (raw && typeof raw === "object" && !Array.isArray(raw)) this.recs = raw;
     } catch {
     }
@@ -3174,19 +3251,19 @@ var SessionStore = class {
     return out;
   }
   savePending() {
-    fs12.mkdirSync(path14.dirname(this.pendingFile), { recursive: true, mode: 448 });
+    fs13.mkdirSync(path15.dirname(this.pendingFile), { recursive: true, mode: 448 });
     const tmp = `${this.pendingFile}.${process.pid}.tmp`;
-    fs12.writeFileSync(tmp, JSON.stringify(this.pending), { mode: 384 });
-    fs12.renameSync(tmp, this.pendingFile);
+    fs13.writeFileSync(tmp, JSON.stringify(this.pending), { mode: 384 });
+    fs13.renameSync(tmp, this.pendingFile);
   }
   ids() {
     return Object.keys(this.recs);
   }
   save() {
-    fs12.mkdirSync(path14.dirname(this.file), { recursive: true, mode: 448 });
+    fs13.mkdirSync(path15.dirname(this.file), { recursive: true, mode: 448 });
     const tmp = `${this.file}.${process.pid}.tmp`;
-    fs12.writeFileSync(tmp, JSON.stringify(this.recs), { mode: 384 });
-    fs12.renameSync(tmp, this.file);
+    fs13.writeFileSync(tmp, JSON.stringify(this.recs), { mode: 384 });
+    fs13.renameSync(tmp, this.file);
   }
 };
 
@@ -3202,7 +3279,9 @@ var DEFAULT_TIMING = {
   pausePollMs: 1e3,
   catalogMs: 12e4,
   attachCliMs: 8e3,
-  recentWriteMs: 1e4
+  recentWriteMs: 1e4,
+  authFailLimit: 4,
+  authFailWindowMs: 12e4
 };
 var CommandLedger = class {
   inflight = /* @__PURE__ */ new Set();
@@ -3242,6 +3321,7 @@ var CommandLedger = class {
     return this.highest;
   }
 };
+var isAuthRefusal = (e) => e instanceof HttpError && (e.status === 401 || e.status === 403);
 function isTransient(e) {
   return e instanceof TransientAuthError || e instanceof TransportError || e instanceof HttpError && (e.status >= 500 || e.status === 429);
 }
@@ -3294,6 +3374,13 @@ var Connector = class {
   /** The connector row itself was revoked (not just the sign-in): recorded in connector.json for `login`. */
   rowRevoked = false;
   paused = false;
+  /** The credential was refused `authFailLimit` times in a row (see {@link ConnectorTiming.authFailLimit}). */
+  authFailed = false;
+  authFailures = 0;
+  authFirstAt = 0;
+  authWhy = "";
+  /** The last event on the command stream, to tell why the server ended it (`superseded`, `token_expired`, a release). */
+  lastFrame = "";
   wakeSender = null;
   wakeHeartbeat = null;
   streamCtl = null;
@@ -3326,7 +3413,7 @@ var Connector = class {
   // --- identity -------------------------------------------------------------------
   readIdentity() {
     try {
-      const raw = JSON.parse(fs13.readFileSync(identityFile(this.d.dirs), "utf8"));
+      const raw = JSON.parse(fs14.readFileSync(identityFile(this.d.dirs), "utf8"));
       if (isObject(raw) && raw.server === this.d.server && typeof raw.connector_id === "string") {
         return { server: raw.server, connector_id: raw.connector_id, cursor: typeof raw.cursor === "number" ? raw.cursor : 0, handled: Array.isArray(raw.handled) ? raw.handled.filter((x) => typeof x === "string") : [] };
       }
@@ -3337,9 +3424,9 @@ var Connector = class {
   writeIdentity() {
     const st = { server: this.d.server, connector_id: this.cid, cursor: this.ledger.cursor, handled: this.ledger.recentIds, ...this.rowRevoked ? { revoked: true } : {} };
     const file = identityFile(this.d.dirs);
-    fs13.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
-    fs13.writeFileSync(`${file}.tmp`, JSON.stringify(st), { mode: 384 });
-    fs13.renameSync(`${file}.tmp`, file);
+    fs14.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
+    fs14.writeFileSync(`${file}.tmp`, JSON.stringify(st), { mode: 384 });
+    fs14.renameSync(`${file}.tmp`, file);
   }
   /** Use the connector id this machine already has, or register a new one. */
   async identify(forceNew = false) {
@@ -3424,12 +3511,29 @@ var Connector = class {
     this.streamCtl?.abort();
     await this.manager.killAll("revoked");
   }
+  /** One more refusal of the credential; the run ends once `authFailLimit` come in a row. Returns whether it ended. */
+  async authRefused(e) {
+    if (this.authFailures++ === 0) this.authFirstAt = Date.now();
+    if (this.authFailed) return true;
+    if (this.authFailures < this.timing.authFailLimit || Date.now() - this.authFirstAt < this.timing.authFailWindowMs) return false;
+    this.authFailed = true;
+    this.authWhy = errMessage(e);
+    this.d.log.error("Claw keeps refusing this sign-in: stopping every agent; run login again", { why: this.authWhy, refusals: this.authFailures });
+    this.d.audit.record("auth_failed", { why: this.authWhy });
+    this.ctl.abort();
+    this.streamCtl?.abort();
+    await this.manager.killAll("stopped");
+    return true;
+  }
+  get authFailure() {
+    return this.authWhy;
+  }
   isRevocation(e) {
     return e instanceof RevokedError || e instanceof GrantRevokedError;
   }
   async pauseWatcher() {
     while (!this.ctl.signal.aborted) {
-      const want = fs13.existsSync(pauseFile(this.d.dirs));
+      const want = fs14.existsSync(pauseFile(this.d.dirs));
       if (want && !this.paused) {
         this.paused = true;
         this.d.audit.record("paused");
@@ -3500,14 +3604,17 @@ var Connector = class {
       if (this.paused) continue;
       try {
         await this.heartbeat();
+        this.authFailures = 0;
         this.writeIdentity();
       } catch (e) {
         if (this.isRevocation(e)) return void await this.onRevoked(e);
+        if (isAuthRefusal(e) && await this.authRefused(e)) return;
         this.d.log.warn("heartbeat failed", { error: errMessage(e) });
       }
     }
   }
   onFrame(f, reconnect) {
+    if (f.event) this.lastFrame = f.event;
     switch (f.event) {
       case "ready":
         if (reconnect) this.manager.resendPending();
@@ -3556,17 +3663,26 @@ var Connector = class {
       try {
         const sig = AbortSignal.any([this.ctl.signal, this.streamCtl.signal]);
         let got = false;
+        this.lastFrame = "";
         for await (const f of this.d.client.commands(this.cid, { lastEventId: this.ledger.highestSeen || void 0, signal: sig, watchdogMs: this.timing.watchdogMs })) {
           if (!got) {
             got = true;
             attempt = 0;
+            this.authFailures = 0;
           }
           this.onFrame(f, reconnect);
           if (f.event === "ready") reconnect = true;
         }
+        if (!this.ctl.signal.aborted && !this.paused) {
+          const why = this.lastFrame === "superseded" || this.lastFrame === "token_expired" ? this.lastFrame : "the server closed the stream (a Claw release or restart)";
+          this.d.log.info("command stream ended by the server; reconnecting", { why });
+          recordDisconnect(this.d.dirs, { reason: "server_closed", detail: why });
+        }
       } catch (e) {
         if (this.isRevocation(e)) return void await this.onRevoked(e);
         if (this.ctl.signal.aborted) break;
+        if (isAuthRefusal(e) && await this.authRefused(e)) return;
+        recordDisconnect(this.d.dirs, { reason: "stream_lost", detail: errMessage(e) });
         if (e instanceof HttpError && e.status === 404) {
           try {
             await this.identify(true);
@@ -3585,18 +3701,34 @@ var Connector = class {
   }
   /** Run until stopped or revoked. Always leaves no adapter process behind. */
   async run() {
-    fs13.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
+    fs14.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
     await this.registry.killAll();
     for (const p of this.store.takePending()) {
       this.d.audit.record("permission_orphaned", { session_id: p.session_id, action_id: p.action_id });
       this.emit(p.session_id, "permission_resolved", { actionId: p.action_id, optionId: null, outcome: "cancelled", by: "connector_restart" });
     }
     const pidf = pidFile(this.d.dirs);
-    fs13.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
-    this.paused = fs13.existsSync(pauseFile(this.d.dirs));
+    let leftover = false;
+    try {
+      fs14.readFileSync(pidf);
+      leftover = true;
+    } catch {
+    }
+    if (leftover) {
+      let last;
+      try {
+        last = fs14.statSync(identityFile(this.d.dirs)).mtime.toISOString();
+      } catch {
+      }
+      recordDisconnect(this.d.dirs, { reason: "process_died", detail: `the previous run ended without shutting down (killed, crashed, or the machine restarted)${last ? `; last heartbeat ${last}` : ""}`, ...last ? { at: last } : {} });
+    }
+    fs14.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
+    this.paused = fs14.existsSync(pauseFile(this.d.dirs));
+    let result = "stopped";
+    let failure = "";
     try {
       const up = await this.startup();
-      if (up !== "ok") return up;
+      if (up !== "ok") return result = up;
       this.d.audit.record("connector_online", {
         connector_id: this.cid,
         agents: this.d.config.agents.map((a) => a.id),
@@ -3604,11 +3736,17 @@ var Connector = class {
         unattended_agents: this.d.config.agents.filter((a) => a.unattended).map((a) => a.id)
       });
       await Promise.all([this.sender(), this.heartbeater(), this.streamLoop(), this.pauseWatcher()]);
+      result = this.revoked ? "revoked" : this.authFailed ? "auth_failed" : "stopped";
+    } catch (e) {
+      failure = errMessage(e);
+      throw e;
     } finally {
       await this.manager.killAll(this.revoked ? "revoked" : "stopped").catch(() => void 0);
-      fs13.rmSync(pidf, { force: true });
+      const reason = this.revoked ? "revoked" : this.authFailed ? "auth_failed" : failure ? "failed" : this.paused ? "stopped_while_paused" : result;
+      recordDisconnect(this.d.dirs, { reason, detail: this.authWhy || failure || void 0 });
+      fs14.rmSync(pidf, { force: true });
     }
-    return this.revoked ? "revoked" : "stopped";
+    return result;
   }
   /** For tests: wait until every event is acknowledged. */
   async drained(timeoutMs = 5e3) {
@@ -3621,11 +3759,432 @@ var Connector = class {
   }
 };
 
+// src/service.ts
+import { spawn as spawn2, spawnSync } from "node:child_process";
+import fs15 from "node:fs";
+import os5 from "node:os";
+import path16 from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+var SUPERVISORS = ["systemd", "launchd", "script"];
+var UNIT = "claw-connector.service";
+var LABEL = "com.primusclaw.connector";
+var RESTART_SEC = 5;
+var NEEDS_PERSON = 78;
+var CARRIED_ENV = [
+  "PATH",
+  "CLAW_CONNECTOR_HOME",
+  "XDG_CONFIG_HOME",
+  "XDG_STATE_HOME",
+  "CLAUDE_CONFIG_DIR",
+  "CODEX_HOME",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "HTTP_PROXY",
+  "http_proxy",
+  "NO_PROXY",
+  "no_proxy",
+  "LANG"
+];
+var SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i;
+function deps(ctx) {
+  const d = ctx.service ?? {};
+  return {
+    platform: d.platform ?? process.platform,
+    home: d.home ?? os5.homedir(),
+    uid: d.uid ?? (process.getuid?.() ?? 0),
+    user: d.user ?? (ctx.env.USER || os5.userInfo().username),
+    exec: d.exec ?? ((cmd, args) => {
+      const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 3e4, stdio: ["ignore", "pipe", "pipe"] });
+      return { code: r.error ? null : r.status, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+    }),
+    node: d.node ?? ctx.node ?? process.execPath,
+    cli: d.cli ?? fileURLToPath(import.meta.url),
+    systemdBooted: d.systemdBooted ?? (() => fs15.existsSync("/run/systemd/system"))
+  };
+}
+var systemdUnitPath = (ctx, d) => path16.join(ctx.env.XDG_CONFIG_HOME?.trim() || path16.join(d.home, ".config"), "systemd", "user", UNIT);
+var launchdPlistPath = (d) => path16.join(d.home, "Library", "LaunchAgents", `${LABEL}.plist`);
+function detectSupervisor(d) {
+  if (d.platform === "darwin") return "launchd";
+  if (!d.systemdBooted()) return "script";
+  const state = d.exec("systemctl", ["--user", "is-system-running"]).out.trim();
+  return ["running", "degraded", "starting", "initializing"].includes(state) ? "systemd" : "script";
+}
+var hasUserinfo = (v) => {
+  try {
+    const u = new URL(v);
+    return u.username !== "" || u.password !== "";
+  } catch {
+    return /\/\/[^/]*@/.test(v);
+  }
+};
+function carriedEnv(env, extra = []) {
+  const vars = [];
+  const refused = [];
+  const withheld = [];
+  for (const name of /* @__PURE__ */ new Set([...CARRIED_ENV, ...extra])) {
+    if (!CARRIED_ENV.includes(name) && SECRET_NAME.test(name)) {
+      refused.push(name);
+      continue;
+    }
+    const v = env[name];
+    if (v === void 0 || v === "") continue;
+    if (/proxy$/i.test(name) && hasUserinfo(v) && !extra.includes(name)) {
+      withheld.push(name);
+      continue;
+    }
+    vars.push([name, v]);
+  }
+  return { vars, refused, withheld };
+}
+var sdEnv = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+var sdQuote = (s) => sdEnv(s).replace(/\$/g, "$$$$");
+var xml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+var sh = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+function systemdUnit(d, vars) {
+  return `# Written by "claw-connector service install"; remove with "claw-connector service uninstall".
+[Unit]
+Description=Claw connector (claw-connector run)
+Wants=network-online.target
+After=network-online.target
+# Never give up: a machine that was offline for an hour must still come back by itself.
+StartLimitIntervalSec=0
+
+[Service]
+Type=simple
+ExecStart=${sdQuote(d.node)} ${sdQuote(d.cli)} run --supervised
+${vars.map(([k, v]) => `Environment=${sdEnv(`${k}=${v}`)}`).join("\n")}
+Restart=on-failure
+RestartSec=${RESTART_SEC}
+# 78: revoked, sign-in refused, or no usable config. Restarting cannot help; "claw-connector login" can.
+RestartPreventExitStatus=${NEEDS_PERSON}
+# "claw-connector stop" and "systemctl --user stop" both end it cleanly (exit 0), which is not restarted.
+KillMode=mixed
+TimeoutStopSec=20
+
+[Install]
+WantedBy=default.target
+`;
+}
+function launchdPlist(d, vars, log) {
+  const env = [...vars, ["CLAW_CONNECTOR_SUPERVISOR", "launchd"]];
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- Written by "claw-connector service install"; remove with "claw-connector service uninstall". -->
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array><string>${xml(d.node)}</string><string>${xml(d.cli)}</string><string>run</string><string>--supervised</string></array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env.map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`).join("\n")}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <!-- Restarted after any exit but a clean one. After a revocation a restarted run sees needs-login.json and exits 0. -->
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>${RESTART_SEC}</integer>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+}
+function keepaliveScript(d, vars) {
+  return `#!/bin/sh
+# Written by "claw-connector service install --supervisor script". Idempotent: starts the connector's supervisor
+# unless it is already running, and does nothing after a revocation until "claw-connector login".
+# Call it from the container's startup hook and every 5 minutes, for example:
+#   @reboot  sh ${"$"}HOME/.../keepalive.sh        */5 * * * *  sh ${"$"}HOME/.../keepalive.sh
+${vars.map(([k, v]) => `export ${k}=${sh(v)}`).join("\n")}
+exec ${sh(d.node)} ${sh(d.cli)} service ensure
+`;
+}
+function readPidRec(file) {
+  try {
+    const raw = JSON.parse(fs15.readFileSync(file, "utf8"));
+    if (isObject(raw) && typeof raw.pid === "number" && typeof raw.start === "string" && raw.start !== "") return { pid: raw.pid, start: raw.start };
+  } catch {
+  }
+  return null;
+}
+function supervisorPid(ctx) {
+  const r = readPidRec(supervisorPidFile(ctx.dirs));
+  return r && processStart(r.pid) === r.start ? r.pid : null;
+}
+async function supervise(ctx, o = {}) {
+  const d = deps(ctx);
+  const [cmd, args] = o.command ?? [d.node, [d.cli, "run", "--supervised"]];
+  const restartMs = o.restartMs ?? RESTART_SEC * 1e3;
+  const pidf = supervisorPidFile(ctx.dirs);
+  const other = supervisorPid(ctx);
+  if (other !== null && other !== process.pid) {
+    ctx.err(`a supervisor is already running (pid ${other})`);
+    return 1;
+  }
+  fs15.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  fs15.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
+  let stopping2 = false;
+  let child = null;
+  const wake = new AbortController();
+  const onSig = (sig) => {
+    stopping2 = true;
+    wake.abort();
+    child?.kill(sig);
+  };
+  const sigs = ["SIGTERM", "SIGINT", "SIGHUP"];
+  const handlers = sigs.map((s) => [s, () => onSig(s)]);
+  for (const [s, h] of handlers) process.on(s, h);
+  o.signal?.addEventListener("abort", () => onSig("SIGTERM"), { once: true });
+  try {
+    for (let round = 0; !stopping2; round++) {
+      child = spawn2(cmd, args, { stdio: ["ignore", "inherit", "inherit"], env: ctx.env });
+      const c = child;
+      const { code, signal } = await new Promise((resolve) => {
+        c.once("exit", (code2, signal2) => resolve({ code: code2, signal: signal2 }));
+        c.once("error", (e) => {
+          ctx.err(`supervisor: cannot start the connector: ${errMessage(e)}`);
+          resolve({ code: 1, signal: null });
+        });
+      });
+      child = null;
+      const at = (/* @__PURE__ */ new Date()).toISOString();
+      if (stopping2) return 0;
+      if (code === 0) {
+        ctx.err(`${at} supervisor: the connector stopped on purpose (exit 0); not restarting`);
+        return 0;
+      }
+      if (code === NEEDS_PERSON) {
+        ctx.err(`${at} supervisor: the connector needs a new sign-in (exit 78); not restarting until: claw-connector login`);
+        return NEEDS_PERSON;
+      }
+      const how = signal ? `killed by ${signal}` : `exit ${code}`;
+      if (signal) recordDisconnect(ctx.dirs, { reason: "process_died", detail: `the connector was ${how}; restarted by the supervisor` });
+      ctx.err(`${at} supervisor: the connector ended (${how}); restarting in ${restartMs / 1e3} s`);
+      await sleep(restartMs, wake.signal);
+    }
+    return 0;
+  } finally {
+    for (const [s, h] of handlers) process.off(s, h);
+    const rec = readPidRec(pidf);
+    if (rec?.pid === process.pid) fs15.rmSync(pidf, { force: true });
+  }
+}
+async function cmdSupervise(_args, ctx) {
+  return supervise(ctx);
+}
+async function ensure(ctx, d, h) {
+  const sup = supervisorPid(ctx);
+  if (sup !== null) {
+    ctx.out(`supervisor running (pid ${sup})`);
+    return 0;
+  }
+  const problem = h.preflight(ctx);
+  if (problem) {
+    ctx.err(`not starting: ${problem}`);
+    return NEEDS_PERSON;
+  }
+  const run2 = h.runningPid(ctx);
+  if (run2 !== null) {
+    ctx.out(`the connector is running (pid ${run2}) without the supervisor; leaving it`);
+    return 0;
+  }
+  fs15.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  const log = fs15.openSync(runLogFile(ctx.dirs), "a", 384);
+  try {
+    const p = spawn2(d.node, [d.cli, "supervise"], { detached: true, cwd: d.home, stdio: ["ignore", log, log], env: ctx.env });
+    p.unref();
+    ctx.out(`started the supervisor (pid ${p.pid}); log: ${runLogFile(ctx.dirs)}`);
+  } finally {
+    fs15.closeSync(log);
+  }
+  return 0;
+}
+async function cmdService(args, ctx, h) {
+  const [sub, ...rest] = args;
+  const usage = "usage: claw-connector service install|uninstall|status [--supervisor systemd|launchd|script] [--env NAME ...]";
+  if (!["install", "uninstall", "status", "ensure"].includes(sub ?? "")) {
+    ctx.err(usage);
+    return 2;
+  }
+  const { values } = parseArgs({ args: rest, strict: true, options: { supervisor: { type: "string" }, env: { type: "string", multiple: true }, json: { type: "boolean" } } });
+  const d = deps(ctx);
+  if (sub === "ensure") return ensure(ctx, d, h);
+  let sup;
+  if (values.supervisor !== void 0) {
+    if (!SUPERVISORS.includes(values.supervisor)) {
+      ctx.err(usage);
+      return 2;
+    }
+    sup = values.supervisor;
+  } else {
+    sup = sub === "install" ? detectSupervisor(d) : installedSupervisor(ctx) ?? detectSupervisor(d);
+  }
+  if (sub === "install") return install(ctx, d, h, sup, values.env ?? []);
+  if (sub === "uninstall") return uninstall(ctx, d, sup);
+  return status(ctx, d, h, values.json === true);
+}
+function installedSupervisor(ctx) {
+  try {
+    const raw = JSON.parse(fs15.readFileSync(serviceFile(ctx.dirs), "utf8"));
+    if (isObject(raw) && typeof raw.supervisor === "string" && SUPERVISORS.includes(raw.supervisor)) return raw.supervisor;
+  } catch {
+  }
+  return null;
+}
+function startAfterLogin(ctx, h) {
+  const sup = installedSupervisor(ctx);
+  if (!sup) return;
+  const d = deps(ctx);
+  if (h.runningPid(ctx) !== null) return;
+  let r;
+  if (sup === "systemd") r = d.exec("systemctl", ["--user", "restart", UNIT]);
+  else if (sup === "launchd") r = d.exec("launchctl", ["kickstart", "-k", `gui/${d.uid}/${LABEL}`]);
+  else {
+    void ensure(ctx, d, h);
+    return;
+  }
+  ctx.out(r.code === 0 ? `started the ${sup} service again` : `could not start the ${sup} service (${r.out || `exit ${r.code}`}); run: claw-connector service install`);
+}
+function writeFile600(file, body, mode = 384) {
+  fs15.mkdirSync(path16.dirname(file), { recursive: true, mode: 448 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs15.writeFileSync(tmp, body, { mode });
+  fs15.renameSync(tmp, file);
+}
+async function install(ctx, d, h, sup, extra) {
+  const problem = h.preflight(ctx);
+  if (problem) {
+    ctx.err(`cannot install the service yet: ${problem}`);
+    return NEEDS_PERSON;
+  }
+  if (!fs15.existsSync(d.cli)) {
+    ctx.err(`${d.cli} does not exist (a source checkout needs "npm run build" first)`);
+    return 1;
+  }
+  const { vars, refused, withheld } = carriedEnv(ctx.env, extra);
+  for (const r of refused) ctx.err(`--env ${r}: not carried into the service (it looks like a credential)`);
+  for (const w of withheld) ctx.err(`${w}: not carried into the service because it holds a password; if the connector needs it, install again with --env ${w} (it is then written into the 0600 unit file)`);
+  const manual = h.runningPid(ctx);
+  if (manual !== null && supervisorPid(ctx) === null) {
+    await h.stop(ctx);
+    ctx.out(`stopped the connector that was running by hand (pid ${manual}) so the service takes over`);
+  }
+  ctx.out(`carrying into the service: ${vars.map(([k]) => k).join(", ") || "nothing"}`);
+  if (sup === "systemd") {
+    const unit = systemdUnitPath(ctx, d);
+    writeFile600(unit, systemdUnit(d, vars));
+    recordInstalled(ctx, "systemd");
+    if (!d.systemdBooted()) {
+      ctx.err("systemd is not this machine's init (no /run/systemd/system): use --supervisor script");
+      return 1;
+    }
+    for (const a of [["--user", "daemon-reload"], ["--user", "enable", UNIT], ["--user", "restart", UNIT]]) {
+      const r = d.exec("systemctl", a);
+      if (r.code !== 0) {
+        ctx.err(`systemctl ${a.join(" ")} failed: ${r.out || `exit ${r.code}`}`);
+        return 1;
+      }
+    }
+    const st = d.exec("systemctl", ["--user", "is-active", UNIT]).out.trim();
+    if (st !== "active" && st !== "activating") {
+      ctx.err(`the unit did not start (is-active: ${st || "nothing"}); see: journalctl --user -u ${UNIT}`);
+      return 1;
+    }
+    ctx.out(`installed ${unit} and started it (systemctl --user status ${UNIT}; logs: journalctl --user -u ${UNIT})`);
+    const linger = d.exec("loginctl", ["show-user", d.user, "-p", "Linger", "--value"]);
+    if (linger.out.trim() !== "yes") ctx.out(`to keep it running when you are not logged in and start it at boot, run once: loginctl enable-linger ${d.user}`);
+  } else if (sup === "launchd") {
+    const plist = launchdPlistPath(d);
+    writeFile600(plist, launchdPlist(d, vars, runLogFile(ctx.dirs)));
+    recordInstalled(ctx, "launchd");
+    d.exec("launchctl", ["bootout", `gui/${d.uid}/${LABEL}`]);
+    const r = d.exec("launchctl", ["bootstrap", `gui/${d.uid}`, plist]);
+    if (r.code !== 0) {
+      ctx.err(`launchctl bootstrap failed: ${r.out || `exit ${r.code}`}`);
+      return 1;
+    }
+    ctx.out(`installed ${plist} and started it (launchctl print gui/${d.uid}/${LABEL}; log: ${runLogFile(ctx.dirs)})`);
+  } else {
+    const script = keepaliveFile(ctx.dirs);
+    writeFile600(script, keepaliveScript(d, vars), 448);
+    recordInstalled(ctx, "script");
+    const code = await ensure(ctx, d, h);
+    if (code !== 0) return code;
+    ctx.out(`wrote ${script}. This machine has no systemd: the supervisor restarts the connector 5 s after it dies, but`);
+    ctx.out("nothing starts the supervisor after a reboot or a container restart. Add both of these (crontab -e, or your container's startup hook):");
+    ctx.out(`  @reboot sh ${script}`);
+    ctx.out(`  */5 * * * * sh ${script}`);
+  }
+  return 0;
+}
+function recordInstalled(ctx, sup) {
+  writeFile600(serviceFile(ctx.dirs), JSON.stringify({ supervisor: sup, installed_at: (/* @__PURE__ */ new Date()).toISOString() }));
+}
+async function uninstall(ctx, d, sup) {
+  fs15.rmSync(serviceFile(ctx.dirs), { force: true });
+  if (sup === "systemd") {
+    const unit = systemdUnitPath(ctx, d);
+    d.exec("systemctl", ["--user", "disable", "--now", UNIT]);
+    const had = fs15.existsSync(unit);
+    fs15.rmSync(unit, { force: true });
+    d.exec("systemctl", ["--user", "daemon-reload"]);
+    ctx.out(had ? `stopped and removed ${unit}` : `no unit at ${unit}`);
+  } else if (sup === "launchd") {
+    const plist = launchdPlistPath(d);
+    d.exec("launchctl", ["bootout", `gui/${d.uid}/${LABEL}`]);
+    const had = fs15.existsSync(plist);
+    fs15.rmSync(plist, { force: true });
+    ctx.out(had ? `stopped and removed ${plist}` : `no LaunchAgent at ${plist}`);
+  } else {
+    const pid = supervisorPid(ctx);
+    if (pid !== null) {
+      process.kill(pid, "SIGTERM");
+      const end = Date.now() + 2e4;
+      while (Date.now() < end && isAlive(pid) && processStart(pid) !== null) await sleep(100);
+    }
+    const script = keepaliveFile(ctx.dirs);
+    const had = fs15.existsSync(script);
+    fs15.rmSync(script, { force: true });
+    ctx.out(`${pid !== null ? `stopped the supervisor (pid ${pid}) and the connector; ` : ""}${had ? `removed ${script}` : "no keep-alive script"}. Remove the @reboot and */5 lines that call it.`);
+  }
+  return 0;
+}
+function status(ctx, d, h, json) {
+  const sup = installedSupervisor(ctx);
+  let active = null;
+  if (sup === "systemd") active = d.exec("systemctl", ["--user", "is-active", UNIT]).out.trim() || null;
+  else if (sup === "launchd") active = d.exec("launchctl", ["print", `gui/${d.uid}/${LABEL}`]).code === 0 ? "loaded" : "not loaded";
+  else if (sup === "script") {
+    const p = supervisorPid(ctx);
+    active = p !== null ? `supervisor pid ${p}` : "supervisor not running";
+  }
+  const st = {
+    installed: sup,
+    active,
+    running: h.runningPid(ctx),
+    needs_login: needsLogin(ctx.dirs),
+    recent_disconnects: recentDisconnects(ctx.dirs, 5)
+  };
+  if (json) {
+    ctx.out(JSON.stringify(st, null, 2));
+    return 0;
+  }
+  ctx.out(`service:    ${sup ? `${sup} (${active})` : "not installed; run: claw-connector service install"}`);
+  ctx.out(`connector:  ${st.running !== null ? `running (pid ${st.running})` : "not running"}`);
+  if (st.needs_login) ctx.out(`problem:    needs a new sign-in: ${st.needs_login.reason}; run: claw-connector login`);
+  for (const x of st.recent_disconnects) ctx.out(`down:       ${x.at} ${x.reason}${x.detail ? ` (${x.detail})` : ""}`);
+  return 0;
+}
+
 // src/version.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.3";
 
 // src/commands.ts
-var EXIT = { ok: 0, failure: 1, usage: 2, revoked: 3 };
+var EXIT = { ok: 0, failure: 1, usage: 2, needsPerson: 78, revoked: 78 };
 var HELP = `claw-connector ${VERSION}: connect the coding agents on this machine to Claw (outbound HTTPS only).
 
 Usage: claw-connector <command> [options]
@@ -3641,8 +4200,13 @@ Usage: claw-connector <command> [options]
                            directories, else $CLAUDE_CONFIG_DIR or ~/.claude); only its own entries are ever changed
   login                    sign in (device flow); --server URL --identity-url URL [--name HOST]
                            development only: --key <api key>  (or CLAW_CONNECTOR_KEY)
-  run                      connect and serve (Ctrl-C or SIGTERM stops it and every agent it started)
-  status [--json]          what is running, signed in, paused
+  run                      connect and serve (Ctrl-C or SIGTERM stops it and every agent it started). Exit code 78:
+                           revoked, sign-in refused, or no usable config; starting it again will not help
+  service install|uninstall|status [--supervisor systemd|launchd|script] [--env NAME ...]
+                           keep "run" up: started at login/boot, restarted 5 s after it dies, never restarted
+                           after exit 78. systemd --user on Linux, launchd on macOS; "script" (containers without
+                           systemd) writes a keep-alive script for a startup hook and a 5-minute cron line
+  status [--json]          what is running, signed in, paused, the last disconnect and why
   pause                    stop every agent now and stay offline until "resume"
   resume                   undo "pause"
   stop                     stop the running connector and every agent it started
@@ -3653,7 +4217,7 @@ Files: ${"$"}XDG_CONFIG_HOME/claw-connector (agents.toml, credentials.json) and
 (audit.jsonl, logs, outbox); set CLAW_CONNECTOR_HOME to keep everything under one directory.
 `;
 function loadCfg(ctx) {
-  return loadConfig(configFile(ctx.dirs), { hostname: ctx.hostname ?? os5.hostname() });
+  return loadConfig(configFile(ctx.dirs), { hostname: ctx.hostname ?? os6.hostname() });
 }
 var noAsk = (ctx, cfg) => noAskWarnings(cfg.agents, ctx.env, { managedFile: ctx.claudeManagedSettings, euid: ctx.euid });
 function serverUrl(ctx, flag, cfg, creds) {
@@ -3681,8 +4245,14 @@ async function main(argv, ctx) {
         return cmdHooks(rest, ctx);
       case "login":
         return await cmdLogin(rest, ctx);
-      case "run":
-        return await cmdRun(rest, ctx);
+      case "run": {
+        const code = await cmdRun(rest, ctx);
+        return code === EXIT.needsPerson && ctx.env.CLAW_CONNECTOR_SUPERVISOR === "launchd" ? EXIT.ok : code;
+      }
+      case "service":
+        return await cmdService(rest, ctx, serviceHelpers);
+      case "supervise":
+        return await cmdSupervise(rest, ctx);
       case "status":
         return cmdStatus(rest, ctx);
       case "pause":
@@ -3724,16 +4294,16 @@ function parseApproval(values) {
   return out;
 }
 async function cmdInit(args, ctx) {
-  const { values } = parseArgs({ args, strict: true, options: { approval: { type: "string", multiple: true }, "no-hooks": { type: "boolean" } } });
+  const { values } = parseArgs2({ args, strict: true, options: { approval: { type: "string", multiple: true }, "no-hooks": { type: "boolean" } } });
   const approval = parseApproval(values.approval ?? []);
   if (typeof approval === "string") {
     ctx.err(approval);
     return EXIT.usage;
   }
   const file = configFile(ctx.dirs);
-  fs14.mkdirSync(path15.dirname(file), { recursive: true, mode: 448 });
+  fs16.mkdirSync(path17.dirname(file), { recursive: true, mode: 448 });
   try {
-    fs14.writeFileSync(file, sampleConfig(approval), { mode: 384, flag: "wx" });
+    fs16.writeFileSync(file, sampleConfig(approval), { mode: 384, flag: "wx" });
     ctx.out(`wrote ${file}: edit the roots (the directories an agent may work in), then run: claw-connector login`);
     const { unattended, parked } = sampleApprovals(approval);
     ctx.out(unattended.length ? `no per-step approval for: ${unattended.join(", ")}. Those agents write files and run commands without asking; the phone shows such a session as unattended. To go back, set approval = "ask" on the agent.` : `every agent in this file asks before it writes a file or runs a command. To let phone sessions run like your terminal instead: claw-connector init --approval never (on a new file), or set approval = "never" on an agent.`);
@@ -3744,7 +4314,7 @@ async function cmdInit(args, ctx) {
   }
   if (!values["no-hooks"]) {
     const dir = defaultClaudeDir(ctx);
-    if (!fs14.existsSync(dir)) ctx.out(`no Claude Code directory at ${dir}; once you use Claude Code, run: claw-connector hooks install`);
+    if (!fs16.existsSync(dir)) ctx.out(`no Claude Code directory at ${dir}; once you use Claude Code, run: claw-connector hooks install`);
     else installForInit(ctx, dir);
   }
   return EXIT.ok;
@@ -3756,19 +4326,19 @@ function installForInit(ctx, dir) {
     ctx.err(`hooks: ${errMessage(e)} (everything else is set up; fix it and run: claw-connector hooks install)`);
   }
 }
-var defaultClaudeDir = (ctx) => path15.resolve(ctx.env.CLAUDE_CONFIG_DIR?.trim() || path15.join(os5.homedir(), ".claude"));
+var defaultClaudeDir = (ctx) => path17.resolve(ctx.env.CLAUDE_CONFIG_DIR?.trim() || path17.join(os6.homedir(), ".claude"));
 function claudeDirs(ctx, flag) {
-  if (flag !== void 0) return [path15.resolve(flag)];
+  if (flag !== void 0) return [path17.resolve(flag)];
   let dirs = [];
   try {
-    dirs = loadCfg(ctx).agents.filter((a) => a.attach).map((a) => path15.resolve(a.env.CLAUDE_CONFIG_DIR ?? ctx.env.CLAUDE_CONFIG_DIR?.trim() ?? path15.join(os5.homedir(), ".claude")));
+    dirs = loadCfg(ctx).agents.filter((a) => a.attach).map((a) => path17.resolve(a.env.CLAUDE_CONFIG_DIR ?? ctx.env.CLAUDE_CONFIG_DIR?.trim() ?? path17.join(os6.homedir(), ".claude")));
   } catch {
   }
   return dirs.length ? [...new Set(dirs)] : [defaultClaudeDir(ctx)];
 }
 function hookScript(ctx) {
-  const script = ctx.hookScript ?? fileURLToPath(new URL("./terminal-hook.js", import.meta.url));
-  if (!fs14.existsSync(script)) throw new HooksError(`${script} does not exist (a source checkout needs "npm run build" first)`);
+  const script = ctx.hookScript ?? fileURLToPath2(new URL("./terminal-hook.js", import.meta.url));
+  if (!fs16.existsSync(script)) throw new HooksError(`${script} does not exist (a source checkout needs "npm run build" first)`);
   return script;
 }
 function installOne(ctx, dir) {
@@ -3781,14 +4351,14 @@ function cmdHooks(args, ctx) {
     ctx.err("usage: claw-connector hooks install|uninstall|status [--config-dir DIR]");
     return EXIT.usage;
   }
-  const { values } = parseArgs({ args: rest, strict: true, options: { "config-dir": { type: "string" }, json: { type: "boolean" } } });
+  const { values } = parseArgs2({ args: rest, strict: true, options: { "config-dir": { type: "string" }, json: { type: "boolean" } } });
   const dirs = claudeDirs(ctx, values["config-dir"]);
   let code = EXIT.ok;
   const report = [];
   for (const dir of dirs) {
     try {
       if (sub === "install") {
-        if (values["config-dir"] === void 0 && !fs14.existsSync(dir)) {
+        if (values["config-dir"] === void 0 && !fs16.existsSync(dir)) {
           ctx.err(`no Claude Code directory at ${dir}; pass --config-dir to name one`);
           code = EXIT.failure;
           continue;
@@ -3813,14 +4383,14 @@ function forgetRevokedIdentity(ctx) {
   const file = identityFile(ctx.dirs);
   let revoked = false;
   try {
-    const raw = JSON.parse(fs14.readFileSync(file, "utf8"));
+    const raw = JSON.parse(fs16.readFileSync(file, "utf8"));
     revoked = isObject(raw) && raw.revoked === true;
   } catch {
   }
-  if (revoked) fs14.rmSync(file, { force: true });
+  if (revoked) fs16.rmSync(file, { force: true });
 }
 async function cmdLogin(args, ctx) {
-  const { values } = parseArgs({
+  const { values } = parseArgs2({
     args,
     strict: true,
     options: { server: { type: "string" }, "identity-url": { type: "string" }, key: { type: "string" }, name: { type: "string" } }
@@ -3841,7 +4411,9 @@ async function cmdLogin(args, ctx) {
   if (key) {
     saveCredentials(file, { v: 1, server, kind: "key", key, saved_at: (/* @__PURE__ */ new Date()).toISOString() });
     forgetRevokedIdentity(ctx);
+    clearNeedsLogin(ctx.dirs);
     ctx.out("saved a development key. This is for trying things out: a device sign-in is the normal way (omit --key).");
+    startAfterLogin(ctx, serviceHelpers);
     return EXIT.ok;
   }
   const identityRaw = (values["identity-url"] ?? ctx.env.CLAW_IDENTITY_URL ?? cfg?.identityUrl ?? "").trim();
@@ -3850,7 +4422,7 @@ async function cmdLogin(args, ctx) {
     ctx.err("login needs --identity-url <identity service URL> (or CLAW_IDENTITY_URL, or identity_url = in agents.toml)");
     return EXIT.usage;
   }
-  const deviceName = values.name ?? cfg?.name ?? ctx.hostname ?? os5.hostname();
+  const deviceName = values.name ?? cfg?.name ?? ctx.hostname ?? os6.hostname();
   const tok = await deviceLogin({ identityUrl, deviceName, fetch: ctx.fetch, print: ctx.out });
   saveCredentials(file, {
     v: 1,
@@ -3863,27 +4435,47 @@ async function cmdLogin(args, ctx) {
     saved_at: (/* @__PURE__ */ new Date()).toISOString()
   });
   forgetRevokedIdentity(ctx);
-  ctx.out(`signed in as ${deviceName}. Next: claw-connector run`);
+  clearNeedsLogin(ctx.dirs);
+  ctx.out(`signed in as ${deviceName}. Next: claw-connector service install (or run)`);
+  startAfterLogin(ctx, serviceHelpers);
   return EXIT.ok;
 }
 function runningPid(ctx) {
   try {
-    const raw = JSON.parse(fs14.readFileSync(pidFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs16.readFileSync(pidFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.pid === "number" && typeof raw.start === "string" && raw.start !== "" && processStart(raw.pid) === raw.start) return raw.pid;
   } catch {
   }
   return null;
 }
-async function cmdRun(_args, ctx) {
-  const cfg = loadCfg(ctx);
+async function cmdRun(args, ctx) {
+  parseArgs2({ args, strict: true, options: { supervised: { type: "boolean" } } });
+  {
+    const nl = needsLogin(ctx.dirs);
+    if (nl) {
+      ctx.err(`not starting: ${nl.reason}${nl.at ? ` (${nl.at})` : ""}. Sign in again (claw-connector login); the service then starts it.`);
+      return EXIT.needsPerson;
+    }
+  }
+  let cfg;
+  let creds;
+  try {
+    cfg = loadCfg(ctx);
+    creds = loadCredentials(credentialsFile(ctx.dirs));
+  } catch (e) {
+    if (e instanceof ConfigError || e instanceof CredentialsError) {
+      ctx.err(e.message);
+      return EXIT.needsPerson;
+    }
+    throw e;
+  }
   if (cfg.agents.length === 0) {
     ctx.err("agents.toml defines no agents; add an [[agents]] table");
-    return EXIT.failure;
+    return EXIT.needsPerson;
   }
-  const creds = loadCredentials(credentialsFile(ctx.dirs));
   if (!creds) {
     ctx.err("not signed in: run  claw-connector login");
-    return EXIT.failure;
+    return EXIT.needsPerson;
   }
   const running = runningPid(ctx);
   if (running !== null) {
@@ -3902,12 +4494,23 @@ async function cmdRun(_args, ctx) {
   try {
     const result = await connector2.run();
     if (result === "revoked") {
+      markNeedsLogin(ctx.dirs, "this connector was revoked");
       ctx.err("this connector was revoked: every agent was stopped. Run login again to connect it anew.");
       return EXIT.revoked;
     }
+    if (result === "auth_failed") {
+      markNeedsLogin(ctx.dirs, `Claw refused the sign-in (${connector2.authFailure})`);
+      ctx.err(`Claw keeps refusing this sign-in (${connector2.authFailure}): every agent was stopped. Run login again.`);
+      return EXIT.needsPerson;
+    }
     return EXIT.ok;
   } catch (e) {
-    if (e instanceof HttpError || e instanceof TransportError || e instanceof RevokedError || e instanceof GrantRevokedError) {
+    if (isAuthRefusal(e) || e instanceof RevokedError || e instanceof GrantRevokedError || e instanceof CredentialsError) {
+      markNeedsLogin(ctx.dirs, e instanceof GrantRevokedError || e instanceof RevokedError ? e.message : `Claw refused the sign-in (${errMessage(e)})`);
+      ctx.err(`error: ${errMessage(e)}. Run login again.`);
+      return EXIT.needsPerson;
+    }
+    if (e instanceof HttpError || e instanceof TransportError) {
       ctx.err(`error: ${e.message}`);
       return EXIT.failure;
     }
@@ -3915,7 +4518,7 @@ async function cmdRun(_args, ctx) {
   }
 }
 function cmdStatus(args, ctx) {
-  const { values } = parseArgs({ args, strict: true, options: { json: { type: "boolean" } } });
+  const { values } = parseArgs2({ args, strict: true, options: { json: { type: "boolean" } } });
   let creds = null;
   let credsProblem = null;
   try {
@@ -3937,15 +4540,15 @@ function cmdStatus(args, ctx) {
   }
   let connectorId = null;
   try {
-    const raw = JSON.parse(fs14.readFileSync(identityFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs16.readFileSync(identityFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.connector_id === "string") connectorId = raw.connector_id;
   } catch {
   }
   const reg = new ChildRegistry(childrenFile(ctx.dirs));
-  const status = {
+  const status2 = {
     version: VERSION,
     running: runningPid(ctx),
-    paused: fs14.existsSync(pauseFile(ctx.dirs)),
+    paused: fs16.existsSync(pauseFile(ctx.dirs)),
     signed_in: creds ? { kind: creds.kind, server: creds.server, device_name: creds.device_name ?? null } : null,
     connector_id: connectorId,
     agents,
@@ -3954,23 +4557,28 @@ function cmdStatus(args, ctx) {
     adapters: reg.list().filter((r) => reg.isOurs(r)).map((r) => ({ pid: r.pid, agent: r.agent_id, session: r.session_id })),
     problems: [credsProblem, configProblem].filter((x) => !!x),
     /** Agents whose sessions will be refused as things stand (Claude's own settings start them in a mode that never asks). */
-    warnings
+    warnings,
+    /** Why the connection last went down, and whether only a new sign-in can bring it back. */
+    last_disconnect: recentDisconnects(ctx.dirs, 1)[0] ?? null,
+    needs_login: needsLogin(ctx.dirs)
   };
   if (values.json) {
-    ctx.out(JSON.stringify(status, null, 2));
+    ctx.out(JSON.stringify(status2, null, 2));
     return EXIT.ok;
   }
-  ctx.out(`connector:  ${status.running ? `running (pid ${status.running})` : "not running"}${status.paused ? ", PAUSED" : ""}`);
+  ctx.out(`connector:  ${status2.running ? `running (pid ${status2.running})` : "not running"}${status2.paused ? ", PAUSED" : ""}`);
   ctx.out(`signed in:  ${creds ? `${creds.kind} to ${creds.server}` : "no"}`);
   ctx.out(`agents:     ${agents.map((a) => unattended.includes(a) ? `${a} (no per-step approval)` : a).join(", ") || "none configured"}`);
-  ctx.out(`adapters:   ${status.adapters.length ? status.adapters.map((a) => `${a.agent} pid ${a.pid}`).join(", ") : "none running"}`);
-  for (const p of status.problems) ctx.out(`problem:    ${p}`);
-  for (const w of status.warnings) ctx.out(`warning:    ${w}`);
+  ctx.out(`adapters:   ${status2.adapters.length ? status2.adapters.map((a) => `${a.agent} pid ${a.pid}`).join(", ") : "none running"}`);
+  if (status2.last_disconnect) ctx.out(`last down:  ${status2.last_disconnect.at} ${status2.last_disconnect.reason}${status2.last_disconnect.detail ? ` (${status2.last_disconnect.detail})` : ""}`);
+  if (status2.needs_login) ctx.out(`problem:    needs a new sign-in: ${status2.needs_login.reason}; run: claw-connector login`);
+  for (const p of status2.problems) ctx.out(`problem:    ${p}`);
+  for (const w of status2.warnings) ctx.out(`warning:    ${w}`);
   return EXIT.ok;
 }
 async function cmdPause(ctx) {
-  fs14.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
-  fs14.writeFileSync(pauseFile(ctx.dirs), (/* @__PURE__ */ new Date()).toISOString() + "\n", { mode: 384 });
+  fs16.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  fs16.writeFileSync(pauseFile(ctx.dirs), (/* @__PURE__ */ new Date()).toISOString() + "\n", { mode: 384 });
   if (runningPid(ctx) === null) {
     const left = await new ChildRegistry(childrenFile(ctx.dirs)).killAll();
     ctx.out(`paused (the connector is not running${left.killed.length ? `; stopped ${left.killed.length} leftover agent process group(s)` : ""})`);
@@ -3980,7 +4588,7 @@ async function cmdPause(ctx) {
   return EXIT.ok;
 }
 function cmdResume(ctx) {
-  fs14.rmSync(pauseFile(ctx.dirs), { force: true });
+  fs16.rmSync(pauseFile(ctx.dirs), { force: true });
   ctx.out(runningPid(ctx) === null ? "resumed; start it with: claw-connector run" : "resumed: the running connector reconnects now");
   return EXIT.ok;
 }
@@ -4020,11 +4628,26 @@ async function cmdLogout(ctx) {
       ctx.err(`could not revoke the sign-in at the identity service (${errMessage(e)}); it was removed from this machine`);
     }
   }
-  fs14.rmSync(file, { force: true });
+  fs16.rmSync(file, { force: true });
   forgetRevokedIdentity(ctx);
   ctx.out("signed out");
   return EXIT.ok;
 }
+var serviceHelpers = {
+  runningPid,
+  stop: (ctx) => cmdStop(ctx, true),
+  preflight: (ctx) => {
+    try {
+      const cfg = loadCfg(ctx);
+      if (cfg.agents.length === 0) return "agents.toml defines no agents; add an [[agents]] table";
+      if (!loadCredentials(credentialsFile(ctx.dirs))) return "not signed in: run  claw-connector login";
+    } catch (e) {
+      return errMessage(e);
+    }
+    const nl = needsLogin(ctx.dirs);
+    return nl ? `${nl.reason}: run  claw-connector login  first` : null;
+  }
+};
 
 // src/cli.ts
 var connector = null;