hanoman 0.1.13 → 0.1.15

package/dist/server.js

@@ -4164,16 +4164,34 @@ var init_enums = __esm({
   }
 });
 
+// ../shared/src/agent-engine.ts
+var zAgentEngine;
+var init_agent_engine = __esm({
+  "../shared/src/agent-engine.ts"() {
+    "use strict";
+    init_zod();
+    init_enums();
+    zAgentEngine = external_exports.object({
+      enabled: external_exports.boolean().default(false),
+      agent: zAgent.default("claude"),
+      model: external_exports.string().default("claude-opus-5"),
+      effort: external_exports.string().default("xhigh")
+    });
+  }
+});
+
 // ../shared/src/telegram.ts
 var zTelegramSettings, TELEGRAM_DEFAULTS, TELEGRAM_CONFIG_KEYS, zTelegramReadiness, zTelegramGatewayStatus, zTelegramMemoryRecord, zTelegramChatContext, TELEGRAM_REPLY_KINDS, zTelegramReplyKind, zTelegramConfirmationRequest, zTelegramReplyInput, zTelegramAuditRecord, zTerminalSteerInput;
 var init_telegram = __esm({
   "../shared/src/telegram.ts"() {
     "use strict";
     init_zod();
+    init_agent_engine();
     init_enums();
     zTelegramSettings = external_exports.object({
       enabled: external_exports.boolean().default(false),
-      progress: external_exports.boolean().default(true)
+      progress: external_exports.boolean().default(true),
+      engine: zAgentEngine.default({})
     });
     TELEGRAM_DEFAULTS = zTelegramSettings.parse({});
     TELEGRAM_CONFIG_KEYS = [
@@ -4306,6 +4324,9 @@ var init_auto_merge = __esm({
 function codexModel(id) {
   return CODEX_MODELS.find((m) => m.id === id);
 }
+function codexEfforts(modelId) {
+  return codexModel(modelId)?.efforts ?? E_BASE;
+}
 function coerceCodexEffort(modelId, effort) {
   const m = codexModel(modelId);
   if (!m) return effort;
@@ -4320,13 +4341,14 @@ function cmpVersion(a, b) {
   }
   return 0;
 }
-var zProject, zBriefPayload, zQaPayload, zGoalPayload, zSpecBlocker, zSpec, NOTIFY_SOUNDS, MODELS, E_5_6, E_LUNA, E_BASE, CODEX_MODELS, RETIRED_CODEX_MODELS, zCodex, CODEX_DEFAULTS, zSourceCommon, zScheduler, SCHEDULER_DEFAULTS, zGoal, GOAL_DEFAULTS, zConflict, CONFLICT_DEFAULTS, zLeadEngine, zLead, LEAD_DEFAULTS, zSetting, zNotification, zDocFile, zDeviceTokenView;
+var zProject, zBriefPayload, zQaPayload, zGoalPayload, zSpecBlocker, zSpec, NOTIFY_SOUNDS, MODELS, EFFORTS, E_5_6, E_LUNA, E_BASE, CODEX_MODELS, RETIRED_CODEX_MODELS, zCodex, CODEX_DEFAULTS, zSourceCommon, zScheduler, SCHEDULER_DEFAULTS, zGoal, GOAL_DEFAULTS, zConflict, CONFLICT_DEFAULTS, zLeadEngine, zLead, LEAD_DEFAULTS, zSetting, zNotification, zDocFile, zDeviceTokenView;
 var init_entities = __esm({
   "../shared/src/entities.ts"() {
     "use strict";
     init_zod();
     init_enums();
     init_telegram();
+    init_agent_engine();
     init_auto_merge();
     zProject = external_exports.object({
       id: external_exports.string(),
@@ -4420,6 +4442,7 @@ var init_entities = __esm({
       { id: "claude-haiku-4-5", label: "Haiku 4.5" },
       { id: "claude-fable-5", label: "Fable 5" }
     ];
+    EFFORTS = ["xhigh", "high", "medium", "low", "max", "ultracode"];
     E_5_6 = ["ultra", "max", "xhigh", "high", "medium", "low"];
     E_LUNA = ["max", "xhigh", "high", "medium", "low"];
     E_BASE = ["xhigh", "high", "medium", "low"];
@@ -4468,12 +4491,7 @@ var init_entities = __esm({
       effort: external_exports.string().default("xhigh")
     });
     CONFLICT_DEFAULTS = zConflict.parse({});
-    zLeadEngine = external_exports.object({
-      enabled: external_exports.boolean().default(false),
-      agent: zAgent.default("claude"),
-      model: external_exports.string().default("claude-opus-5"),
-      effort: external_exports.string().default("xhigh")
-    });
+    zLeadEngine = zAgentEngine;
     zLead = external_exports.object({
       enabled: external_exports.boolean().default(false),
       // master switch (AC-30)
@@ -5553,6 +5571,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 +5900,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 +5910,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 +5920,7 @@ var init_config_registry = __esm({
         kind: "int",
         apply: "live",
         category: "knob",
+        example: "15000",
         default: "15000",
         min: 1e3
       },
@@ -5908,13 +5932,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 +5947,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 +5963,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 +5973,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 +5986,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 +5998,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 +6010,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 +6022,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 +6039,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 +6050,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 +6069,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" },
@@ -7089,6 +7123,7 @@ var init_src = __esm({
   "../shared/src/index.ts"() {
     "use strict";
     init_enums();
+    init_agent_engine();
     init_entities();
     init_agent();
     init_custom_agent();
@@ -7112,7 +7147,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 +7155,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 +7609,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 +7644,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 +7654,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 +7971,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 +7996,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;
@@ -8011,6 +8046,7 @@ function buildTelegramOperatorPrompt(input) {
     "",
     "- Bahasa natural adalah antarmuka utama; command hanya shortcut yang tetap kamu tangani di sesi ini.",
     `- Command minimum: ${COMMANDS.join(", ")}.`,
+    `- Command runtime sesi ini ditangani server, bukan kamu: ${SERVER_COMMANDS.join(", ")}. Sebutkan di /help apa adanya; jangan pernah mencoba menjawabnya sendiri.`,
     `- Panggil API dengan base $HANOMAN_API_BASE, bearer $HANOMAN_TELEGRAM_AGENT_TOKEN, dan header x-hanoman-telegram-update: ${update2.updateId}.`,
     "- Terbitkan jawaban user-facing secara eksplisit melalui POST $HANOMAN_API_BASE/api/telegram/replies.",
     "- Kind reply hanya progress|final|decision|failure|confirmation. Jangan mengandalkan layar PTY sebagai balasan.",
@@ -8024,7 +8060,7 @@ function buildTelegramOperatorPrompt(input) {
     update2.text
   ].join("\n");
 }
-var COMMANDS;
+var COMMANDS, SERVER_COMMANDS;
 var init_telegram_operator = __esm({
   "../runner/src/telegram-operator.ts"() {
     "use strict";
@@ -8042,6 +8078,12 @@ var init_telegram_operator = __esm({
       "/personality [nama|reset]",
       "/skills"
     ];
+    SERVER_COMMANDS = [
+      "/engine",
+      "/runtime claude|codex",
+      "/model <id>",
+      "/effort <nilai>"
+    ];
   }
 });
 
@@ -8197,7 +8239,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 +8249,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);
@@ -9781,10 +9823,11 @@ var init_client = __esm({
   "src/services/telegram/client.ts"() {
     "use strict";
     TelegramApiError = class extends Error {
-      constructor(method, code, message) {
+      constructor(method, code, message, retryAfter) {
         super(`Telegram ${method} gagal${code ? ` (${code})` : ""}: ${message}`);
         this.method = method;
         this.code = code;
+        this.retryAfter = retryAfter;
         this.name = "TelegramApiError";
       }
     };
@@ -9809,7 +9852,10 @@ var init_client = __esm({
         } catch (error) {
           throw new TelegramApiError(method, void 0, this.safe(error.message || "network error"));
         }
-        if (!response.ok) throw new TelegramApiError(method, response.status, `HTTP ${response.status}`);
+        if (!response.ok) {
+          const failed = await response.json().catch(() => null);
+          throw new TelegramApiError(method, response.status, `HTTP ${response.status}`, failed?.parameters?.retry_after);
+        }
         let envelope;
         try {
           envelope = await response.json();
@@ -9817,7 +9863,12 @@ var init_client = __esm({
           throw new TelegramApiError(method, response.status, "respons bukan JSON");
         }
         if (!envelope.ok || envelope.result === void 0) {
-          throw new TelegramApiError(method, envelope.error_code, this.safe(envelope.description ?? "respons tidak valid"));
+          throw new TelegramApiError(
+            method,
+            envelope.error_code,
+            this.safe(envelope.description ?? "respons tidak valid"),
+            envelope.parameters?.retry_after
+          );
         }
         return envelope.result;
       }
@@ -9842,6 +9893,14 @@ var init_client = __esm({
           ...input.replyMarkup ? { reply_markup: input.replyMarkup } : {}
         });
       }
+      /**
+       * SPEC-493 · indikator "typing…". Argumennya posisional (beda dari tetangganya) sesuai kontrak
+       * yang diminta. Telegram TAK punya API stop-typing: statusnya padam sendiri ~5 detik sesudah
+       * panggilan terakhir, dan pesan masuk apa pun langsung menghapusnya.
+       */
+      sendChatAction(chatId, action = "typing") {
+        return this.call("sendChatAction", { chat_id: chatId, action });
+      }
       editMessageText(input) {
         return this.call("editMessageText", {
           chat_id: input.chatId,
@@ -9859,6 +9918,40 @@ var init_client = __esm({
   }
 });
 
+// src/services/telegram/config.ts
+async function setTelegramEngine(next) {
+  const cur = await getSetting();
+  const data = { ...cur, telegram: { ...cur.telegram, engine: next } };
+  await prisma.setting.upsert({ where: { id: 1 }, update: { data }, create: { id: 1, data } });
+  return next;
+}
+async function telegramAgentDefaults() {
+  const e = (await getSetting()).telegram.engine;
+  if (!e.enabled) return sessionAgentDefaults();
+  return e.agent === "codex" ? { agent: "codex", model: e.model, effort: coerceCodexEffort(e.model, e.effort) } : { agent: "claude", model: e.model, effort: e.effort };
+}
+async function telegramEngineContext() {
+  const s2 = await getSetting();
+  return {
+    enabled: s2.telegram.engine.enabled,
+    effective: await telegramAgentDefaults(),
+    claude: { model: s2.model, effort: s2.effort },
+    codex: { model: s2.codex.model, effort: s2.codex.effort }
+  };
+}
+function telegramReloadNeeded(before, after) {
+  const strip = ({ engine: _engine, ...rest }) => rest;
+  return JSON.stringify(strip(before)) !== JSON.stringify(strip(after));
+}
+var init_config3 = __esm({
+  "src/services/telegram/config.ts"() {
+    "use strict";
+    init_src();
+    init_db();
+    init_settings2();
+  }
+});
+
 // src/services/telegram/protocol.ts
 import { createHash as createHash2 } from "node:crypto";
 function normalizeTelegramCommand(text) {
@@ -9959,7 +10052,7 @@ function splitTelegramText(text, max = 4096, exactSecrets = []) {
   if (rest) chunks.push(rest);
   return chunks;
 }
-var record, ANSI, CONTROLS, CREDENTIAL_PATTERNS;
+var record, ANSI, CONTROLS, CREDENTIAL_PATTERNS, TELEGRAM_GATEWAY_FAILURE_KIND, TELEGRAM_FINAL_REPLY_KINDS;
 var init_protocol = __esm({
   "src/services/telegram/protocol.ts"() {
     "use strict";
@@ -9971,6 +10064,14 @@ var init_protocol = __esm({
       /\bhnm_(?:agent_)?[A-Za-z0-9_-]{16,}\b/g,
       /\bsk-ant-[A-Za-z0-9_-]{16,}\b/g
     ];
+    TELEGRAM_GATEWAY_FAILURE_KIND = "gateway-failure";
+    TELEGRAM_FINAL_REPLY_KINDS = /* @__PURE__ */ new Set([
+      "final",
+      "decision",
+      "failure",
+      "confirmation",
+      TELEGRAM_GATEWAY_FAILURE_KIND
+    ]);
   }
 });
 
@@ -10022,6 +10123,69 @@ var init_runtime = __esm({
   }
 });
 
+// src/services/telegram/typing.ts
+var TYPING_ACTIVE_POLL_SEC, TYPING_MIN_INTERVAL_MS, TYPING_COOLDOWN_BASE_MS, TYPING_COOLDOWN_MIN_MS, TYPING_COOLDOWN_MAX_MS, TYPING_MAX_WAIT_MS, clampTypingCooldown, pollTimeoutFor, TelegramTypingIndicator;
+var init_typing = __esm({
+  "src/services/telegram/typing.ts"() {
+    "use strict";
+    init_client();
+    TYPING_ACTIVE_POLL_SEC = 4;
+    TYPING_MIN_INTERVAL_MS = 3e3;
+    TYPING_COOLDOWN_BASE_MS = 5e3;
+    TYPING_COOLDOWN_MIN_MS = 1e3;
+    TYPING_COOLDOWN_MAX_MS = 3e5;
+    TYPING_MAX_WAIT_MS = 6e5;
+    clampTypingCooldown = (ms) => Math.min(TYPING_COOLDOWN_MAX_MS, Math.max(TYPING_COOLDOWN_MIN_MS, Math.round(ms)));
+    pollTimeoutFor = (waiting, idle) => waiting > 0 ? Math.min(TYPING_ACTIVE_POLL_SEC, idle) : idle;
+    TelegramTypingIndicator = class {
+      constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? (() => Date.now());
+      }
+      state = /* @__PURE__ */ new Map();
+      now;
+      /** Paksa — MENGABAIKAN throttle. Telegram menghapus status typing tiap ada pesan masuk. */
+      async arm(chatId) {
+        await this.send(chatId, true);
+      }
+      /** Denyut loop; ter-throttle supaya iterasi cepat beruntun tak jadi banjir panggilan API. */
+      async refresh(chatIds) {
+        for (const chatId of chatIds) await this.send(chatId, false);
+        this.prune(new Set(chatIds));
+      }
+      async send(chatId, force) {
+        if (!this.deps.enabled) return;
+        const now = this.now();
+        const current = this.state.get(chatId);
+        if (current && now < current.cooldownUntil) return;
+        if (!force && current && now - current.lastArmedAt < TYPING_MIN_INTERVAL_MS) return;
+        try {
+          await this.deps.client.sendChatAction(chatId, "typing");
+          this.state.set(chatId, { lastArmedAt: now, cooldownUntil: 0, nextDelayMs: TYPING_COOLDOWN_BASE_MS });
+        } catch (error) {
+          const retryAfterMs = error instanceof TelegramApiError && typeof error.retryAfter === "number" && error.retryAfter > 0 ? error.retryAfter * 1e3 : null;
+          const delay = clampTypingCooldown(retryAfterMs ?? current?.nextDelayMs ?? TYPING_COOLDOWN_BASE_MS);
+          this.state.set(chatId, {
+            lastArmedAt: current?.lastArmedAt ?? 0,
+            cooldownUntil: now + delay,
+            nextDelayMs: clampTypingCooldown(delay * 2)
+          });
+        }
+      }
+      /** Chat yang sudah lama tak aktif dan tak sedang di-cooldown dibuang agar peta tak tumbuh. */
+      prune(active) {
+        const now = this.now();
+        for (const [chatId, entry] of this.state) {
+          if (active.has(chatId)) continue;
+          if (now < entry.cooldownUntil) continue;
+          if (now - entry.lastArmedAt <= TYPING_MAX_WAIT_MS) continue;
+          this.state.delete(chatId);
+        }
+      }
+    };
+  }
+});
+
 // src/services/telegram/gateway.ts
 import { createHash as createHash3 } from "node:crypto";
 var digestRaw, TelegramGateway;
@@ -10031,13 +10195,19 @@ var init_gateway = __esm({
     init_client();
     init_protocol();
     init_runtime();
+    init_typing();
     digestRaw = (update2) => createHash3("sha256").update(JSON.stringify(update2)).digest("hex");
     TelegramGateway = class {
       constructor(deps) {
         this.deps = deps;
+        this.typing = deps.typing ?? new TelegramTypingIndicator({
+          client: deps.client,
+          enabled: deps.progress
+        });
       }
       abort = null;
       loopPromise = null;
+      typing;
       async processUpdates(updates) {
         for (const raw of updates) await this.processUpdate(raw);
       }
@@ -10113,11 +10283,15 @@ var init_gateway = __esm({
             userId: input.userId,
             updateId: input.updateId,
             action: "dispatch",
-            outcome: target2.created ? "session-created" : "session-reused",
+            // SPEC-492 · command runtime dijawab gateway sendiri; jejaknya harus bisa dibedakan dari
+            // pesan yang benar-benar sampai ke sesi operator.
+            outcome: target2.control ? "control" : target2.created ? "session-created" : "session-reused",
             correlationId: `tg:${input.updateId}`
           });
+          await this.typing.arm(input.chatId);
           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 +10301,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: TELEGRAM_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() {
@@ -10153,6 +10334,7 @@ var init_gateway = __esm({
               } : void 0;
               const message = await this.deps.client.sendMessage({ chatId: row.chatId, text: chunks[index], replyMarkup });
               messageId = message.message_id;
+              if (!(isLast && TELEGRAM_FINAL_REPLY_KINDS.has(row.kind))) await this.typing.arm(row.chatId);
             }
             await this.deps.store.markOutboxSent(row.id, messageId);
           } catch (error) {
@@ -10178,22 +10360,31 @@ var init_gateway = __esm({
         });
       }
       async loop(signal) {
+        const idlePollTimeout = this.deps.pollTimeout ?? 25;
         while (!signal.aborted) {
           try {
+            const waiting = await this.deps.store.chatsAwaitingReply(new Date(Date.now() - TYPING_MAX_WAIT_MS));
+            await this.typing.refresh(waiting);
             const updates = await this.deps.client.getUpdates({
               offset: await this.deps.store.offset(),
               limit: 100,
-              timeout: this.deps.pollTimeout ?? 25,
+              timeout: pollTimeoutFor(waiting.length, idlePollTimeout),
               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));
           }
         }
       }
@@ -10205,6 +10396,112 @@ var init_gateway = __esm({
   }
 });
 
+// src/services/telegram/engine-command.ts
+function parseEngineCommand(text, ctx) {
+  const match = text.trim().match(/^\/(engine|runtime|model|effort)(?:\s+([\s\S]+))?$/i);
+  if (!match) return null;
+  const verb = match[1].toLowerCase();
+  const arg = (match[2] ?? "").trim();
+  if (verb === "engine") {
+    if (!arg) return { kind: "show" };
+    const word = arg.toLowerCase();
+    if (word === "off" || word === "mati") {
+      return {
+        kind: "set",
+        engine: { enabled: false, ...ctx.effective },
+        label: "Setelan operator Telegram \u2192 ikut default global sesi kerja"
+      };
+    }
+    if (word === "restart" || word === "ulang") return { kind: "restart" };
+    return { kind: "invalid", message: usage };
+  }
+  if (verb === "runtime") {
+    const word = arg.toLowerCase();
+    if (word !== "claude" && word !== "codex") {
+      return { kind: "invalid", message: "Runtime hanya `claude` atau `codex`. Contoh: `/runtime codex`" };
+    }
+    const agent = word;
+    const base2 = agent === "codex" ? ctx.codex : ctx.claude;
+    const effort = agent === "codex" ? coerceCodexEffort(base2.model, base2.effort) : base2.effort;
+    return {
+      kind: "set",
+      engine: { enabled: true, agent, model: base2.model, effort },
+      label: `Runtime \u2192 ${AGENT_LABEL[agent]}`
+    };
+  }
+  if (verb === "model") {
+    const agent = ctx.effective.agent;
+    const own = agent === "codex" ? codexModels() : claudeModels();
+    const other = agent === "codex" ? claudeModels() : codexModels();
+    if (!own.includes(arg)) {
+      if (other.includes(arg)) {
+        const swap = agent === "codex" ? "claude" : "codex";
+        return {
+          kind: "invalid",
+          message: `\`${arg}\` adalah model ${AGENT_LABEL[swap]}, sedangkan runtime aktif ${AGENT_LABEL[agent]}. Jalankan \`/runtime ${swap}\` dulu.`
+        };
+      }
+      return { kind: "invalid", message: `Model ${AGENT_LABEL[agent]} yang sah: ${own.join(", ")}.` };
+    }
+    const effort = agent === "codex" ? coerceCodexEffort(arg, ctx.effective.effort) : ctx.effective.effort;
+    return {
+      kind: "set",
+      engine: { enabled: true, agent, model: arg, effort },
+      label: `Model \u2192 ${arg}`
+    };
+  }
+  const allowed = effortsFor(ctx.effective);
+  if (!arg || !allowed.includes(arg)) {
+    return {
+      kind: "invalid",
+      message: `Effort yang sah untuk \`${ctx.effective.model}\`: ${allowed.join(", ")}.`
+    };
+  }
+  return {
+    kind: "set",
+    engine: { enabled: true, ...ctx.effective, effort: arg },
+    label: `Effort \u2192 ${arg}`
+  };
+}
+function formatEngineStatus(ctx, sessionAlive) {
+  return [
+    `Sesi operator berikutnya: ${triple(ctx.effective)}`,
+    ctx.enabled ? "Sumber: setelan sendiri untuk kanal Telegram." : "Sumber: default global sesi kerja (belum pakai setelan sendiri).",
+    sessionAlive ? "Sesi operator sekarang masih hidup dan tetap memakai setelan lamanya \u2014 `/engine restart` untuk menutupnya." : "Belum ada sesi operator yang hidup; pesan berikutnya lahir dengan setelan di atas.",
+    "",
+    usage
+  ].join("\n");
+}
+function formatEngineApplied(next, label, sessionAlive) {
+  const head = next.enabled ? `${label}. Sesi operator berikutnya: ${triple(next)}` : `${label}. Sesi operator berikutnya mengikuti default global sesi kerja.`;
+  return [
+    head,
+    sessionAlive ? "Sesi yang sedang jalan tidak diubah \u2014 ia satu proses, satu model seumur hidup. `/engine restart` menutupnya; ringkasan & memory tetap tersimpan." : "Berlaku untuk sesi operator berikutnya yang dibuat."
+  ].join("\n");
+}
+var AGENT_LABEL, TELEGRAM_CONTROL_KIND, claudeModels, codexModels, effortsFor, usage, triple;
+var init_engine_command = __esm({
+  "src/services/telegram/engine-command.ts"() {
+    "use strict";
+    init_src();
+    AGENT_LABEL = { claude: "Claude Code", codex: "Codex CLI" };
+    TELEGRAM_CONTROL_KIND = "gateway-control";
+    claudeModels = () => MODELS.map((m) => m.id);
+    codexModels = () => CODEX_MODELS.map((m) => m.id);
+    effortsFor = (t) => t.agent === "codex" ? codexEfforts(t.model) : EFFORTS;
+    usage = [
+      "Setelan runtime sesi operator Telegram:",
+      "`/engine` \u2014 lihat setelan sekarang",
+      "`/runtime claude|codex` \u2014 tukar runtime",
+      "`/model <id>` \u2014 tukar model",
+      "`/effort <nilai>` \u2014 tukar effort",
+      "`/engine off` \u2014 kembali ikut default global sesi kerja",
+      "`/engine restart` \u2014 tutup sesi operator supaya setelan berlaku sekarang"
+    ].join("\n");
+    triple = (t) => `${AGENT_LABEL[t.agent]} \xB7 \`${t.model}\` \xB7 \`${t.effort}\``;
+  }
+});
+
 // src/services/telegram/session.ts
 import { createHash as createHash4 } from "node:crypto";
 var chatHash, telegramOperatorSessionId, formatTelegramTurn, TelegramSessionCoordinator;
@@ -10212,6 +10509,7 @@ var init_session = __esm({
   "src/services/telegram/session.ts"() {
     "use strict";
     init_src2();
+    init_engine_command();
     chatHash = (chatId) => createHash4("sha256").update(chatId).digest("hex").slice(0, 16);
     telegramOperatorSessionId = (chatId) => `telegram-${chatHash(chatId)}`;
     formatTelegramTurn = (input) => `[Telegram update ${input.updateId} \xB7 chat ${input.chatId} \xB7 kind ${input.kind}]
@@ -10221,15 +10519,19 @@ ${input.text}`;
         this.deps = deps;
       }
       async dispatch(input) {
+        if (input.kind === "command") {
+          const handled = await this.control(input);
+          if (handled) return handled;
+        }
         let context = await this.deps.store.chatContext(input.chatId);
         if (!context) {
-          const defaults = await this.deps.defaults();
+          const seed = await this.deps.defaults();
           await this.deps.store.ensureChat({
             chatId: input.chatId,
             userId: input.userId,
-            agent: defaults.agent,
-            model: defaults.model,
-            effort: defaults.effort
+            agent: seed.agent,
+            model: seed.model,
+            effort: seed.effort
           });
           context = await this.deps.store.chatContext(input.chatId);
         }
@@ -10243,11 +10545,13 @@ ${input.text}`;
           if (context.sessionId !== sessionId2) await this.deps.store.bindSession(input.chatId, sessionId2);
           return { sessionId: sessionId2, created: false };
         }
+        const engine = await this.deps.defaults();
+        await this.deps.store.setChatEngine(input.chatId, engine);
         const hash2 = chatHash(input.chatId);
         const projectId = `telegram:${hash2}`;
         const cwd = `${this.deps.home.replace(/\/$/, "")}/telegram/${hash2}`;
         this.deps.ensureDir(cwd);
-        if (context.agent === "codex") this.deps.ensureCodexTrust(cwd);
+        if (engine.agent === "codex") this.deps.ensureCodexTrust(cwd);
         const personality = await this.deps.personality(context.personalityAgentId, context.activeProjectId);
         const prompt = buildTelegramOperatorPrompt({
           update: input,
@@ -10258,9 +10562,9 @@ ${input.text}`;
         const born = this.deps.port.createSession(projectId, cwd, {
           id: sessionId2,
           prompt,
-          agent: context.agent,
-          model: context.model,
-          effort: context.effort,
+          agent: engine.agent,
+          model: engine.model,
+          effort: engine.effort,
           env: {
             HANOMAN_API_BASE: this.deps.apiBase,
             HANOMAN_TELEGRAM_AGENT_TOKEN: this.deps.agentToken,
@@ -10271,6 +10575,48 @@ ${input.text}`;
         await this.deps.store.bindSession(input.chatId, sessionId2);
         return { sessionId: sessionId2, created: true };
       }
+      /**
+       * SPEC-492 · empat command runtime tak pernah menyentuh pane: ia soal transport, bukan isi
+       * hanoman, dan harus tetap bekerja saat agennya justru macet. `null` = bukan command runtime →
+       * pemanggil melanjutkan jalur lama persis seperti sebelumnya.
+       *
+       * Sengaja TIDAK mengetik `/model`/`/effort` ke pane hidup: ADR-0061 mencabut matrix per-fase
+       * karena mekanisme itu tak andal, dan SPEC-487 mengukur kelasnya (ketikan ke pane yang sedang
+       * menjalankan giliran mendarat sebagai pesan liar). Jalur yang dijanjikan ke operator adalah
+       * `/engine restart` — deterministik, dan konteksnya selamat lewat ringkasan + curated memory.
+       */
+      async control(input) {
+        const ctx = await this.deps.engine.read();
+        const cmd = parseEngineCommand(input.text, ctx);
+        if (!cmd) return null;
+        const sessionId2 = telegramOperatorSessionId(input.chatId);
+        const live = this.deps.port.getSession(sessionId2);
+        const alive = Boolean(live && !live.exited);
+        let text;
+        if (cmd.kind === "show") {
+          text = formatEngineStatus(ctx, alive);
+        } else if (cmd.kind === "invalid") {
+          text = cmd.message;
+        } else if (cmd.kind === "restart") {
+          if (alive) {
+            this.deps.port.killSession(sessionId2);
+            await this.deps.store.patchChat(input.chatId, { sessionId: null });
+            text = "Sesi operator ditutup. Pesan berikutnya lahir dengan setelan sekarang \u2014 ringkasan & curated memory tetap tersimpan.";
+          } else {
+            text = "Tak ada sesi operator yang sedang hidup. Pesan berikutnya lahir dengan setelan sekarang.";
+          }
+        } else {
+          await this.deps.engine.write(cmd.engine);
+          text = formatEngineApplied(cmd.engine, cmd.label, alive);
+        }
+        await this.deps.store.enqueueReply({
+          chatId: input.chatId,
+          updateId: input.updateId,
+          kind: TELEGRAM_CONTROL_KIND,
+          text
+        });
+        return { sessionId: sessionId2, created: false, control: true };
+      }
     };
   }
 });
@@ -10281,6 +10627,7 @@ var isUnique, TelegramStore;
 var init_store = __esm({
   "src/services/telegram/store.ts"() {
     "use strict";
+    init_protocol();
     isUnique = (error) => error instanceof Prisma3.PrismaClientKnownRequestError && error.code === "P2002";
     TelegramStore = class {
       // SPEC-481 · klien yang diekspor kini ber-extension (tap webhook) sehingga tak lagi
@@ -10346,6 +10693,15 @@ var init_store = __esm({
           update: { userId: input.userId }
         });
       }
+      /**
+       * SPEC-492 · cermin baris chat terhadap runtime yang BENAR-BENAR dipakai sesi operator terakhir.
+       * `ensureChat` sengaja tak menyentuh ketiganya (ia hanya menyegarkan `userId`), jadi tanpa ini
+       * `GET /telegram/chats/:chatId/context` — yang dibaca agen operator sendiri — melaporkan
+       * snapshot dari chat pertama, selamanya.
+       */
+      async setChatEngine(chatId, engine) {
+        await this.db.telegramChat.update({ where: { chatId }, data: engine });
+      }
       async chatContext(chatId) {
         const chat = await this.db.telegramChat.findUnique({ where: { chatId } });
         if (!chat) return null;
@@ -10379,6 +10735,38 @@ var init_store = __esm({
           data: { state: "uncertain", rejectReason: reason }
         });
       }
+      /**
+       * SPEC-493 · chat yang masih menunggu jawaban: ada `TelegramUpdate` `dispatched` sesudah `since`
+       * yang belum punya baris outbox ber-kind final. Dihitung pada saat **enqueue**, bukan `sent` —
+       * baris outbox lahir begitu session operator memanggil `POST /telegram/replies`, dan jarak
+       * enqueue→kirim paling banyak satu iterasi loop. Menunggu `sent` akan menahan typing melewati
+       * pesan finalnya sendiri.
+       *
+       * `since` adalah pagar keras: update yang session operatornya mati mengendap `dispatched`
+       * SELAMANYA, dan tanpa pagar ini gateway akan mengetik selamanya sekaligus mengunci long-poll
+       * di 4 detik selamanya.
+       */
+      async chatsAwaitingReply(since) {
+        const pending = await this.db.telegramUpdate.findMany({
+          where: { state: "dispatched", chatId: { not: null }, dispatchedAt: { gte: since } },
+          select: { updateId: true, chatId: true },
+          orderBy: { updateId: "asc" }
+        });
+        if (!pending.length) return [];
+        const answered = new Set((await this.db.telegramOutbox.findMany({
+          where: {
+            updateId: { in: pending.map((row) => row.updateId) },
+            kind: { in: [...TELEGRAM_FINAL_REPLY_KINDS] }
+          },
+          select: { updateId: true }
+        })).map((row) => row.updateId));
+        const chats = [];
+        for (const row of pending) {
+          if (answered.has(row.updateId) || !row.chatId || chats.includes(row.chatId)) continue;
+          chats.push(row.chatId);
+        }
+        return chats;
+      }
       async addMemory(chatId, content) {
         return this.memoryView(await this.db.telegramMemory.create({ data: { chatId, content } }));
       }
@@ -10513,7 +10901,8 @@ __export(bootstrap_exports, {
   TELEGRAM_REQUIRED_CAPABILITIES: () => TELEGRAM_REQUIRED_CAPABILITIES,
   installTelegramGateway: () => installTelegramGateway,
   parseTelegramAllowedUserIds: () => parseTelegramAllowedUserIds,
-  reloadTelegramGateway: () => reloadTelegramGateway
+  reloadTelegramGateway: () => reloadTelegramGateway,
+  telegramSessionDeps: () => telegramSessionDeps
 });
 import { mkdirSync as mkdirSync7 } from "node:fs";
 function parseTelegramAllowedUserIds(raw) {
@@ -10522,14 +10911,14 @@ function parseTelegramAllowedUserIds(raw) {
   if (ids.some((id) => !/^\d+$/.test(id))) throw new Error("Telegram allowlist hanya menerima numeric user id");
   return new Set(ids);
 }
-async function productionFactory(input) {
-  const client = new TelegramApiClient(input.botToken);
-  const me = await client.getMe();
-  const store3 = new TelegramStore(prisma);
-  const coordinator = new TelegramSessionCoordinator({
-    store: store3,
-    port: { getSession, createSession, sendToPane },
-    defaults: sessionAgentDefaults,
+function telegramSessionDeps(input) {
+  return {
+    store: input.store,
+    port: { getSession, createSession, sendToPane, killSession },
+    // SPEC-492 · BUKAN `sessionAgentDefaults`: sesi operator Telegram sebagian besar membaca API
+    // lalu merangkum, bukan menulis kode, jadi ia boleh punya runtime/model/effort sendiri.
+    defaults: telegramAgentDefaults,
+    engine: { read: telegramEngineContext, write: setTelegramEngine },
     personality: async (id, projectId) => {
       if (!id) return null;
       const row = await prisma.customAgent.findUnique({ where: { id } });
@@ -10541,7 +10930,17 @@ async function productionFactory(input) {
     apiBase: input.apiBase,
     agentToken: input.agentToken,
     ensureDir: (path) => mkdirSync7(path, { recursive: true })
-  });
+  };
+}
+async function productionFactory(input) {
+  const client = new TelegramApiClient(input.botToken);
+  const me = await client.getMe();
+  const store3 = new TelegramStore(prisma);
+  const coordinator = new TelegramSessionCoordinator(telegramSessionDeps({
+    apiBase: input.apiBase,
+    agentToken: input.agentToken,
+    store: store3
+  }));
   const gateway = new TelegramGateway({
     client,
     store: store3,
@@ -10653,6 +11052,7 @@ var init_bootstrap = __esm({
     init_settings2();
     init_pty();
     init_client();
+    init_config3();
     init_gateway();
     init_session();
     init_store();
@@ -17222,17 +17622,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 +17641,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 +18083,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 +18375,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 +18422,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 +18438,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 +18446,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 +18457,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 +18480,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 +18980,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 +18991,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 +19115,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 +21728,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));
@@ -21782,6 +22210,7 @@ init_src();
 init_db();
 init_settings2();
 init_bootstrap();
+init_config3();
 async function settings_default(app2) {
   app2.get("/settings", async () => getSetting());
   app2.put("/settings", async (req, reply) => {
@@ -21793,7 +22222,7 @@ async function settings_default(app2) {
       update: { data: parsed.data },
       create: { id: 1, data: parsed.data }
     });
-    if (JSON.stringify(before.telegram) !== JSON.stringify(parsed.data.telegram)) {
+    if (telegramReloadNeeded(before.telegram, parsed.data.telegram)) {
       await reloadTelegramGateway();
     }
     return row.data;
@@ -22009,16 +22438,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 +22465,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 +22866,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 +23332,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 +23472,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 +23977,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 +24761,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 +24787,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 +25136,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 +25147,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 +25158,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 +25311,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 +25339,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 +26367,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 +26380,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 +26417,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 +26936,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 +26945,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 +26965,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 +27016,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 +27047,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 +27080,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 +27131,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 +27159,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 +27174,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 +27209,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 +27236,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 +28145,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 +28153,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 +28472,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 +28525,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 +28539,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 +28561,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 +28578,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 +29487,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 +29549,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);