hanoman 0.1.13 → 0.1.14

package/dist/server.js

@@ -5553,6 +5553,9 @@ var init_api = __esm({
       limits: `${API}/limits`,
       // SPEC-339 · versi codex CLI (peringatan lunak model GPT-5.6).
       codexVersion: `${API}/codex/version`,
+      // SPEC-489 · panduan AI agent — markdown MENTAH & PUBLIC (tanpa auth). Satu definisi URL untuk
+      // klien web dan untuk tautan yang disalin operator ke agennya.
+      agentDoc: `${API}/agent-integration.md`,
       docs: (id) => `${API}/projects/${id}/docs`,
       docFile: (id, path) => `${API}/projects/${id}/docs/${path}`,
       // SPEC-210 · dokumen PRD project (freshest-wins: worktree sesi prd hidup > repoDir)
@@ -5879,6 +5882,7 @@ var init_config_registry = __esm({
         kind: "url",
         apply: "live",
         category: "knob",
+        example: "https://hanoman.nafanesia.id",
         help: "Base URL hub tujuan sync (REST + WS). Kosong = instance ini murni HUB."
       },
       {
@@ -5888,6 +5892,7 @@ var init_config_registry = __esm({
         kind: "secret",
         apply: "live",
         category: "credential",
+        example: "43 karakter base64url dari tab Perangkat hub",
         help: "Token yang diterbitkan hub (tab Perangkat di hub). Dikirim sebagai Bearer."
       },
       {
@@ -5897,6 +5902,7 @@ var init_config_registry = __esm({
         kind: "int",
         apply: "live",
         category: "knob",
+        example: "15000",
         default: "15000",
         min: 1e3
       },
@@ -5908,13 +5914,14 @@ var init_config_registry = __esm({
         kind: "secret",
         apply: "new-session",
         category: "credential",
+        example: "sk-ant-oat01-\u2026",
         inheritEnv: true,
         help: "Token `claude setup-token`. Diwarisi proses claude yang di-spawn."
       },
-      { key: "ANTHROPIC_API_KEY", group: "claude", label: "Anthropic API key", kind: "secret", apply: "new-session", category: "credential", inheritEnv: true },
-      { key: "HANOMAN_CLAUDE_BIN", group: "claude", label: "Biner claude", kind: "path", apply: "new-session", category: "knob", default: "claude" },
+      { key: "ANTHROPIC_API_KEY", group: "claude", label: "Anthropic API key", kind: "secret", apply: "new-session", category: "credential", example: "sk-ant-api03-\u2026", inheritEnv: true },
+      { key: "HANOMAN_CLAUDE_BIN", group: "claude", label: "Biner claude", kind: "path", apply: "new-session", category: "knob", example: "/opt/homebrew/bin/claude", default: "claude" },
       // codex (SPEC-338 · ADR-0074)
-      { key: "HANOMAN_CODEX_BIN", group: "claude", label: "Biner codex", kind: "path", apply: "new-session", category: "knob", default: "codex" },
+      { key: "HANOMAN_CODEX_BIN", group: "claude", label: "Biner codex", kind: "path", apply: "new-session", category: "knob", example: "/opt/homebrew/bin/codex", default: "codex" },
       {
         key: "CLAUDE_CONFIG_DIR",
         group: "claude",
@@ -5922,11 +5929,12 @@ var init_config_registry = __esm({
         kind: "path",
         apply: "new-session",
         category: "knob",
+        example: "~/.claude",
         help: "Default ~/.claude. Sumber .credentials.json untuk panel usage/limit."
       },
       // vps
-      { key: "HANOMAN_SSH_KEY_DIR", group: "vps", label: "Dir key SSH", kind: "path", apply: "new-session", category: "knob", help: "Default ~/.hanoman." },
-      { key: "HANOMAN_SSH_BIN", group: "vps", label: "Biner ssh", kind: "path", apply: "new-session", category: "knob", default: "ssh" },
+      { key: "HANOMAN_SSH_KEY_DIR", group: "vps", label: "Dir key SSH", kind: "path", apply: "new-session", category: "knob", example: "~/.hanoman", help: "Default ~/.hanoman." },
+      { key: "HANOMAN_SSH_BIN", group: "vps", label: "Biner ssh", kind: "path", apply: "new-session", category: "knob", example: "/usr/bin/ssh", default: "ssh" },
       // github (SPEC-471 · ADR-0095 · tarik issue → backlog). Dua mode auth, satu jalur kode:
       // `gh` memakai keyring mesin; bila GITHUB_TOKEN diisi ia diteruskan sebagai GH_TOKEN ke
       // proses gh DAN dipakai jalur REST (hub VPS yang tak punya keyring).
@@ -5937,6 +5945,7 @@ var init_config_registry = __esm({
         kind: "secret",
         apply: "live",
         category: "credential",
+        example: "ghp_\u2026",
         help: "PAT scope `repo` (atau `public_repo`). Kosong = andalkan `gh auth login` di mesin ini."
       },
       {
@@ -5946,6 +5955,7 @@ var init_config_registry = __esm({
         kind: "path",
         apply: "live",
         category: "knob",
+        example: "/opt/homebrew/bin/gh",
         default: "gh",
         help: "Absen = tarik issue lewat HTTPS langsung ke api.github.com."
       },
@@ -5958,6 +5968,7 @@ var init_config_registry = __esm({
         kind: "secret",
         apply: "live",
         category: "credential",
+        example: "123456789:AAE\u2026",
         pattern: "^\\d{5,}:[A-Za-z0-9_-]{30,}$",
         patternError: "format BotFather: <bot_id>:<secret>",
         help: "Token dari BotFather. Disimpan terenkripsi; tak pernah dikembalikan utuh."
@@ -5969,6 +5980,7 @@ var init_config_registry = __esm({
         kind: "secret",
         apply: "live",
         category: "credential",
+        example: "hnm_agt_\u2026",
         pattern: "^\\S{20,}$",
         patternError: "plaintext AgentToken (hnm_agt_\u2026)",
         help: "Plaintext AgentToken ber-capability Telegram. Dipakai session operator, bukan bot."
@@ -5980,6 +5992,7 @@ var init_config_registry = __esm({
         kind: "string",
         apply: "live",
         category: "credential",
+        example: "123456789, 987654321",
         pattern: "^\\d+(?:[\\s,]+\\d+)*$",
         patternError: "numeric user id, dipisah koma/spasi",
         help: "Siapa yang boleh memerintah bot. Numeric Telegram user id, bukan username."
@@ -5991,12 +6004,13 @@ var init_config_registry = __esm({
         kind: "string",
         apply: "live",
         category: "knob",
+        example: "-1001234567890",
         pattern: "^-?\\d+$",
         patternError: "numeric chat id (channel/supergroup negatif)",
         help: "Tujuan Test Connection. Kosong = pakai satu-satunya id di allowlist."
       },
       // runtime
-      { key: "HANOMAN_EVENTS_TICK_MS", group: "runtime", label: "Interval events (ms)", kind: "int", apply: "live", category: "knob", default: "1000", min: 100 },
+      { key: "HANOMAN_EVENTS_TICK_MS", group: "runtime", label: "Interval events (ms)", kind: "int", apply: "live", category: "knob", example: "1000", default: "1000", min: 100 },
       { key: "HANOMAN_UPDATE_FETCH", group: "runtime", label: "Deteksi update saat boot", kind: "bool", apply: "live", category: "knob", default: "1" },
       // SPEC-398 · ADR-0087 · deteksi update kini membandingkan semver dengan registry npm, bukan
       // menghitung commit di repo git (HANOMAN_REPO_ROOT dicabut bersama jalur git itu).
@@ -6007,6 +6021,7 @@ var init_config_registry = __esm({
         kind: "string",
         apply: "live",
         category: "knob",
+        example: "https://registry.npmjs.org",
         default: "https://registry.npmjs.org",
         help: "Sumber versi terbaru paket `hanoman`."
       },
@@ -6017,15 +6032,16 @@ var init_config_registry = __esm({
         kind: "string",
         apply: "restart",
         category: "knob",
+        example: "hanoman",
         default: "hanoman",
         help: "Mengubah ini TIDAK memindahkan sesi tmux yang sudah hidup \u2014 berlaku setelah restart."
       },
       // gitGraph (SPEC-233 · preferensi tampilan git graph; semua live, dikonsumsi client)
-      { key: "gitGraph.style", group: "gitGraph", label: "Gaya graph", kind: "string", apply: "live", category: "knob", default: "rounded", help: "rounded | angular" },
-      { key: "gitGraph.colours", group: "gitGraph", label: "Warna lane (CSV)", kind: "string", apply: "live", category: "knob", help: "Daftar warna hex dipisah koma; kosong = palet bawaan." },
-      { key: "gitGraph.dateType", group: "gitGraph", label: "Jenis tanggal", kind: "string", apply: "live", category: "knob", default: "author", help: "author | commit" },
-      { key: "gitGraph.commitsInitialLoad", group: "gitGraph", label: "Muat awal", kind: "int", apply: "live", category: "knob", default: "200", min: 1 },
-      { key: "gitGraph.commitsLoadMore", group: "gitGraph", label: "Muat lagi", kind: "int", apply: "live", category: "knob", default: "100", min: 1 },
+      { key: "gitGraph.style", group: "gitGraph", label: "Gaya graph", kind: "string", apply: "live", category: "knob", example: "rounded", default: "rounded", help: "rounded | angular" },
+      { key: "gitGraph.colours", group: "gitGraph", label: "Warna lane (CSV)", kind: "string", apply: "live", category: "knob", example: "#c9a227, #6b8f71, #b4614e", help: "Daftar warna hex dipisah koma; kosong = palet bawaan." },
+      { key: "gitGraph.dateType", group: "gitGraph", label: "Jenis tanggal", kind: "string", apply: "live", category: "knob", example: "author", default: "author", help: "author | commit" },
+      { key: "gitGraph.commitsInitialLoad", group: "gitGraph", label: "Muat awal", kind: "int", apply: "live", category: "knob", example: "200", default: "200", min: 1 },
+      { key: "gitGraph.commitsLoadMore", group: "gitGraph", label: "Muat lagi", kind: "int", apply: "live", category: "knob", example: "100", default: "100", min: 1 },
       { key: "gitGraph.showRemoteBranches", group: "gitGraph", label: "Tampilkan remote", kind: "bool", apply: "live", category: "knob", default: "1" },
       { key: "gitGraph.showTags", group: "gitGraph", label: "Tampilkan tag", kind: "bool", apply: "live", category: "knob", default: "1" },
       { key: "gitGraph.showStashes", group: "gitGraph", label: "Tampilkan stash", kind: "bool", apply: "live", category: "knob", default: "1" },
@@ -6035,7 +6051,7 @@ var init_config_registry = __esm({
       { key: "gitGraph.combineLocalRemote", group: "gitGraph", label: "Gabung label local+remote", kind: "bool", apply: "live", category: "knob", default: "0" },
       { key: "gitGraph.markdown", group: "gitGraph", label: "Render markdown pesan", kind: "bool", apply: "live", category: "knob", default: "1" },
       { key: "gitGraph.emoji", group: "gitGraph", label: "Render emoji shortcode", kind: "bool", apply: "live", category: "knob", default: "1" },
-      { key: "gitGraph.issueLinkPattern", group: "gitGraph", label: "Pola link issue", kind: "string", apply: "live", category: "knob", help: "URL dengan $1 untuk nomor issue, mis. https://github.com/acme/app/issues/$1" },
+      { key: "gitGraph.issueLinkPattern", group: "gitGraph", label: "Pola link issue", kind: "string", apply: "live", category: "knob", example: "https://github.com/acme/app/issues/$1", help: "URL dengan $1 untuk nomor issue, mis. https://github.com/acme/app/issues/$1" },
       // bootstrap (read-only)
       { key: "DATABASE_URL", group: "bootstrap", label: "DATABASE_URL", kind: "secret", apply: "restart", category: "bootstrap" },
       { key: "TEST_DATABASE_URL", group: "bootstrap", label: "TEST_DATABASE_URL", kind: "secret", apply: "restart", category: "bootstrap" },
@@ -7112,7 +7128,7 @@ var init_src = __esm({
 
 // src/env.ts
 import { readFileSync, existsSync } from "node:fs";
-import { dirname, resolve as resolve2 } from "node:path";
+import { dirname, resolve as resolve3 } from "node:path";
 import { fileURLToPath } from "node:url";
 var dir;
 var init_env = __esm({
@@ -7120,7 +7136,7 @@ var init_env = __esm({
     "use strict";
     dir = dirname(fileURLToPath(import.meta.url));
     for (let i = 0; i < 6; i++) {
-      const file = resolve2(dir, ".env");
+      const file = resolve3(dir, ".env");
       if (existsSync(file)) {
         for (const line of readFileSync(file, "utf8").split("\n")) {
           const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
@@ -7574,7 +7590,7 @@ ${lines2.join("\n")}` : "";
 // ../runner/src/git.ts
 import { spawnSync } from "node:child_process";
 import { rmSync, mkdirSync, realpathSync } from "node:fs";
-import { isAbsolute, resolve as resolve3 } from "node:path";
+import { isAbsolute, resolve as resolve4 } from "node:path";
 function git(cwd, args) {
   const r = spawnSync("git", args, { cwd, encoding: "utf8" });
   if (r.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${r.stderr || r.stdout || r.error?.message || "gagal spawn"}`);
@@ -7609,7 +7625,7 @@ var init_git = __esm({
       addWorktree: (repo, path, branchFrom) => {
         tryGit(repo, ["worktree", "remove", "--force", path]);
         tryGit(repo, ["worktree", "prune"]);
-        rmSync(isAbsolute(path) ? path : resolve3(repo, path), { recursive: true, force: true });
+        rmSync(isAbsolute(path) ? path : resolve4(repo, path), { recursive: true, force: true });
         const base2 = resolveCommit(repo, branchFrom);
         git(repo, ["worktree", "add", "--detach", path, base2]);
         return base2;
@@ -7619,8 +7635,8 @@ var init_git = __esm({
       // `fatal: not a working tree` → membuat DELETE /terminal/sessions balas 500. remove+prune+rm
       // semuanya toleran, jadi penutupan sesi selalu 204 dan registrasi worktree tak stale (SPEC-197).
       removeWorktree: (repo, path) => {
-        const target2 = isAbsolute(path) ? resolve3(path) : resolve3(repo, path);
-        if (target2 === resolve3(repo)) {
+        const target2 = isAbsolute(path) ? resolve4(path) : resolve4(repo, path);
+        if (target2 === resolve4(repo)) {
           throw new Error(`removeWorktree menolak menghapus repo itu sendiri: ${target2}`);
         }
         tryGit(repo, ["worktree", "remove", "--force", target2]);
@@ -7936,7 +7952,7 @@ var init_custom_agents = __esm({
 
 // ../runner/src/paths.ts
 import { homedir } from "node:os";
-import { dirname as dirname2, isAbsolute as isAbsolute2, join, resolve as resolve4 } from "node:path";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join, resolve as resolve5 } from "node:path";
 function resolveHome(env = process.env, home2 = homedir()) {
   const v = env.HANOMAN_HOME?.trim();
   return v ? v : join(home2, ".hanoman");
@@ -7961,7 +7977,7 @@ function resolveDbUrl(env, schemaDir2) {
 function absoluteFileUrl(raw, schemaDir2) {
   const p = raw.slice("file:".length);
   if (p.startsWith(":")) return raw;
-  return `file:${isAbsolute2(p) ? p : resolve4(schemaDir2, p)}`;
+  return `file:${isAbsolute2(p) ? p : resolve5(schemaDir2, p)}`;
 }
 function dbUrlNotice(env) {
   if (env.HANOMAN_DATABASE_URL?.trim()) return null;
@@ -8197,7 +8213,7 @@ var init_tap = __esm({
 
 // src/db.ts
 import { mkdirSync as mkdirSync2 } from "node:fs";
-import { dirname as dirname3, resolve as resolve5 } from "node:path";
+import { dirname as dirname3, resolve as resolve6 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { PrismaClient } from "@prisma/client";
 var schemaDir, notice, url, base, prisma;
@@ -8207,7 +8223,7 @@ var init_db = __esm({
     init_env();
     init_src2();
     init_tap();
-    schemaDir = resolve5(dirname3(fileURLToPath2(import.meta.url)), "../prisma");
+    schemaDir = resolve6(dirname3(fileURLToPath2(import.meta.url)), "../prisma");
     notice = dbUrlNotice(process.env);
     if (notice) console.warn(notice);
     url = resolveDbUrl(process.env, schemaDir);
@@ -10024,13 +10040,15 @@ var init_runtime = __esm({
 
 // src/services/telegram/gateway.ts
 import { createHash as createHash3 } from "node:crypto";
-var digestRaw, TelegramGateway;
+var GATEWAY_PROGRESS_KIND, GATEWAY_FAILURE_KIND, digestRaw, TelegramGateway;
 var init_gateway = __esm({
   "src/services/telegram/gateway.ts"() {
     "use strict";
     init_client();
     init_protocol();
     init_runtime();
+    GATEWAY_PROGRESS_KIND = "gateway-progress";
+    GATEWAY_FAILURE_KIND = "gateway-failure";
     digestRaw = (update2) => createHash3("sha256").update(JSON.stringify(update2)).digest("hex");
     TelegramGateway = class {
       constructor(deps) {
@@ -10116,8 +10134,18 @@ var init_gateway = __esm({
             outcome: target2.created ? "session-created" : "session-reused",
             correlationId: `tg:${input.updateId}`
           });
+          if (this.deps.progress) {
+            await this.deps.store.enqueueReply({
+              chatId: input.chatId,
+              updateId: input.updateId,
+              kind: GATEWAY_PROGRESS_KIND,
+              text: target2.created ? "Diterima. Sesi operator Hanoman untuk chat ini sedang dijalankan \u2014 jawabannya menyusul." : "Diterima. Diteruskan ke sesi operator."
+            }).catch(() => {
+            });
+          }
           updateTelegramRuntimeStatus({ lastUpdateAt: (/* @__PURE__ */ new Date()).toISOString(), lastError: null });
         } catch (error) {
+          const reason = sanitizeTelegramOutput(error.message, this.deps.exactSecrets).slice(0, 200);
           await this.deps.store.markUpdateUncertain(input.updateId, "dispatch-failed");
           await this.deps.store.audit({
             chatId: input.chatId,
@@ -10127,7 +10155,14 @@ var init_gateway = __esm({
             outcome: "uncertain",
             correlationId: `tg:${input.updateId}`
           });
-          throw error;
+          await this.deps.store.enqueueReply({
+            chatId: input.chatId,
+            updateId: input.updateId,
+            kind: GATEWAY_FAILURE_KIND,
+            text: `Pesan Anda tertangkap tapi gagal diteruskan ke sesi operator: ${reason || "sebab tak diketahui"}. Kirim ulang setelah masalahnya beres \u2014 hanoman tidak pernah mengulanginya sendiri (at-most-once).`
+          }).catch(() => {
+          });
+          updateTelegramRuntimeStatus({ lastError: reason });
         }
       }
       async flushOutbox() {
@@ -10186,14 +10221,20 @@ var init_gateway = __esm({
               timeout: this.deps.pollTimeout ?? 25,
               signal
             });
-            await this.processUpdates(updates);
-            await this.flushOutbox();
+            if (telegramRuntimeStatus().readiness === "error") {
+              updateTelegramRuntimeStatus({ running: true, readiness: "running", lastError: null });
+            }
+            try {
+              await this.processUpdates(updates);
+            } finally {
+              await this.flushOutbox();
+            }
           } catch (error) {
             if (signal.aborted) return;
             const message = sanitizeTelegramOutput(error.message, this.deps.exactSecrets).slice(0, 500);
             updateTelegramRuntimeStatus({ running: false, readiness: "error", lastError: message });
             if (error instanceof TelegramApiError && error.code === 409) return;
-            await new Promise((resolve14) => setTimeout(resolve14, 1e3));
+            await new Promise((resolve15) => setTimeout(resolve15, 1e3));
           }
         }
       }
@@ -17222,17 +17263,17 @@ var require_stream_wormhole = __commonJS({
   "../node_modules/.pnpm/stream-wormhole@1.1.0/node_modules/stream-wormhole/index.js"(exports, module) {
     "use strict";
     module.exports = (stream, throwError) => {
-      return new Promise((resolve14, reject2) => {
+      return new Promise((resolve15, reject2) => {
         if (typeof stream.resume !== "function") {
-          return resolve14();
+          return resolve15();
         }
         stream.unpipe && stream.unpipe();
         stream.resume();
         if (stream._readableState && stream._readableState.ended) {
-          return resolve14();
+          return resolve15();
         }
         if (!stream.readable || stream.destroyed) {
-          return resolve14();
+          return resolve15();
         }
         function cleanup() {
           stream.removeListener("end", onEnd);
@@ -17241,14 +17282,14 @@ var require_stream_wormhole = __commonJS({
         }
         function onEnd() {
           cleanup();
-          resolve14();
+          resolve15();
         }
         function onError(err) {
           cleanup();
           if (throwError) {
             reject2(err);
           } else {
-            resolve14();
+            resolve15();
           }
         }
         stream.on("end", onEnd);
@@ -17683,16 +17724,16 @@ var require_multipart2 = __commonJS({
           }
         };
         const parts = () => {
-          return new Promise((resolve14, reject2) => {
+          return new Promise((resolve15, reject2) => {
             handle((val) => {
               if (val instanceof Error) {
                 if (val.message === "Unexpected end of multipart data") {
-                  resolve14(null);
+                  resolve15(null);
                 } else {
                   reject2(val);
                 }
               } else {
-                resolve14(val);
+                resolve15(val);
               }
             });
           });
@@ -17975,11 +18016,39 @@ function pickWebDir(distDir, env, exists) {
   return null;
 }
 
+// src/guide-file.ts
+import { resolve as resolve2 } from "node:path";
+var AGENT_DOC_REL = "docs/agent-integration.md";
+function pickGuideFile(distDir, env, exists) {
+  const forced = env.HANOMAN_AGENT_DOC?.trim();
+  if (forced) {
+    if (!exists(forced)) throw new Error(`HANOMAN_AGENT_DOC menunjuk berkas yang tak ada: ${forced}`);
+    return forced;
+  }
+  for (const c of [resolve2(distDir, "..", AGENT_DOC_REL), resolve2(distDir, "../..", AGENT_DOC_REL)]) {
+    if (exists(c)) return c;
+  }
+  return null;
+}
+
 // src/routes/health.ts
 async function health_default(app2) {
   app2.get("/health", async () => ({ ok: true }));
 }
 
+// src/routes/agent-doc.ts
+import { readFile } from "node:fs/promises";
+async function agent_doc_default(app2, opts) {
+  app2.get("/agent-integration.md", async (_req, reply) => {
+    if (!opts.file)
+      return reply.code(404).send({
+        error: `dokumen panduan tak ada di instalasi ini (${AGENT_DOC_REL}) \u2014 pasang ulang paket hanoman atau set HANOMAN_AGENT_DOC`
+      });
+    const text = await readFile(opts.file, "utf8");
+    return reply.type("text/markdown; charset=utf-8").send(text);
+  });
+}
+
 // src/routes/projects.ts
 init_src();
 init_db();
@@ -17994,7 +18063,7 @@ init_src();
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync3, rmSync as rmSync2, mkdirSync as mkdirSync5 } from "node:fs";
-import { resolve as resolve6, dirname as dirname6, sep } from "node:path";
+import { resolve as resolve7, dirname as dirname6, sep } from "node:path";
 var exec = promisify(execFile);
 async function listRepoDocs(repoDir) {
   try {
@@ -18010,7 +18079,7 @@ async function listRepoDocs(repoDir) {
 }
 function docsDirOf(repoDir) {
   try {
-    const raw = readFileSync4(resolve6(repoDir, "hanoman.config.json"), "utf8");
+    const raw = readFileSync4(resolve7(repoDir, "hanoman.config.json"), "utf8");
     return zHanomanConfig.parse(JSON.parse(raw)).docsDir;
   } catch {
     return zHanomanConfig.parse({}).docsDir;
@@ -18018,7 +18087,7 @@ function docsDirOf(repoDir) {
 }
 function resolveIndex(repoDir, docsDir) {
   const rel = `${docsDir}/README.md`;
-  return existsSync3(resolve6(repoDir, rel)) ? rel : "";
+  return existsSync3(resolve7(repoDir, rel)) ? rel : "";
 }
 var catOf = (rel) => rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : ".";
 var nameOf = (rel) => rel.includes("/") ? rel.slice(rel.lastIndexOf("/") + 1) : rel;
@@ -18029,7 +18098,7 @@ async function scanRepoDocs(repoDir) {
   const index = resolveIndex(repoDir, docsDir);
   const read = (rel) => {
     try {
-      return readFileSync4(resolve6(repoDir, rel), "utf8");
+      return readFileSync4(resolve7(repoDir, rel), "utf8");
     } catch {
       return null;
     }
@@ -18052,7 +18121,7 @@ async function scanRepoDocs(repoDir) {
 function docAbsPath(repoDir, rel) {
   if (!rel.endsWith(".md")) throw new Error("hanya file .md yang diizinkan");
   if (rel.split("/").includes(".git")) throw new Error("tidak boleh menyentuh .git");
-  const abs = resolve6(repoDir, rel);
+  const abs = resolve7(repoDir, rel);
   if (abs !== repoDir && !abs.startsWith(repoDir + sep)) throw new Error("path keluar dari repo");
   return abs;
 }
@@ -18552,9 +18621,9 @@ init_db();
 // src/services/spec-review.ts
 import { execFile as execFile4 } from "node:child_process";
 import { promisify as promisify4 } from "node:util";
-import { readFile, mkdtemp, copyFile, rm } from "node:fs/promises";
+import { readFile as readFile2, mkdtemp, copyFile, rm } from "node:fs/promises";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join4, resolve as resolve7 } from "node:path";
+import { join as join4, resolve as resolve8 } from "node:path";
 var exec4 = promisify4(execFile4);
 var GIT3 = { maxBuffer: 1 << 24 };
 var MAX = 256 * 1024;
@@ -18563,7 +18632,7 @@ async function withTempIndex(wt, fn) {
   const idx = (await exec4("git", ["rev-parse", "--git-path", "index"], { cwd: wt, ...GIT3 })).stdout.trim();
   const dir2 = await mkdtemp(join4(tmpdir2(), "hanoman-idx-"));
   const tmp = join4(dir2, "index");
-  await copyFile(resolve7(wt, idx), tmp);
+  await copyFile(resolve8(wt, idx), tmp);
   const env = { ...process.env, GIT_INDEX_FILE: tmp };
   try {
     await exec4("git", ["add", "-A", "-N"], { cwd: wt, env, ...GIT3 });
@@ -18687,7 +18756,7 @@ async function reviewFile(repoDir, specId, baseSha, branchFrom, path) {
   let contentRaw = null;
   if (status !== "D") {
     try {
-      contentRaw = await readFile(join4(wt, path), "utf8");
+      contentRaw = await readFile2(join4(wt, path), "utf8");
     } catch {
       contentRaw = null;
     }
@@ -21300,7 +21369,7 @@ function renderDocPdf(text, name2, meta) {
   });
   const chunks = [];
   doc.on("data", (c) => chunks.push(c));
-  const done = new Promise((resolve14) => doc.on("end", () => resolve14(Buffer.concat(chunks))));
+  const done = new Promise((resolve15) => doc.on("end", () => resolve15(Buffer.concat(chunks))));
   doc.font("Helvetica-Bold").fontSize(8).fillColor(BRASS).text(toWinAnsi(meta.eyebrow.toUpperCase()), { characterSpacing: 0.8 });
   doc.moveDown(0.25);
   doc.font("Helvetica-Bold").fontSize(17).fillColor(STRONG).text(toWinAnsi(name2.split("/").pop() ?? name2));
@@ -22009,16 +22078,16 @@ import { promisify as promisify7 } from "node:util";
 // src/services/git-ide.ts
 import { execFile as execFile6 } from "node:child_process";
 import { promisify as promisify6 } from "node:util";
-import { readFile as readFile2, writeFile, mkdir } from "node:fs/promises";
+import { readFile as readFile3, writeFile, mkdir } from "node:fs/promises";
 import { existsSync as existsSync6 } from "node:fs";
-import { resolve as resolve8, sep as sep2, dirname as dirname8 } from "node:path";
+import { resolve as resolve9, sep as sep2, dirname as dirname8 } from "node:path";
 var exec6 = promisify6(execFile6);
 var GIT5 = { maxBuffer: 1 << 24 };
 var MAX2 = 256 * 1024;
 var splitZ2 = (s2) => s2.split("\0").filter(Boolean);
 function repoAbsPath(repoDir, rel) {
   if (rel.split(/[\\/]/).includes(".git")) throw new Error("tidak boleh menyentuh .git");
-  const abs = resolve8(repoDir, rel);
+  const abs = resolve9(repoDir, rel);
   if (abs !== repoDir && !abs.startsWith(repoDir + sep2)) throw new Error("path keluar dari repo");
   return abs;
 }
@@ -22036,7 +22105,7 @@ async function readRepoFile(repoDir, rel, ref = "") {
   repoAbsPath(repoDir, rel);
   let raw;
   try {
-    raw = ref ? (await exec6("git", ["show", `${ref}:${rel}`], { cwd: repoDir, ...GIT5 })).stdout : await readFile2(repoAbsPath(repoDir, rel), "utf8");
+    raw = ref ? (await exec6("git", ["show", `${ref}:${rel}`], { cwd: repoDir, ...GIT5 })).stdout : await readFile3(repoAbsPath(repoDir, rel), "utf8");
   } catch {
     return null;
   }
@@ -22437,7 +22506,7 @@ async function workingFileDiff(repoDir, path, staged) {
   let contentRaw = null;
   if (cf.status !== "D") {
     try {
-      contentRaw = staged ? (await exec6("git", ["show", `:${path}`], { cwd: repoDir, ...GIT5 })).stdout : await readFile2(repoAbsPath(repoDir, path), "utf8");
+      contentRaw = staged ? (await exec6("git", ["show", `:${path}`], { cwd: repoDir, ...GIT5 })).stdout : await readFile3(repoAbsPath(repoDir, path), "utf8");
     } catch {
       contentRaw = null;
     }
@@ -22903,11 +22972,11 @@ async function finishGraphOp(reply, id, repoDir, r, verb) {
 // src/routes/fs.ts
 import { readdir } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
-import { resolve as resolve9, dirname as dirname9, join as join5 } from "node:path";
+import { resolve as resolve10, dirname as dirname9, join as join5 } from "node:path";
 async function fs_default(app2) {
   app2.get("/fs/browse", async (req, reply) => {
     const q = req.query.path;
-    const dir2 = q && q.trim() ? resolve9(q.trim()) : homedir3();
+    const dir2 = q && q.trim() ? resolve10(q.trim()) : homedir3();
     try {
       const ents = await readdir(dir2, { withFileTypes: true });
       const entries = ents.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => ({ name: e.name, path: join5(dir2, e.name) })).sort((a, b) => a.name.localeCompare(b.name));
@@ -23043,11 +23112,11 @@ async function startSpecSession(spec, opts) {
 }
 
 // src/services/session-worktree.ts
-import { resolve as resolve10, sep as sep3 } from "node:path";
+import { resolve as resolve11, sep as sep3 } from "node:path";
 function ownsWorktree(repoDir, cwd) {
-  const base2 = resolve10(repoDir);
-  const dir2 = resolve10(cwd);
-  const container = resolve10(base2, ".worktrees");
+  const base2 = resolve11(repoDir);
+  const dir2 = resolve11(cwd);
+  const container = resolve11(base2, ".worktrees");
   return dir2 !== base2 && dir2 !== container && dir2.startsWith(container + sep3);
 }
 
@@ -23548,14 +23617,14 @@ function sshExec(t, remoteCmd, opts = {}) {
     SSH_ASKPASS_REQUIRE: "force",
     HANOMAN_SSH_PASSWORD: opts.password
   } : process.env;
-  return new Promise((resolve14) => {
+  return new Promise((resolve15) => {
     const p = spawn3(sshBin(), args, { stdio: ["pipe", "pipe", "pipe"], env });
     let out3 = "";
     const timer7 = setTimeout(() => p.kill("SIGKILL"), opts.timeoutMs ?? 6e4);
     const done = (r) => {
       clearTimeout(timer7);
       if (askpass) rmSync4(dirname10(askpass), { recursive: true, force: true });
-      resolve14(r);
+      resolve15(r);
     };
     p.stdout.on("data", (d) => {
       out3 += d;
@@ -24332,7 +24401,7 @@ init_src();
 init_src();
 init_config2();
 import { readFileSync as readFileSync11 } from "node:fs";
-import { resolve as resolve11, dirname as dirname12 } from "node:path";
+import { resolve as resolve12, dirname as dirname12 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var UPDATE_COMMAND = "npm i -g hanoman@latest";
 function composeUpdate(x) {
@@ -24358,7 +24427,7 @@ var lastLatest = null;
 var lastStatus = "unavailable";
 function runningVersion() {
   const here = dirname12(fileURLToPath3(import.meta.url));
-  for (const p of [resolve11(here, "build-info.json"), resolve11(here, "../package.json")]) {
+  for (const p of [resolve12(here, "build-info.json"), resolve12(here, "../package.json")]) {
     try {
       const v = JSON.parse(readFileSync11(p, "utf8")).version;
       if (typeof v === "string" && v) return v;
@@ -24707,8 +24776,8 @@ init_conflicts();
 // src/services/uploads.ts
 init_config2();
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { mkdir as mkdir2, writeFile as writeFile2, readFile as readFile3, unlink } from "node:fs/promises";
-import { join as join12, resolve as resolve12 } from "node:path";
+import { mkdir as mkdir2, writeFile as writeFile2, readFile as readFile4, unlink } from "node:fs/promises";
+import { join as join12, resolve as resolve13 } from "node:path";
 var EXT = {
   "image/png": ".png",
   "image/jpeg": ".jpg",
@@ -24718,7 +24787,7 @@ function extFor(mimeType) {
   return EXT[mimeType] ?? ".bin";
 }
 function uploadDir() {
-  return resolve12(effectiveStr("HANOMAN_UPLOAD_DIR") ?? join12(process.cwd(), "data", "uploads"));
+  return resolve13(effectiveStr("HANOMAN_UPLOAD_DIR") ?? join12(process.cwd(), "data", "uploads"));
 }
 async function saveUpload(buf, mimeType) {
   const dir2 = uploadDir();
@@ -24729,13 +24798,13 @@ async function saveUpload(buf, mimeType) {
 }
 async function readUpload(storageKey) {
   const safe = storageKey.replace(/[/\\]/g, "");
-  return readFile3(join12(uploadDir(), safe));
+  return readFile4(join12(uploadDir(), safe));
 }
 async function readUploadOrFetch(storageKey) {
   const safe = storageKey.replace(/[/\\]/g, "");
   const target2 = join12(uploadDir(), safe);
   try {
-    return await readFile3(target2);
+    return await readFile4(target2);
   } catch {
     const base2 = effectiveStr("SYNC_SERVER_URL");
     const token = effectiveStr("SYNC_DEVICE_TOKEN");
@@ -24882,11 +24951,11 @@ import { randomUUID as randomUUID5 } from "node:crypto";
 // src/services/transcript-store.ts
 init_config2();
 import { randomUUID as randomUUID4 } from "node:crypto";
-import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile4, unlink as unlink2 } from "node:fs/promises";
-import { join as join13, resolve as resolve13, basename as basename2 } from "node:path";
+import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile5, unlink as unlink2 } from "node:fs/promises";
+import { join as join13, resolve as resolve14, basename as basename2 } from "node:path";
 var MAX_TRANSCRIPT_BYTES = 1024 * 1024;
 function transcriptDir() {
-  return resolve13(effectiveStr("HANOMAN_TRANSCRIPT_DIR") ?? join13(process.cwd(), "data", "transcripts"));
+  return resolve14(effectiveStr("HANOMAN_TRANSCRIPT_DIR") ?? join13(process.cwd(), "data", "transcripts"));
 }
 function clamp(text) {
   const buf = Buffer.from(text, "utf8");
@@ -24910,7 +24979,7 @@ async function saveTranscript(text) {
 async function readTranscript(key) {
   if (!key) return null;
   try {
-    return await readFile4(join13(transcriptDir(), basename2(key)), "utf8");
+    return await readFile5(join13(transcriptDir(), basename2(key)), "utf8");
   } catch {
     return null;
   }
@@ -25938,7 +26007,7 @@ function leadFailureReason(agent, timeoutMs, err, stdout, stderr) {
 function think(prompt, o) {
   const bin = binFor(o.agent);
   const args = leadArgv({ agent: o.agent, model: o.model, effort: o.effort, prompt });
-  return new Promise((resolve14, reject2) => {
+  return new Promise((resolve15, reject2) => {
     const child = execFile9(bin, args, {
       cwd: o.cwd,
       timeout: o.timeoutMs,
@@ -25951,7 +26020,7 @@ function think(prompt, o) {
         reject2(new Error(leadFailureReason(o.agent, o.timeoutMs, err, stdout, stderr)));
         return;
       }
-      resolve14(stdout);
+      resolve15(stdout);
     });
     child.stdin?.end();
   });
@@ -25988,9 +26057,9 @@ function acquire(cap, waitMs) {
     return Promise.resolve();
   }
   const startedAt = Date.now();
-  return new Promise((resolve14, reject2) => {
+  return new Promise((resolve15, reject2) => {
     const w = {
-      grant: resolve14,
+      grant: resolve15,
       deny: reject2,
       timer: setTimeout(() => {
         const i = queue.indexOf(w);
@@ -26507,6 +26576,7 @@ var CODEX_FINISHED = [
   /\btokens used\b/i,
   /\bTo continue this session\b/i
 ];
+var AGENT_TURN_LINE = /(?:\bfor\s+\d+\s*[hms]\b|\(\s*\d+\s*[hms][^)]*·)/i;
 var ASK_SIGNALS = [
   /\?\s*$/m,
   /^\s*\[?\d+[).\]]\s+\S/m,
@@ -26515,9 +26585,12 @@ var ASK_SIGNALS = [
 function readPaneQuestion(text, agent) {
   const lines2 = tail2(text, 40);
   const body = lines2.join("\n").trim();
-  const choices = readChoiceDialog(text)?.options ?? [];
+  const dialog = readChoiceDialog(text);
+  const choices = dialog?.options ?? [];
   if (!body) return { asking: false, question: "", reason: "layar kosong", choices };
   const question = tail2(text, 25).join("\n").trim();
+  if (!dialog && AGENT_TURN_LINE.test(body))
+    return { asking: false, question, reason: "giliran agen, bukan pertanyaan (baris giliran claude di layar)", choices };
   if (agent === "codex") {
     const finished = CODEX_FINISHED.find((re) => re.test(body));
     if (finished) return { asking: false, question, reason: "sesi codex selesai wajar (ADR-0074)", choices };
@@ -26532,14 +26605,20 @@ var answers = /* @__PURE__ */ new Map();
 var capped = /* @__PURE__ */ new Set();
 var failures = /* @__PURE__ */ new Map();
 var failCapped = /* @__PURE__ */ new Set();
+var failedAt = /* @__PURE__ */ new Map();
+var FAIL_COOLDOWN_MS = 15 * 6e4;
+var chainFlows = /* @__PURE__ */ new Map();
 var MAX_CHAIN_STEPS = 6;
 var CHAIN_POLL_MS = 300;
 var CHAIN_POLL_TRIES = 20;
+var CHAIN_END_TRIES = 5;
 function resetSession(sessionId2) {
   answers.delete(sessionId2);
   capped.delete(sessionId2);
   failures.delete(sessionId2);
   failCapped.delete(sessionId2);
+  failedAt.delete(sessionId2);
+  chainFlows.delete(sessionId2);
 }
 var prodDetectDeps = {
   live: () => {
@@ -26577,6 +26656,12 @@ var prodDetectDeps = {
   },
   submit: (id) => submitPaneDialog(id),
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+  // Alur yang gagal ditutup bukan alasan menggagalkan rantai yang sudah berhasil: penyapu TTL
+  // (ADR-0102) tetap menutupnya.
+  closeChain: async (flowId) => {
+    await closeFlow(flowId, "submit").catch(() => null);
+  },
+  now: Date.now,
   decide,
   decideDeps: prodDecideDeps,
   delivery: takeDelivery,
@@ -26602,7 +26687,7 @@ async function scanAndAnswer(deps = prodDetectDeps) {
       skip("lead dijeda untuk project ini");
       continue;
     }
-    if (!deps.filled(s2.decisionFile)) continue;
+    if (!deps.filled(s2.decisionFile) && !(!deps.exited(s2.id) && readDialogScreen(deps.pane(s2.id)))) continue;
     if (deps.exited(s2.id)) {
       skip("pane mati");
       continue;
@@ -26635,6 +26720,12 @@ async function scanAndAnswer(deps = prodDetectDeps) {
       skip("batas jawaban otomatis tercapai");
       continue;
     }
+    const lastFail = failedAt.get(s2.id);
+    if (lastFail !== void 0 && deps.now() - lastFail > FAIL_COOLDOWN_MS) {
+      failures.delete(s2.id);
+      failCapped.delete(s2.id);
+      failedAt.delete(s2.id);
+    }
     if ((failures.get(s2.id) ?? 0) >= cfg.maxAutoAnswers) {
       if (!failCapped.has(s2.id)) {
         failCapped.add(s2.id);
@@ -26680,15 +26771,27 @@ async function scanAndAnswer(deps = prodDetectDeps) {
       out3.answered.push(s2.id);
       return;
     }
-    if (chain.failed) failures.set(s2.id, (failures.get(s2.id) ?? 0) + 1);
+    if (chain.failed) {
+      failures.set(s2.id, (failures.get(s2.id) ?? 0) + 1);
+      failedAt.set(s2.id, deps.now());
+    }
     out3.skipped.push({ id: s2.id, reason: chain.reason });
   });
   return out3;
 }
 async function runChain(s2, agent, deps) {
   let acted = false;
+  const done = async (r) => {
+    const flowId = chainFlows.get(s2.id);
+    if (flowId) {
+      chainFlows.delete(s2.id);
+      await deps.closeChain(flowId).catch(() => {
+      });
+    }
+    return r;
+  };
   for (let step = 0; step < MAX_CHAIN_STEPS; step++) {
-    const text = deps.pane(s2.id);
+    const text = step === 0 ? deps.pane(s2.id) : await settledPane(s2.id, deps);
     const screen = readDialogScreen(text);
     if (screen?.kind === "review") {
       if (!await deps.submit(s2.id))
@@ -26696,10 +26799,10 @@ async function runChain(s2, agent, deps) {
       acted = true;
       continue;
     }
-    if (step > 0 && !screen) return { acted, done: true, failed: false, reason: "" };
+    if (step > 0 && !screen) return done({ acted, done: true, failed: false, reason: "" });
     const read = readPaneQuestion(text, agent);
     if (!read.asking) {
-      return step === 0 ? { acted, done: false, failed: false, reason: read.reason } : { acted, done: true, failed: false, reason: "" };
+      return step === 0 ? { acted, done: false, failed: false, reason: read.reason } : done({ acted, done: true, failed: false, reason: "" });
     }
     const notes = [`Sesi ini menunggu di terminal; teks di bawah adalah layar terakhirnya. Jawablah sebagai masukan yang bisa langsung diketik ke terminal itu (isi \`reply\`).`];
     if (read.choices.length) {
@@ -26711,22 +26814,32 @@ async function runChain(s2, agent, deps) {
         `Dialog ini BERANTAI: ${screen.tabs.length} pertanyaan dalam satu tanya (${screen.tabs.map((t) => `${t.answered ? "sudah" : "belum"}: ${t.header}`).join(", ")}). Yang sedang tampil pertanyaan ke-${at + 1}; jawab HANYA pertanyaan itu \u2014 sisanya akan ditanyakan sesudah ini.`
       );
     }
+    const ask = {
+      projectId: s2.projectId,
+      specId: s2.specId,
+      sessionId: s2.id,
+      gate: "detected",
+      kind: "answer",
+      question: read.question,
+      options: read.choices.length ? read.choices : void 0,
+      notes,
+      chain: true
+    };
     let row;
     try {
-      row = await deps.decide({
-        projectId: s2.projectId,
-        specId: s2.specId,
-        sessionId: s2.id,
-        gate: "detected",
-        kind: "answer",
-        question: read.question,
-        options: read.choices.length ? read.choices : void 0,
-        notes
-      }, deps.decideDeps);
+      row = await deps.decide({ ...ask, flowId: chainFlows.get(s2.id) ?? null }, deps.decideDeps);
     } catch (e) {
       if (e instanceof LeadBusyError) return { acted, done: false, failed: false, reason: `lead penuh \u2014 ${e.message}` };
-      throw e;
+      if (!(e instanceof LeadFlowClosedError)) throw e;
+      chainFlows.delete(s2.id);
+      try {
+        row = await deps.decide({ ...ask, flowId: null }, deps.decideDeps);
+      } catch (e2) {
+        if (e2 instanceof LeadBusyError) return { acted, done: false, failed: false, reason: `lead penuh \u2014 ${e2.message}` };
+        throw e2;
+      }
     }
+    if (row?.flowId) chainFlows.set(s2.id, row.flowId);
     if (!row) return { acted, done: false, failed: false, reason: "lead tak menghasilkan keputusan yang berlaku" };
     if (row.status !== "berlaku")
       return { acted, done: false, failed: true, reason: "lead tak menghasilkan keputusan yang berlaku" };
@@ -26736,12 +26849,20 @@ async function runChain(s2, agent, deps) {
     if (!await deps.send(s2.id, reply, picked))
       return { acted, done: false, failed: true, reason: "gagal mengetik ke pane" };
     acted = true;
-    if (!screen) return { acted, done: true, failed: false, reason: "" };
+    if (!screen) return done({ acted, done: true, failed: false, reason: "" });
     if (!await waitScreenChange(s2.id, dialogKey(text), deps))
       return { acted, done: false, failed: true, reason: "layar dialog tak berubah sesudah dijawab" };
   }
   return { acted, done: false, failed: true, reason: "batas langkah rantai dialog tercapai" };
 }
+async function settledPane(id, deps) {
+  let text = deps.pane(id);
+  for (let i = 0; i < CHAIN_END_TRIES && !readDialogScreen(text); i++) {
+    await deps.sleep(CHAIN_POLL_MS);
+    text = deps.pane(id);
+  }
+  return text;
+}
 async function waitScreenChange(id, before, deps) {
   for (let i = 0; i < CHAIN_POLL_TRIES; i++) {
     await deps.sleep(CHAIN_POLL_MS);
@@ -26755,6 +26876,8 @@ function sweep(liveIds) {
   for (const id of [...capped]) if (!live.has(id)) capped.delete(id);
   for (const id of [...failures.keys()]) if (!live.has(id)) failures.delete(id);
   for (const id of [...failCapped]) if (!live.has(id)) failCapped.delete(id);
+  for (const id of [...failedAt.keys()]) if (!live.has(id)) failedAt.delete(id);
+  for (const id of [...chainFlows.keys()]) if (!live.has(id)) chainFlows.delete(id);
 }
 
 // src/services/lead/pulse.ts
@@ -27662,7 +27785,7 @@ function issuesFromRest(raw) {
 }
 var GH_FIELDS = "number,title,body,author,labels,url,state,createdAt,updatedAt";
 var API2 = "https://api.github.com";
-var defaultRunGh = (args, env) => new Promise((resolve14, reject2) => {
+var defaultRunGh = (args, env) => new Promise((resolve15, reject2) => {
   execFile10(
     args[0],
     args.slice(1),
@@ -27670,7 +27793,7 @@ var defaultRunGh = (args, env) => new Promise((resolve14, reject2) => {
     (err, stdout, stderr) => {
       const e = err;
       if (e && (e.code === "ENOENT" || e.code === "EACCES")) return reject2(e);
-      resolve14({ code: err ? Number(err.code ?? 1) : 0, stdout, stderr });
+      resolve15({ code: err ? Number(err.code ?? 1) : 0, stdout, stderr });
     }
   );
 });
@@ -27989,8 +28112,42 @@ import { randomBytes as randomBytes5 } from "node:crypto";
 // src/services/telegram/credentials.ts
 init_src();
 init_config2();
+init_agent_token();
+init_settings2();
+init_bootstrap();
 init_client();
 init_protocol();
+init_runtime();
+async function verifyTelegramAgentToken(token, deps = {}) {
+  const agent = await (deps.verify ?? verifyAgentToken)(token);
+  if (!agent) {
+    return {
+      ok: false,
+      missing: [...TELEGRAM_REQUIRED_CAPABILITIES],
+      reason: "AgentToken tidak dikenal atau sudah dicabut \u2014 salin plaintext `hnm_agt_\u2026` dari Akses AI Agent, bukan hash-nya."
+    };
+  }
+  const missing = TELEGRAM_REQUIRED_CAPABILITIES.filter((c) => !agent.capabilities.includes(c));
+  return missing.length ? { ok: false, missing, reason: `AgentToken kurang ${missing.length} capability.` } : { ok: true };
+}
+async function telegramInboundReadiness(deps = {}) {
+  const polling = deps.polling ?? telegramRuntimeStatus().running;
+  const empty = [];
+  const token = deps.agentToken ?? effectiveStr("HANOMAN_TELEGRAM_AGENT_TOKEN")?.trim();
+  if (!token) {
+    return { ok: false, reason: "AgentToken gateway belum diisi.", missingCapabilities: [...TELEGRAM_REQUIRED_CAPABILITIES], polling };
+  }
+  const setting = await (deps.getSetting ?? getSetting)();
+  if (!setting.agentAccessEnabled) {
+    return { ok: false, reason: "Akses agent mati \u2014 nyalakan master switch di Akses AI Agent.", missingCapabilities: empty, polling };
+  }
+  const gate = await verifyTelegramAgentToken(token, deps);
+  if (!gate.ok) return { ok: false, reason: gate.reason, missingCapabilities: gate.missing, polling };
+  if (!polling) {
+    return { ok: false, reason: "Kredensial sudah sah tapi gateway belum polling \u2014 nyalakan \u201CGateway aktif\u201D.", missingCapabilities: empty, polling };
+  }
+  return { ok: true, reason: null, missingCapabilities: empty, polling };
+}
 var KEYS = TELEGRAM_CONFIG_KEYS;
 function telegramCredentialView() {
   return {
@@ -28008,7 +28165,7 @@ function telegramCredentialView() {
     })
   };
 }
-async function saveTelegramCredentials(patch) {
+async function saveTelegramCredentials(patch, deps = {}) {
   const writes = [];
   for (const [key, raw] of Object.entries(patch)) {
     if (!KEYS.includes(key)) return { ok: false, key, error: "key bukan kredensial Telegram" };
@@ -28022,6 +28179,14 @@ async function saveTelegramCredentials(patch) {
     if (!parsed.ok) return { ok: false, key, error: parsed.error };
     writes.push([key, parsed.value]);
   }
+  const agentToken = writes.find(([key]) => key === "HANOMAN_TELEGRAM_AGENT_TOKEN")?.[1];
+  if (agentToken !== void 0) {
+    const gate = await verifyTelegramAgentToken(agentToken, deps);
+    if (!gate.ok) {
+      const detail = gate.missing.length < TELEGRAM_REQUIRED_CAPABILITIES.length ? `${gate.reason} Kurang: ${gate.missing.join(", ")}.` : gate.reason;
+      return { ok: false, key: "HANOMAN_TELEGRAM_AGENT_TOKEN", error: detail };
+    }
+  }
   for (const [key, value] of writes) await setConfig(key, value);
   return { ok: true };
 }
@@ -28036,11 +28201,12 @@ async function clearTelegramCredentials() {
   return { cleared, envFallback: KEYS.filter((k) => sourceOf(k) === "env") };
 }
 async function testTelegramConnection(deps = {}) {
+  const inbound = await telegramInboundReadiness(deps);
   const botToken = deps.botToken ?? effectiveStr("HANOMAN_TELEGRAM_BOT_TOKEN");
-  if (!botToken) return { ok: false, error: "Bot token belum diisi." };
+  if (!botToken) return { ok: false, error: "Bot token belum diisi.", inbound };
   const chatId = deps.chatId ?? resolveTestChatId();
   if (!chatId) {
-    return { ok: false, error: "Isi Chat / Channel ID target \u2014 atau isi allowlist dengan tepat satu user id." };
+    return { ok: false, inbound, error: "Isi Chat / Channel ID target \u2014 atau isi allowlist dengan tepat satu user id." };
   }
   const timeoutMs = deps.timeoutMs ?? 1e4;
   const controller = new AbortController();
@@ -28052,11 +28218,11 @@ async function testTelegramConnection(deps = {}) {
     const me = await client.getMe();
     const stamp2 = (deps.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
     await client.sendMessage({ chatId, text: `hanoman: uji koneksi Telegram berhasil (${stamp2}).` });
-    return { ok: true, botUsername: me.username ?? null, chatId };
+    return { ok: true, botUsername: me.username ?? null, chatId, inbound };
   } catch (error) {
     const raw = error.message || "gagal menghubungi Telegram";
     const message = controller.signal.aborted ? `Timeout ${timeoutMs} ms \u2014 Telegram tidak menjawab.` : raw;
-    return { ok: false, error: sanitizeTelegramOutput(message, [botToken]).slice(0, 500) };
+    return { ok: false, inbound, error: sanitizeTelegramOutput(message, [botToken]).slice(0, 500) };
   } finally {
     clearTimeout(timer7);
   }
@@ -28961,9 +29127,15 @@ var PUBLIC = /* @__PURE__ */ new Set([
   "GET /api/health",
   "GET /api/auth/status",
   "POST /api/auth/login",
-  "POST /api/auth/setup"
+  "POST /api/auth/setup",
+  // SPEC-489 · panduan AI agent. Sengaja tanpa auth: byte-nya sudah publik di GitHub, dan
+  // "cukup diberi link + token" hanya benar bila link-nya terbaca SEBELUM token disetel —
+  // menggerbanginya berarti agen yang capability-nya kurang menerima 403 pada dokumen yang
+  // justru menjelaskan arti 403 itu.
+  "GET /api/agent-integration.md"
 ]);
-function buildApp({ requireAuth = true } = {}) {
+function buildApp({ requireAuth = true, agentDocFile } = {}) {
+  const docFile = agentDocFile !== void 0 ? agentDocFile : pickGuideFile(dirname13(fileURLToPath4(import.meta.url)), process.env, existsSync12);
   const app2 = Fastify({ logger: false, trustProxy: true });
   app2.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
     if (!body) return done(null, void 0);
@@ -29017,6 +29189,7 @@ function buildApp({ requireAuth = true } = {}) {
     api.addHook("onResponse", auditTelegramGatewayResponse);
     await api.register(auth_default);
     await api.register(health_default);
+    await api.register(agent_doc_default, { file: docFile });
     await api.register(projects_default);
     await api.register(specs_default);
     await api.register(notifications_default);