hanoman 0.1.58 → 0.1.59

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.58",
-  "sha": "36f46443",
-  "builtAt": "2026-08-23T16:44:16.513Z"
+  "version": "0.1.59",
+  "sha": "efcde67d",
+  "builtAt": "2026-08-24T03:26:58.817Z"
 }

package/dist/cli.js

@@ -6109,6 +6109,8 @@ var init_api = __esm({
       sessionTranscript: (id) => `${API}/terminal/history/${encodeURIComponent(id)}/transcript`,
       eventsWs: `${API}/events/ws`,
       // SPEC-199 · WebSocket siar dashboard (global, bukan per-sesi)
+      // SPEC-919 · ADR-0147 · muat awal + fallback halaman Klien. Selama WS sehat tak ada yang men-poll-nya.
+      presence: `${API}/presence`,
       wsTickets: `${API}/ws-tickets`,
       vps: `${API}/vps`,
       vpsOne: (id) => `${API}/vps/${id}`,
@@ -7751,6 +7753,34 @@ var init_session_ask = __esm({
   }
 });
 
+// ../shared/src/presence.ts
+var PRESENCE_PROTOCOL, MAX_PRESENCE_SESSIONS, PRESENCE_MAX_FRAME_BYTES, zPresenceSession, zPresenceFrame;
+var init_presence = __esm({
+  "../shared/src/presence.ts"() {
+    "use strict";
+    init_zod();
+    PRESENCE_PROTOCOL = 1;
+    MAX_PRESENCE_SESSIONS = 100;
+    PRESENCE_MAX_FRAME_BYTES = 32 * 1024;
+    zPresenceSession = external_exports.object({
+      sessionId: external_exports.string().min(1).max(200),
+      projectId: external_exports.string().min(1).max(200),
+      specId: external_exports.string().max(200).optional(),
+      flow: external_exports.string().max(40).optional(),
+      /** Fase `active` dari `readPhases()`. Absen = sesi tanpa berkas fase (mis. konsol VPS). */
+      phase: external_exports.string().max(80).optional(),
+      agent: external_exports.enum(["claude", "codex"]),
+      status: external_exports.enum(["working", "waiting", "exited"]),
+      startedAt: external_exports.string().max(40)
+    }).strict();
+    zPresenceFrame = external_exports.object({
+      t: external_exports.literal("presence"),
+      v: external_exports.literal(PRESENCE_PROTOCOL),
+      sessions: external_exports.array(zPresenceSession).max(MAX_PRESENCE_SESSIONS)
+    }).strict();
+  }
+});
+
 // ../shared/src/index.ts
 var init_src = __esm({
   "../shared/src/index.ts"() {
@@ -7790,6 +7820,7 @@ var init_src = __esm({
     init_terminal_io();
     init_session_dialog();
     init_session_ask();
+    init_presence();
   }
 });
 

package/dist/server.js

@@ -6563,6 +6563,8 @@ var init_api = __esm({
       sessionTranscript: (id) => `${API}/terminal/history/${encodeURIComponent(id)}/transcript`,
       eventsWs: `${API}/events/ws`,
       // SPEC-199 · WebSocket siar dashboard (global, bukan per-sesi)
+      // SPEC-919 · ADR-0147 · muat awal + fallback halaman Klien. Selama WS sehat tak ada yang men-poll-nya.
+      presence: `${API}/presence`,
       wsTickets: `${API}/ws-tickets`,
       vps: `${API}/vps`,
       vpsOne: (id) => `${API}/vps/${id}`,
@@ -8399,6 +8401,61 @@ var init_session_ask = __esm({
   }
 });
 
+// ../shared/src/presence.ts
+function trimPresenceToBudget(sessions, maxBytes = PRESENCE_MAX_FRAME_BYTES) {
+  let out4 = sessions.slice(0, MAX_PRESENCE_SESSIONS);
+  while (out4.length > 0 && Buffer.byteLength(presenceFrameJson(out4)) > maxBytes) {
+    out4 = out4.slice(0, Math.max(0, Math.floor(out4.length / 2)));
+  }
+  return out4;
+}
+function presenceSignature(sessions) {
+  return JSON.stringify(
+    [...sessions].sort((a, b) => a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0).map((s2) => [
+      s2.sessionId,
+      s2.projectId,
+      s2.specId ?? "",
+      s2.flow ?? "",
+      s2.phase ?? "",
+      s2.agent,
+      s2.status,
+      s2.startedAt
+    ])
+  );
+}
+var PRESENCE_PROTOCOL, MAX_PRESENCE_SESSIONS, PRESENCE_MAX_FRAME_BYTES, PRESENCE_TICK_MS, PRESENCE_HEARTBEAT_MS, PRESENCE_OFFLINE_MS, PRESENCE_MAX_FRAMES_PER_MIN, LOCAL_DEVICE_ID, zPresenceSession, zPresenceFrame, presenceFrameJson;
+var init_presence = __esm({
+  "../shared/src/presence.ts"() {
+    "use strict";
+    init_zod();
+    PRESENCE_PROTOCOL = 1;
+    MAX_PRESENCE_SESSIONS = 100;
+    PRESENCE_MAX_FRAME_BYTES = 32 * 1024;
+    PRESENCE_TICK_MS = 3e3;
+    PRESENCE_HEARTBEAT_MS = 3e4;
+    PRESENCE_OFFLINE_MS = 9e4;
+    PRESENCE_MAX_FRAMES_PER_MIN = 60;
+    LOCAL_DEVICE_ID = "local";
+    zPresenceSession = external_exports.object({
+      sessionId: external_exports.string().min(1).max(200),
+      projectId: external_exports.string().min(1).max(200),
+      specId: external_exports.string().max(200).optional(),
+      flow: external_exports.string().max(40).optional(),
+      /** Fase `active` dari `readPhases()`. Absen = sesi tanpa berkas fase (mis. konsol VPS). */
+      phase: external_exports.string().max(80).optional(),
+      agent: external_exports.enum(["claude", "codex"]),
+      status: external_exports.enum(["working", "waiting", "exited"]),
+      startedAt: external_exports.string().max(40)
+    }).strict();
+    zPresenceFrame = external_exports.object({
+      t: external_exports.literal("presence"),
+      v: external_exports.literal(PRESENCE_PROTOCOL),
+      sessions: external_exports.array(zPresenceSession).max(MAX_PRESENCE_SESSIONS)
+    }).strict();
+    presenceFrameJson = (sessions) => JSON.stringify({ t: "presence", v: PRESENCE_PROTOCOL, sessions });
+  }
+});
+
 // ../shared/src/index.ts
 var init_src = __esm({
   "../shared/src/index.ts"() {
@@ -8438,6 +8495,7 @@ var init_src = __esm({
     init_terminal_io();
     init_session_dialog();
     init_session_ask();
+    init_presence();
   }
 });
 
@@ -11113,7 +11171,8 @@ function parsePanes(out4) {
       agent,
       alternate,
       activity,
-      eventHook
+      eventHook,
+      created
     ] = line.split("	");
     if (!n2?.startsWith(PREFIX)) return [];
     const exited = dead === "1";
@@ -11140,6 +11199,8 @@ function parsePanes(out4) {
       agent: agent === "codex" ? "codex" : "claude",
       altScreen: alternate === "1",
       activityAt,
+      // SPEC-919 · sesi yang lahir di tmux yang tak menjawab field ini → 0 (epoch).
+      startedAt: Number(created) || 0,
       // SPEC-909 · ADR-0146 · sesi yang lahir sebelum pembaruan tak punya opsi ini → false.
       eventHook: eventHook === "1"
     }];
@@ -11709,8 +11770,11 @@ exit 1
       "#{@hanoman_branch}",
       "#{@hanoman_agent}",
       "#{alternate_on}",
+      // SPEC-919 · field baru ditambahkan di UJUNG: posisi kolom lama tak bergeser, dan
+      // `pty-parse.test.ts` mengunci panjang FMT terhadap destructuring `parsePanes`.
       "#{window_activity}",
-      "#{@hanoman_event_hook}"
+      "#{@hanoman_event_hook}",
+      "#{session_created}"
     ].join("	");
     toSessionInfo = ({
       id,
@@ -14735,6 +14799,39 @@ var init_bootstrap = __esm({
   }
 });
 
+// src/services/presence/snapshot.ts
+function paneToPresence(p, phase) {
+  return {
+    sessionId: p.id,
+    projectId: p.projectId,
+    ...p.specId ? { specId: p.specId } : {},
+    ...p.flow ? { flow: p.flow } : {},
+    ...phase ? { phase } : {},
+    agent: p.agent,
+    // Presedensi: pane mati sudah berakhir apa pun isi markernya.
+    status: p.exited ? "exited" : p.decision ? "waiting" : "working",
+    startedAt: isoFromEpochSeconds(p.startedAt)
+  };
+}
+function activePhase(p) {
+  if (!p.flow || !p.phaseFile) return void 0;
+  return readPhases(p.phaseFile, p.flow).find((f) => f.state === "active")?.name;
+}
+async function buildLocalPresence() {
+  const panes = await listPanesAsync();
+  return panes.slice(0, MAX_PRESENCE_SESSIONS).map((p) => paneToPresence(p, activePhase(p)));
+}
+var isoFromEpochSeconds;
+var init_snapshot = __esm({
+  "src/services/presence/snapshot.ts"() {
+    "use strict";
+    init_src();
+    init_pty();
+    init_session_phases();
+    isoFromEpochSeconds = (s2) => new Date((s2 || 0) * 1e3).toISOString();
+  }
+});
+
 // src/services/conflicts.ts
 function stamp(d) {
   const v = d.updatedAt;
@@ -14805,6 +14902,54 @@ var init_conflicts = __esm({
   }
 });
 
+// src/services/presence/sender.ts
+function createPresenceSender(o) {
+  const heartbeatMs = o.heartbeatMs ?? PRESENCE_HEARTBEAT_MS;
+  let lastSignature = null;
+  let lastSentAt = 0;
+  return {
+    async tick(now) {
+      let sessions;
+      try {
+        sessions = trimPresenceToBudget(await o.build());
+      } catch {
+        return;
+      }
+      const signature = presenceSignature(sessions);
+      const due = lastSignature === null || signature !== lastSignature || now - lastSentAt >= heartbeatMs;
+      if (!due) return;
+      lastSignature = signature;
+      lastSentAt = now;
+      try {
+        o.send(presenceFrameJson(sessions));
+      } catch {
+      }
+    }
+  };
+}
+function startPresenceSender(o) {
+  const sender = createPresenceSender({
+    send: o.send,
+    build: o.build ?? buildLocalPresence,
+    heartbeatMs: o.heartbeatMs
+  });
+  void sender.tick(Date.now());
+  const timer9 = setInterval(() => {
+    void sender.tick(Date.now());
+  }, o.tickMs ?? PRESENCE_TICK_MS);
+  timer9.unref?.();
+  return { stop() {
+    clearInterval(timer9);
+  } };
+}
+var init_sender = __esm({
+  "src/services/presence/sender.ts"() {
+    "use strict";
+    init_src();
+    init_snapshot();
+  }
+});
+
 // ../node_modules/.pnpm/ws@8.21.0/node_modules/ws/lib/constants.js
 var require_constants = __commonJS({
   "../node_modules/.pnpm/ws@8.21.0/node_modules/ws/lib/constants.js"(exports, module) {
@@ -18853,11 +18998,14 @@ async function startSyncClient(base2, token, tickMs2) {
   const connectWs = async () => {
     const { WebSocket: WebSocket2 } = await Promise.resolve().then(() => (init_wrapper(), wrapper_exports));
     const wsUrl = base2.replace(/^http/, "ws").replace(/\/$/, "") + "/api/sync/ws";
-    ws = new WebSocket2(wsUrl, { headers: { authorization: `Bearer ${token}` } });
-    ws.on("open", () => {
+    const sock = new WebSocket2(wsUrl, { headers: { authorization: `Bearer ${token}` } });
+    ws = sock;
+    sock.on("open", () => {
+      reconnectDelay = 0;
       void tick6();
+      presence = startPresenceSender({ send: (json) => sock.send(json) });
     });
-    ws.on("message", async (raw) => {
+    sock.on("message", async (raw) => {
       try {
         const msg = JSON.parse(raw.toString());
         if (msg.t !== "sync") return;
@@ -18865,15 +19013,19 @@ async function startSyncClient(base2, token, tickMs2) {
       } catch {
       }
     });
-    const reconnect = () => {
-      setTimeout(() => {
+    sock.on("close", () => {
+      presence?.stop();
+      presence = void 0;
+      if (!started) return;
+      reconnectDelay = nextBackoff(reconnectDelay);
+      reconnectTimer = setTimeout(() => {
         void connectWs();
-      }, 3e3);
-    };
-    ws.on("close", reconnect);
-    ws.on("error", () => {
+      }, withJitter(reconnectDelay));
+      reconnectTimer.unref?.();
+    });
+    sock.on("error", () => {
       try {
-        ws?.close();
+        sock.close();
       } catch {
       }
     });
@@ -18893,6 +19045,13 @@ function stopSyncClient() {
     clearInterval(timer4);
     timer4 = void 0;
   }
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = void 0;
+  }
+  reconnectDelay = 0;
+  presence?.stop();
+  presence = void 0;
   try {
     ws?.close();
   } catch {
@@ -18905,7 +19064,7 @@ async function applySyncConfig() {
   const token = effectiveStr("SYNC_DEVICE_TOKEN");
   if (base2 && token) await startSyncClient(base2, token, effectiveInt("SYNC_TICK_MS"));
 }
-var MAX_SYNC_RECORD_BYTES, feedHole, MAX_DRAIN_PAGES, timer4, ws, started, pullSehat;
+var MAX_SYNC_RECORD_BYTES, feedHole, MAX_DRAIN_PAGES, timer4, ws, started, RECONNECT_MIN_MS, RECONNECT_MAX_MS, nextBackoff, withJitter, reconnectTimer, reconnectDelay, presence, pullSehat;
 var init_sync_client = __esm({
   "src/services/sync-client.ts"() {
     "use strict";
@@ -18918,10 +19077,16 @@ var init_sync_client = __esm({
     init_rename_project();
     init_config2();
     init_safe_outbound_request();
+    init_sender();
     MAX_SYNC_RECORD_BYTES = 1024 * 1024;
     feedHole = false;
     MAX_DRAIN_PAGES = 500;
     started = false;
+    RECONNECT_MIN_MS = 1e3;
+    RECONNECT_MAX_MS = 3e4;
+    nextBackoff = (prev) => prev <= 0 ? RECONNECT_MIN_MS : Math.min(RECONNECT_MAX_MS, prev * 2);
+    withJitter = (ms, rnd = Math.random) => Math.round(ms * (0.8 + rnd() * 0.4));
+    reconnectDelay = 0;
     pullSehat = true;
   }
 });
@@ -22575,14 +22740,14 @@ async function loadDeviceIndex() {
   const rows = await prisma.deviceToken.findMany({ select: { id: true, name: true, revokedAt: true } });
   return new Map(rows.map((d) => [d.id, { name: d.name, revoked: d.revokedAt !== null }]));
 }
-function handledByView(raw, devices) {
+function handledByView(raw, devices2) {
   return handledByOf(raw).map((e) => {
-    const d = devices.get(e.deviceId);
+    const d = devices2.get(e.deviceId);
     return { deviceId: e.deviceId, name: d?.name ?? e.name, revoked: d?.revoked ?? false };
   });
 }
-async function toProjectView(p, sessions, devices) {
-  const deviceIndex = devices ?? await loadDeviceIndex();
+async function toProjectView(p, sessions, devices2) {
+  const deviceIndex = devices2 ?? await loadDeviceIndex();
   const specs = await prisma.spec.findMany({ where: { projectId: p.id } });
   const { coverage } = await scanRepoDocs(await resolveRepoDir(p.id));
   const binding = await getBinding(p.id);
@@ -22753,8 +22918,8 @@ async function projects_default(app2) {
     const { q, handledBy, page, limit } = req.query;
     const ps = await prisma.project.findMany({ orderBy: { createdAt: "desc" } });
     const sessions = listSessions();
-    const devices = await loadDeviceIndex();
-    const views = await Promise.all(ps.map((p) => toProjectView(p, sessions, devices)));
+    const devices2 = await loadDeviceIndex();
+    const views = await Promise.all(ps.map((p) => toProjectView(p, sessions, devices2)));
     const needle = (q ?? "").trim().toLowerCase();
     const filtered = needle ? views.filter((v) => `${v.name} ${v.desc} ${v.stack}`.toLowerCase().includes(needle)) : views;
     const device = (handledBy ?? "").trim();
@@ -36175,6 +36340,82 @@ async function update(app2) {
 // src/services/events.ts
 init_pty();
 init_notifications();
+
+// src/services/presence/view.ts
+init_src();
+init_db();
+init_snapshot();
+import { hostname } from "node:os";
+
+// src/services/presence/registry.ts
+init_src();
+var devices = /* @__PURE__ */ new Map();
+function recordPresence(deviceId, sessions, now = Date.now()) {
+  const prev = devices.get(deviceId)?.sessions;
+  const next = /* @__PURE__ */ new Map();
+  for (const session of sessions) {
+    const before2 = prev?.get(session.sessionId);
+    next.set(session.sessionId, {
+      session,
+      statusAt: before2 && before2.session.status === session.status ? before2.statusAt : now
+    });
+  }
+  devices.set(deviceId, { sessions: next, lastFrameAt: now });
+}
+function dropPresence(deviceId) {
+  devices.delete(deviceId);
+}
+function presenceEntries(now = Date.now()) {
+  const out4 = [];
+  for (const [deviceId, d] of devices) {
+    if (now - d.lastFrameAt >= PRESENCE_OFFLINE_MS) {
+      devices.delete(deviceId);
+      continue;
+    }
+    out4.push({
+      deviceId,
+      sessions: [...d.sessions.values()].map((t) => ({
+        ...t.session,
+        statusAt: new Date(t.statusAt).toISOString()
+      }))
+    });
+  }
+  return out4;
+}
+
+// src/services/presence/view.ts
+async function presenceView(o = {}) {
+  const now = o.now ?? Date.now();
+  const local = o.local ?? buildLocalPresence;
+  recordPresence(LOCAL_DEVICE_ID, await local().catch(() => []), now);
+  const live = new Map(presenceEntries(now).map((e) => [e.deviceId, e.sessions]));
+  const rows = await prisma.deviceToken.findMany({
+    where: { revokedAt: null },
+    orderBy: { createdAt: "asc" }
+  });
+  const devices2 = [{
+    deviceId: LOCAL_DEVICE_ID,
+    name: hostname(),
+    local: true,
+    online: true,
+    lastSeenAt: new Date(now).toISOString(),
+    sessions: live.get(LOCAL_DEVICE_ID) ?? []
+  }];
+  for (const r of rows) {
+    const sessions = live.get(r.id);
+    devices2.push({
+      deviceId: r.id,
+      name: r.name,
+      local: false,
+      online: !!sessions,
+      lastSeenAt: r.lastSeenAt?.toISOString() ?? null,
+      sessions: sessions ?? []
+    });
+  }
+  return { enabled: rows.length > 0, devices: devices2 };
+}
+
+// src/services/events.ts
 init_db();
 init_config2();
 init_src();
@@ -36964,6 +37205,7 @@ function parseParams(topic, params) {
 
 // src/services/events.ts
 var clients = /* @__PURE__ */ new Set();
+var cookieClients = /* @__PURE__ */ new WeakSet();
 var tickMs = () => effectiveInt("HANOMAN_EVENTS_TICK_MS") ?? 1e3;
 var GROUPS = [
   // SPEC-409 · ADR-0091 · AC-3 · `deciding` menandai sesi yang sedang DISUSUN keputusannya oleh
@@ -36997,11 +37239,19 @@ var GROUPS = [
   { everyTicks: 30, last: "", build: async () => ({ t: "codexLimits", limits: await getCodexLimits() }) },
   // SPEC-214 · deteksi update jarang berubah; recompute tiap 300 dtk, dedup signature → siar hanya
   // saat status berubah. getUpdateStatus cache 15s + fetch ter-gate (server.ts) → attach tak menahan.
-  { everyTicks: 300, last: "", build: async () => ({ t: "update", update: await getUpdateStatus() }) }
+  { everyTicks: 300, last: "", build: async () => ({ t: "update", update: await getUpdateStatus() }) },
+  // SPEC-919 · ADR-0147 · sesi hidup lintas device (grup GLOBAL ke-10 — `leadAsks` SPEC-909 ikut
+  // dihitung). 3 dtk: presence berdenyut 30 dtk, jadi kadens lebih rapat hanya menambah build tanpa
+  // menambah informasi. `presenceView` menyegarkan sesi mesin ini sendiri di dalamnya — satu
+  // `tmux list-panes` asinkron, tak menahan event loop.
+  { everyTicks: 3, cookieOnly: true, last: "", build: async () => ({ t: "presence", ...await presenceView() }) }
 ];
-function broadcast2(msg) {
+function broadcast2(msg, cookieOnly = false) {
   const s2 = JSON.stringify(msg);
-  for (const c of clients) sendTo(c, s2);
+  for (const c of clients) {
+    if (cookieOnly && !cookieClients.has(c)) continue;
+    sendTo(c, s2);
+  }
 }
 var entries2 = /* @__PURE__ */ new Map();
 function sendTo(c, s2) {
@@ -37107,7 +37357,7 @@ async function __tick() {
       const sig = JSON.stringify(msg);
       if (sig === g.last) continue;
       g.last = sig;
-      broadcast2(msg);
+      broadcast2(msg, g.cookieOnly);
     }
     for (const e of entries2.values()) {
       e.tick++;
@@ -37135,6 +37385,7 @@ function stopLoop() {
 }
 async function attach2(c, o = {}) {
   clients.add(c);
+  if (o.maySubscribe !== false) cookieClients.add(c);
   startLoop();
   const topics = o.maySubscribe === false ? [] : TOPIC_NAMES;
   try {
@@ -37143,6 +37394,7 @@ async function attach2(c, o = {}) {
     return;
   }
   for (const g of GROUPS) {
+    if (g.cookieOnly && !cookieClients.has(c)) continue;
     let msg;
     try {
       msg = await g.build();
@@ -37158,6 +37410,7 @@ async function attach2(c, o = {}) {
 }
 function detach2(c) {
   clients.delete(c);
+  cookieClients.delete(c);
   dropClientSubs(c);
   if (clients.size === 0) stopLoop();
 }
@@ -37284,6 +37537,7 @@ async function bindings_default(app2) {
 
 // src/routes/sync.ts
 init_zod();
+init_src();
 init_db();
 import { gzipSync } from "node:zlib";
 
@@ -37433,6 +37687,16 @@ async function sync_default(app2) {
     }
     const client = { send: (m) => socket2.send(m), close: () => socket2.close() };
     attachSync(client);
+    const guard = new WsMessageGuard({ perWindow: PRESENCE_MAX_FRAMES_PER_MIN });
+    socket2.on("message", (raw) => {
+      try {
+        if (!guard.accept(raw).ok) return;
+        const parsed = zPresenceFrame.safeParse(JSON.parse(raw.toString("utf8")));
+        if (!parsed.success) return;
+        recordPresence(principal.id, parsed.data.sessions);
+      } catch {
+      }
+    });
     const revalidate = setInterval(() => {
       void revalidateWsPrincipal(req, principal).then((ok2) => {
         if (!ok2) socket2.close(1008, "token revoked");
@@ -37443,10 +37707,16 @@ async function sync_default(app2) {
       clearInterval(revalidate);
       release();
       detachSync(client);
+      dropPresence(principal.id);
     });
   });
 }
 
+// src/routes/presence.ts
+async function presence_default(app2) {
+  app2.get("/presence", async () => presenceView());
+}
+
 // src/routes/session-results.ts
 init_db();
 var view4 = (r) => ({
@@ -41540,7 +41810,7 @@ function capabilityForRoute(method, path) {
   const rw = (d) => `${d}:${read2 ? "read" : "write"}`;
   const seg = path.replace(/^\/api\/?/, "").replace(/\/+$/, "").split("/").filter(Boolean);
   const top = seg[0] ?? "";
-  if (top === "auth" || top === "agent-tokens" || top === "device-tokens" || top === "sync" || top === "portal" || top === "client-accounts" || top === "session-events") return "COOKIE_ONLY";
+  if (top === "auth" || top === "agent-tokens" || top === "device-tokens" || top === "sync" || top === "presence" || top === "portal" || top === "client-accounts" || top === "session-events") return "COOKIE_ONLY";
   if (top === "limits" || top === "update" || top === "events" || top === "fs" || top === "health")
     return read2 ? "GLOBAL_READ" : "COOKIE_ONLY";
   if (top === "scheduler") {
@@ -41812,6 +42082,7 @@ function buildApp({ requireAuth = true, agentDocFile, env = process.env } = {})
     await api.register(agent_tokens_default);
     await api.register(bindings_default);
     await api.register(sync_default);
+    await api.register(presence_default);
     await api.register(session_results_default);
     await api.register(session_history_default);
     await api.register(session_events_default);

package/docs/agent-integration.md

@@ -154,6 +154,11 @@ token selalu **403**, apa pun capability-nya, dan tak ada capability yang bisa m
   bisa memalsukan "sesi X bertanya Y" bisa menggerakkan lead atas nama sesi mana pun — itu peniruan
   identitas, bukan capability. Agent token di sini menerima **401** (token sesi tak cocok), bukan
   403: gate cookie mem-bypass path-nya dan route menegakkan tokennya sendiri
+- `/api/presence` — peta pekerjaan yang sedang berjalan di **seluruh mesin** operator: sesi apa
+  hidup di device mana (SPEC-919/ADR-0147). Tak ada capability yang bisa berarti sesuatu untuk
+  agregat lintas-mesin, jadi ia cookie-only apa pun method-nya. Frame siar `presence` di
+  `/api/events/ws` mengikuti gerbang yang sama — grup itu **tidak** dikirim ke principal non-cookie,
+  walau kanalnya sendiri `GLOBAL_READ` bagi agent token
 - `POST /api/update/apply` dan tulis lain di bawah prefix status (`/api/limits`, `/api/update`,
   `/api/events`, `/api/fs`, `/api/health`) — **baca**-nya terbuka untuk token mana pun, **tulis**-nya
   cookie-only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanoman",
-  "version": "0.1.58",
+  "version": "0.1.59",
   "description": "Orchestrator + dashboard workflow docs-driven untuk sesi Claude Code / Codex",
   "type": "module",
   "repository": {