@kienntpixon/dieu-phoi 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog — @kienntpixon/dieu-phoi
 
+## 0.3.0
+
+- **Khởi động không qua shell:** hook mới `UserPromptSubmit` (`setup` đăng ký, không matcher, timeout 5 s; chạy lại không nhân đôi; `uninstall` gỡ). Chỉ kích hoạt khi prompt **mở đầu** (sau khi cắt khoảng trắng) bằng `/dieu-phoi`, "điều phối" (không phân biệt hoa thường / có dấu hay không, có thể kèm ":") hoặc một cụm đặc trưng "spawn subagents", "orchestrate subagents", "chia việc cho agent", "giao cho subagent"; "điều phối" ở giữa câu ("trung tâm điều phối…", "không cần điều phối") không kích hoạt, yêu cầu kiểu retro / state / stats / lệnh CLI và "điều phối viên…" cũng không → hook tạo sẵn `root_task_id` (cùng bộ sinh với `new-id`), **tạo** run dir `~/.dieu-phoi/runs/<id>/` (theo `DIEU_PHOI_RUNS_DIR`), 10 `step_ids` dự phòng cho các bước, tình trạng sức khoẻ cục bộ và đường dẫn brief scout dựng sẵn, rồi tiêm vào `hookSpecificOutput.additionalContext` (dòng đầu `dieu-phoi: khởi động sẵn (hook UserPromptSubmit, …)`). Prompt khác → im lặng. Không gọi mạng, không ghi sự kiện, luôn exit 0 (lỗi → `hook-errors.log`). Đo: ~40 ms cả tiến trình node, < 5 ms phần xử lý. Lý do: lệnh shell đầu tiên của phiên Claude Code trong repo lớn có thể treo 6–11 phút trước khi có shell snapshot; trước đây `doctor; new-id` nằm đúng trên đường găng của cổng 1.
+- Lệnh mới `dieu-phoi start [--json]`: dự phòng khi hook không chạy — một lệnh (~50 ms) kiểm cục bộ (hook đã cài/đăng ký, `UserPromptSubmit`, quyền run dir, config, profile, sink từ bộ nhớ đệm), sinh `root_task_id` + `step_ids`, tạo run dir, in đường dẫn brief scout. Không gọi mạng; luôn exit 0, vấn đề nằm trong `health`.
+- **`doctor` thôi gọi mạng mỗi lần:** trạng thái sink lấy từ bộ nhớ đệm 24 giờ — `data/sink-check.json` (lần kiểm trực tiếp gần nhất của `doctor`, gắn với URL sink) hoặc `data/last-sync.json` (sync nền; từ 0.3.0 mang khoá `url` = sha256-8 của `sink_url`, khác URL hiện tại hoặc thiếu khoá → không dùng); không có bản nào còn hạn → kiểm trực tiếp một lần rồi lưu (kể cả khi lỗi). `doctor --net` buộc kiểm trực tiếp. Trước đây `doctor` mất 3,5–4,9 s, trong đó 3–4 s là request tới Apps Script.
+- `doctor` có dòng `prompt-hook` (CẢNH BÁO khi thiếu hook `UserPromptSubmit` — chạy lại `setup`); dòng `settings` vẫn chỉ xét 3 hook cũ nên cài đặt 0.2.x không bị báo LỖI.
+- Core export `isDieuPhoiPrompt`, `sinkStatusCached`, `quickHealth`, `startInfo`, `handleUserPromptSubmit`, … để CLI và hook dùng chung.
+
 ## 0.2.2
 
 - **Trần model hạ xuống `opus/medium`** (trước là `opus/high`). Thang tier bỏ `opus/high`: `haiku/low … sonnet/high < opus/medium`. Mọi (model, effort) cao hơn (opus `high`/`xhigh`/`max`, Fable) bị kẹp về `opus/medium` khi đọc log và profile; `--override opus/high` / `--approved opus/high` bị từ chối (không nằm trên thang, lỗi nêu trần `opus/medium`).

package/README.md

@@ -34,8 +34,8 @@ Khởi động lại Claude Code sau khi cài. Kiểm tra bằng `dieu-phoi doct
 
 | Lệnh | Việc |
 |---|---|
-| `setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]` | cài hook, đăng ký `PostToolUse(Agent)` + `SubagentStop` + `SessionStart(compact)` trong settings, ghi config; tạo thư mục báo cáo `~/.dieu-phoi/runs` (env `DIEU_PHOI_RUNS_DIR` để đổi; ngoài `~/.claude` vì đó là protected path) và thêm quyền `Read`/`Edit(~/.dieu-phoi/runs/**)` + `additionalDirectories` để subagent nền ghi được báo cáo (không nhân đôi, có sao lưu); gỡ luật cũ của bản dev cho `~/.claude/dieu-phoi/runs` |
-| `doctor [--json]` | kiểm node, hook, settings, config, profile, sink; context phiên điều phối hiện tại nếu đo được (`orch-ctx`); thư mục `~/.dieu-phoi/runs` + quyền của nó, không còn luật cũ (`run-permissions`); `--json` có `runs_dir` |
+| `setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]` | cài hook, đăng ký `PostToolUse(Agent)` + `SubagentStop` + `SessionStart(compact)` + `UserPromptSubmit` trong settings, ghi config; tạo thư mục báo cáo `~/.dieu-phoi/runs` (env `DIEU_PHOI_RUNS_DIR` để đổi; ngoài `~/.claude` vì đó là protected path) và thêm quyền `Read`/`Edit(~/.dieu-phoi/runs/**)` + `additionalDirectories` để subagent nền ghi được báo cáo (không nhân đôi, có sao lưu); gỡ luật cũ của bản dev cho `~/.claude/dieu-phoi/runs` |
+| `doctor [--net] [--json]` | kiểm node, hook, settings (+ `prompt-hook`), config, profile, sink (từ bộ nhớ đệm 24 giờ; `--net` kiểm trực tiếp); context phiên điều phối hiện tại nếu đo được (`orch-ctx`); thư mục `~/.dieu-phoi/runs` + quyền của nó, không còn luật cũ (`run-permissions`); `--json` có `runs_dir` |
 | `verdict <agent_id\|last> <pass\|fail\|timeout> [--verify tests\|lint\|review\|judgment\|none] [--reason short-kebab]` | nghiệm thu tầng agent (`by=agent`). `last` = agent hoàn thành gần nhất; từ chối (liệt kê ứng viên) nếu trong 30 phút qua có > 1 agent xong mà chưa có verdict. Được viết tắt agent_id nếu không trùng |
 | `verdict --task <task_id> <accept\|reject> [--cause quality\|scope] [--round n] [--reason R]` | nghiệm thu của **người dùng** (`by=user`). `reject` bắt buộc `--cause`: `quality` = làm sai (tính là fail), `scope` = yêu cầu đổi/thiếu (không tính cho model). `--round` mặc định tự tăng |
 | `steer <agent_id> \| --task <task_id> --kind minor\|plan\|redirect [--reason R]` | ghi **một** lần người dùng lái giữa chừng (một `steer_id`). `--task` chỉ đánh dấu agent đang chạy của task; không có agent nào đang chạy → bản ghi cấp task. `plan`/`redirect` trước verdict loại lượt đó khỏi tỉ lệ của tier (chi phí vẫn tính); steer không xoá fail đã ghi |
@@ -44,6 +44,7 @@ Khởi động lại Claude Code sau khi cài. Kiểm tra bằng `dieu-phoi doct
 | `ctx [--session <id>] [--json]` | context phiên điều phối: `ctx_tokens` (request cuối), `ctx_baseline` (request đầu: system prompt + tools), `ctx_growth`, chi phí cộng dồn `cum_usd`, số lần đã nén `compactions`; `over` = `ctx_growth` > `orch_ctx_soft_cap` (profile, mặc định 60000 token tăng, chỉ được hạ). Session mặc định = `$CLAUDE_CODE_SESSION_ID`. JSON: `session_id, ctx_tokens, ctx_baseline, ctx_growth, cum_usd, compactions, soft_cap, over, advice`. Vượt trần → khuyên gõ `/compact` (trạng thái điều phối được nạp lại tự động). Đọc tăng dần qua cache `data/orch/`. Không đo được → exit 0, các số `null`, `over: false` |
 | `state [--session <id>] [--json]` | trạng thái điều phối của phiên dựng lại chỉ từ log: mỗi task — cổng (1/2/3/xong), vòng, tier, các lượt (agent, role, try, model/effort, running/done/pass/fail/timeout), verdict người dùng, steer cuối, thư mục chạy; nhóm theo kế hoạch đã duyệt (tier đã duyệt, bước "chưa giao", thư mục chạy theo root). Hook `SessionStart(compact)` tự nạp bản này vào ngữ cảnh sau `/compact` hoặc auto-compact. Bản chữ ≤ 8.000 ký tự |
 | `plan-table --file <steps.json> [--json] [--approve --root <root_task_id>]` | bảng phân công tiếng Việt (Bước \| Model/effort \| Rubric: điểm · kiểm chứng · đảo ngược \| Lý do \| Ước tính) + tổng chi phí + thời gian đường găng. Bước lỗi (override sai) hiện \"từ chối: …\", các bước khác vẫn hiện. Sau khi người dùng duyệt: `--approve --root R` ghi kế hoạch đã duyệt vào `data/plans/R.json` (cục bộ; `approval` = số lần duyệt, duyệt lại = +1, lần cũ vào `history`) và in thêm "Đã ghi kế hoạch đã duyệt (root R, lần duyệt n)". Từ chối (không ghi gì) khi bước thiếu `task_id`, `task_id` sai định dạng, `task_id` lặp, hoặc trùng `--root`; `--root` phải đúng 8 ký tự `a-z0-9` |
+| `start [--json]` | khởi động cổng 1 trong một lệnh, không gọi mạng: kiểm cục bộ, `root_task_id` + `step_ids`, tạo run dir, đường dẫn brief scout. Thường không cần: hook `UserPromptSubmit` làm sẵn việc này khi prompt có "điều phối" hoặc bắt đầu bằng `/dieu-phoi` |
 | `new-id [--count n] [--json]` | in task_id mới hợp lệ (đúng 8 ký tự `a-z0-9`), mỗi dòng một id (mặc định 1, tối đa 1000; `--json`: mảng). Lấy mọi `task_id` / `root_task_id` từ đây — không tự bịa. `choose/verdict/steer --task` và `plan-table --approve` từ chối id sai định dạng (kèm gợi ý id mới); hook vẫn ghi id cũ nhưng gắn `task_id_invalid: true`, `doctor` cảnh báo |
 | `sync [--json]` | đẩy bản ghi chưa đồng bộ lên sink, lô ≤ 200, có thử lại. Bản ghi sink từ chối → `data/sync-rejected.jsonl`, `doctor` báo số lượng |
 | `retro [--json]` | tóm tắt cho vòng retro: số liệu từng ô, đếm `reason_code`, danh sách loại task, tóm tắt điều phối (`orchestration`) |

package/bin/dieu-phoi.cjs

@@ -10,7 +10,9 @@ Cách dùng: dieu-phoi <lệnh> [tuỳ chọn]
 
   setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]
                          cài hook vào ~/.claude/dieu-phoi/bin, đăng ký trong settings.json
-  doctor                 kiểm hook, node, config, sink
+  doctor [--net]         kiểm hook, node, config, sink (sink lấy từ bộ nhớ đệm 24 giờ; --net kiểm trực tiếp)
+  start [--json]         khởi động cổng 1 trong một lệnh (~150 ms, không gọi mạng): kiểm cục bộ, task_id gốc,
+                         tạo run dir, đường dẫn brief scout — dùng khi hook UserPromptSubmit không chạy
   verdict <agent_id|last> <pass|fail|timeout> [--verify tests|lint|review|judgment|none] [--reason short-kebab]
                          nghiệm thu tầng agent (by=agent)
   verdict --task <task_id> <accept|reject> [--cause quality|scope] [--round n] [--reason R]
@@ -63,6 +65,7 @@ async function main(argv) {
   const table = {
     setup: c.cmdSetup,
     doctor: c.cmdDoctor,
+    start: c.cmdStart,
     verdict: c.cmdVerdict,
     steer: c.cmdSteer,
     'plan-table': c.cmdPlanTable,

package/hook.cjs

@@ -4,10 +4,11 @@
  * dieu-phoi hook + core helpers.
  *
  * This file is copied verbatim to ~/.claude/dieu-phoi/bin/hook.cjs by `dieu-phoi setup`
- * and run by Claude Code on PostToolUse(Agent) and SubagentStop. It must stay
+ * and run by Claude Code on PostToolUse(Agent), SubagentStop, SessionStart(compact) and UserPromptSubmit. It must stay
  * self-contained: Node built-ins only, no requires of other package files.
  *
- * Hook rules: never write to stdout, always exit 0, no synchronous network.
+ * Hook rules: stdout only for the JSON of SessionStart(compact) / UserPromptSubmit, always exit 0,
+ * no network.
  * Errors go to <home>/hook-errors.log.
  *
  *   node hook.cjs            -> read hook payload from stdin, append event
@@ -19,7 +20,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.2.2';
+const CORE_VERSION = '0.3.0';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -124,6 +125,7 @@ function pathsFor(home) {
     syncOffset: path.join(data, 'sync-offset.json'),
     syncSpawn: path.join(data, 'sync-spawn.json'),
     lastSync: path.join(data, 'last-sync.json'),
+    sinkCheck: path.join(data, 'sink-check.json'),
     syncRejected: path.join(data, 'sync-rejected.jsonl'),
     lock: path.join(data, 'sync.lock'),
     config: path.join(home, 'config.json'),
@@ -1140,6 +1142,147 @@ function handleSessionStart(p, ctx) {
   };
 }
 
+// ------------------------------------------------------------------ fast start (UserPromptSubmit + `start`)
+
+const SINK_CACHE_TTL_MS = 24 * 3600 * 1000;
+const START_PREFIX = 'dieu-phoi: khởi động sẵn (hook UserPromptSubmit, không cần chạy shell trước scout):';
+
+/**
+ * Prompt that starts a NEW dieu-phoi orchestration. Conservative: the trigger must OPEN the prompt
+ * (after trimming) — `/dieu-phoi`, "điều phối" (any case, with or without diacritics, optionally
+ * followed by ":"), or one of the skill's distinctive phrases ("spawn subagents", "orchestrate
+ * subagents", "chia việc cho agent", "giao cho subagent"). "điều phối" elsewhere in the prompt never
+ * fires. Retro / state / stats / CLI-style requests and "điều phối viên …" never fire (not a gate 1).
+ */
+const PROMPT_START_RE = /^(?:\/dieu-phoi|dieu phoi|spawn (?:\d+ )?sub-?agents?|orchestrate sub-?agents?|chia viec cho (?:cac )?(?:sub-?)?agents?|giao (?:viec )?cho (?:cac )?sub-?agents?)(?=$|[\s:,.!?])/;
+const PROMPT_REST_EXCLUDE_RE = /^[\s:,.!?-]*(?:vien\b|retro|state\b|stats?\b|status\b|trang thai|thong ke|ctx\b|doctor|setup\b|start\b|sync\b|uninstall|new-id|choose\b|plan-table|verdict|steer\b)/;
+const PROMPT_ANY_EXCLUDE_RE = /\b(?:retro|thong ke)\b/;
+
+function foldPrompt(s) {
+  return String(s).toLowerCase().replace(/đ/g, 'd').normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .replace(/\s+/g, ' ');
+}
+
+function isDieuPhoiPrompt(prompt) {
+  if (typeof prompt !== 'string' || !prompt) return false;
+  const t = foldPrompt(prompt.trimStart().slice(0, 300)).trim();
+  const m = PROMPT_START_RE.exec(t);
+  if (!m) return false;
+  if (PROMPT_REST_EXCLUDE_RE.test(t.slice(m[0].length))) return false;
+  return !PROMPT_ANY_EXCLUDE_RE.test(t);
+}
+
+function sinkUrlKey(cfg) {
+  return cfg && cfg.sink_url ? sha8(String(cfg.sink_url)) : null;
+}
+
+/**
+ * Sink health without a network call: newest of data/sink-check.json (doctor's live check, same sink
+ * URL) and data/last-sync.json (every background sync) within 24 h.
+ * Returns { state: 'none'|'ok'|'fail'|'unknown', ts, source, detail }.
+ */
+function sinkStatusCached(ctx, nowMs) {
+  const cfg = ctx.config || {};
+  if (!cfg.sink_url || !cfg.sink_token) return { state: 'none', ts: null, source: null, detail: 'chưa cấu hình (chỉ lưu cục bộ)' };
+  const now = nowMs || Date.now();
+  const cands = [];
+  const chk = readJsonFile(ctx.paths.sinkCheck, null);
+  if (chk && chk.url === sinkUrlKey(cfg) && Date.parse(chk.ts)) {
+    cands.push({ state: chk.ok ? 'ok' : 'fail', ts: chk.ts, source: 'doctor', detail: chk.detail || null });
+  }
+  const ls = readJsonFile(ctx.paths.lastSync, null);
+  // last-sync is only trusted for the sink it was written for (sink_url changed → stale)
+  if (ls && ls.url === sinkUrlKey(cfg) && Date.parse(ls.ts)) {
+    cands.push({ state: ls.ok ? 'ok' : 'fail', ts: ls.ts, source: 'sync', detail: ls.ok ? `đẩy ${ls.sent || 0} bản ghi` : (ls.error || 'lỗi') });
+  }
+  const fresh = cands.filter((c) => now - Date.parse(c.ts) <= SINK_CACHE_TTL_MS && Date.parse(c.ts) <= now + 60000)
+    .sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
+  if (fresh.length) return fresh[0];
+  return { state: 'unknown', ts: null, source: null, detail: 'chưa kiểm trong 24 giờ qua (`dieu-phoi doctor --net`)' };
+}
+
+/** Absolute path of the ready-made scout brief of the installed skill, or null. */
+function scoutBriefPath(ctx) {
+  const sd = ctx.config && ctx.config.skill_dir;
+  if (!sd) return null;
+  const f = path.join(sd, 'references', 'scout-brief.md');
+  return fs.existsSync(f) ? toPosix(f) : null;
+}
+
+/** Local, network-free health: config, profile, run dir, cached sink status. */
+function quickHealth(ctx, runs) {
+  const problems = [];
+  if (!fs.existsSync(ctx.paths.config)) problems.push('chưa có config — chạy `dieu-phoi setup --dept <phòng>`');
+  const sd = ctx.config.skill_dir;
+  if (!sd || !fs.existsSync(path.join(sd, 'profile', 'profile.json'))) problems.push('không thấy profile của skill — `choose` dùng priors mặc định');
+  if (runs && !fs.existsSync(runs)) problems.push(`chưa có thư mục ${toPosix(runs)}`);
+  const sink = sinkStatusCached(ctx);
+  if (sink.state === 'fail') problems.push(`sink lỗi lần cuối (${sink.ts}): ${sink.detail}`);
+  return { ok: !problems.length, problems, sink };
+}
+
+/** Fresh root task id + its run dir, created. Retries on the (astronomically rare) existing dir. */
+function startRun() {
+  const runs = runsDir();
+  fs.mkdirSync(runs, { recursive: true });
+  for (let i = 0; i < 5; i++) {
+    const id = newTaskId();
+    const dir = path.join(runs, id);
+    try {
+      fs.mkdirSync(dir);
+      return { id, run_dir: toPosix(dir), runs };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+    }
+  }
+  throw new Error('không tạo được run dir mới');
+}
+
+function healthLine(h) {
+  const sink = h.sink.state === 'ok' ? `sink ok (${h.sink.source} ${h.sink.ts})`
+    : h.sink.state === 'none' ? 'sink chưa cấu hình' : `sink ${h.sink.state === 'fail' ? 'LỖI' : 'chưa rõ'}`;
+  return h.ok ? `ok — ${sink}` : `CẢNH BÁO — ${h.problems.join('; ')}${h.sink.state === 'fail' ? '' : ` — ${sink}`}`;
+}
+
+const START_STEP_IDS = 10;
+
+/** Spare task_ids for the plan steps, distinct from the root, so the scout needs no `new-id` shell call. */
+function stepIds(root, n) {
+  const ids = new Set();
+  while (ids.size < n) { const id = newTaskId(); if (id !== root) ids.add(id); }
+  return Array.from(ids);
+}
+
+function startInfo(ctx) {
+  const run = startRun();
+  const health = quickHealth(ctx, run.runs);
+  return { id: run.id, run_dir: run.run_dir, step_ids: stepIds(run.id, START_STEP_IDS), health, scout_brief: scoutBriefPath(ctx) };
+}
+
+function formatStartBlock(info) {
+  return [
+    START_PREFIX,
+    `root_task_id: ${info.id}`,
+    `run_dir: ${info.run_dir}/ (đã tạo)`,
+    `step_ids: ${info.step_ids.join(' ')}`,
+    `health: ${healthLine(info.health)}`,
+    `scout_brief: ${info.scout_brief || '(không thấy — dùng references/brief-template.md mục E)'}`,
+    'Dùng khối này cho yêu cầu MỚI ở cổng 1 (không dùng nếu đang giữa một lần điều phối). Không chạy `dieu-phoi doctor` / `new-id` / mkdir: lượt đầu tiên là Agent scout + câu hỏi cổng 1 cho người dùng.',
+  ].join('\n');
+}
+
+/** UserPromptSubmit: on a dieu-phoi prompt, pre-create the run and inject id/run dir/health/brief. */
+function handleUserPromptSubmit(p, ctx) {
+  if (!isDieuPhoiPrompt(p.prompt)) return null;
+  const info = startInfo(ctx);
+  return {
+    stdout: JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: formatStartBlock(info) },
+    }),
+    info,
+  };
+}
+
 // ------------------------------------------------------------------ hook handlers
 
 function extractAgentId(tr) {
@@ -1337,6 +1480,7 @@ function runHook(opts) {
     let ev = null;
     const name = p.hook_event_name;
     if (name === 'SessionStart') return handleSessionStart(p, ctx); // { stdout } or null, never an event
+    if (name === 'UserPromptSubmit') return handleUserPromptSubmit(p, ctx); // { stdout } or null
     if (name === 'SubagentStop') ev = handleSubagentStop(p, ctx);
     else if (name === 'PostToolUse' || (!name && p.tool_name)) ev = handlePostToolUse(p, ctx);
     if (ev) {
@@ -1477,7 +1621,7 @@ async function runSync(ctx, opts) {
   } finally {
     try {
       writeFileAtomic(ctx.paths.lastSync, `${JSON.stringify({
-        ts: nowIso(), ok: result.ok, sent: result.sent, error: result.error,
+        ts: nowIso(), ok: result.ok, sent: result.sent, error: result.error, url: sinkUrlKey(cfg),
       })}\n`);
     } catch (_) { /* best effort */ }
     try { fs.unlinkSync(ctx.paths.lock); } catch (_) { /* gone */ }
@@ -1488,7 +1632,7 @@ async function runSync(ctx, opts) {
 // ------------------------------------------------------------------ exports / main
 
 module.exports = {
-  runsDir, loadPlans, buildSessionState, formatSessionState, stateCounts, compactSystemMessage, handleSessionStart, dispatchInSession, STATE_TEXT_CAP, COMPACT_PREFIX,
+  runsDir, loadPlans, isDieuPhoiPrompt, foldPrompt, sinkStatusCached, sinkUrlKey, SINK_CACHE_TTL_MS, scoutBriefPath, quickHealth, startRun, startInfo, stepIds, START_STEP_IDS, healthLine, formatStartBlock, handleUserPromptSubmit, START_PREFIX, buildSessionState, formatSessionState, stateCounts, compactSystemMessage, handleSessionStart, dispatchInSession, STATE_TEXT_CAP, COMPACT_PREFIX,
   CORE_VERSION, SCHEMA, TASK_TYPES, URGENCIES, ROLES, MODEL_ALIASES, UNTAGGED,
   sha8, nowIso, readJsonFile, writeFileAtomic, defaultClaudeDir, resolveHome, pathsFor, loadConfig, makeCtx,
   logError, computeUserHash, userHash, commonFields, parseTag, TASK_ID_RE, isValidTaskId, newTaskId, taskIdError, normalizeModel, loadPricing,

package/lib/commands.cjs

@@ -63,7 +63,7 @@ function cmdSetup(opts) {
   const lines = [
     `Đã cài hook: ${res.hook}`,
     res.settings_changed
-      ? `Đã đăng ký PostToolUse(Agent) + SubagentStop + SessionStart(compact) trong ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}`
+      ? `Đã đăng ký PostToolUse(Agent) + SubagentStop + SessionStart(compact) + UserPromptSubmit trong ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}`
       : `settings.json đã có hook, không đổi gì (${res.settings})`,
     `Thư mục báo cáo subagent: ${res.runs_dir} (quyền: ${res.permissions.allow.join(', ')} + additionalDirectories)`,
     `Phòng ban: ${res.config.dept || '(chưa đặt, dùng --dept)'}`,
@@ -98,6 +98,9 @@ async function cmdDoctor(opts) {
   const reg = setupLib.registration(claudeDir);
   add(reg.PostToolUse && reg.SubagentStop && reg.SessionStart, 'settings',
     `PostToolUse(Agent)=${reg.PostToolUse ? 'có' : 'thiếu'}, SubagentStop=${reg.SubagentStop ? 'có' : 'thiếu'}, SessionStart(compact)=${reg.SessionStart ? 'có' : 'thiếu'} (${reg.file})`);
+  add(reg.UserPromptSubmit, 'prompt-hook', reg.UserPromptSubmit
+    ? 'UserPromptSubmit có — prompt "điều phối" được tạo sẵn task_id + run dir, lượt đầu là scout'
+    : 'thiếu hook UserPromptSubmit — mỗi lần điều phối phải chạy `dieu-phoi start` trước scout; chạy lại `dieu-phoi setup`', 'CẢNH BÁO');
   const permOk = reg.permissions && reg.runs_dir_exists && !reg.legacy_permissions;
   add(permOk, 'run-permissions', permOk
     ? `${reg.permission_entries.allow.join(', ')} + additionalDirectories ${reg.permission_entries.dir}`
@@ -147,17 +150,12 @@ async function cmdDoctor(opts) {
     add(!orch.over, 'orch-ctx', `session ${orch.session_id}: ${orch.ctx_tokens} token, tăng ${orch.ctx_growth}/${orch.soft_cap}, ≈ ${fmtUsd(orch.cum_usd)} — ${orch.advice}`, 'CẢNH BÁO');
   }
   if (ctx.config.sink_url && ctx.config.sink_token) {
-    try {
-      const u = new URL(ctx.config.sink_url);
-      u.searchParams.set('token', ctx.config.sink_token);
-      u.searchParams.set('view', 'stats');
-      const res = await fetch(u, { redirect: 'follow', signal: AbortSignal.timeout(8000) });
-      const txt = await res.text();
-      let ok = res.ok;
-      try { const b = JSON.parse(txt); if (b && b.ok === false) ok = false; } catch (_) { ok = false; }
-      add(ok, 'sink', `${ctx.config.sink_url} → HTTP ${res.status}`);
-    } catch (e) {
-      add(false, 'sink', `${ctx.config.sink_url} → ${e.message}`);
+    const cached = opts.net ? null : core.sinkStatusCached(ctx);
+    if (cached && (cached.state === 'ok' || cached.state === 'fail')) {
+      add(cached.state === 'ok', 'sink', `${ctx.config.sink_url} → ${cached.state === 'ok' ? 'ok' : `lỗi: ${cached.detail}`} (bộ nhớ đệm: ${cached.source} lúc ${cached.ts}; \`doctor --net\` để kiểm trực tiếp)`);
+    } else {
+      const live = await checkSinkLive(ctx);
+      add(live.ok, 'sink', `${ctx.config.sink_url} → ${live.detail}`);
     }
   } else {
     add(true, 'sink', 'chưa cấu hình (chỉ lưu cục bộ)');
@@ -168,6 +166,55 @@ async function cmdDoctor(opts) {
   return { code: failed ? 1 : 0, out };
 }
 
+/** Live sink check (view=stats); result cached in data/sink-check.json for 24 h. */
+async function checkSinkLive(ctx) {
+  let ok = false;
+  let detail;
+  try {
+    const u = new URL(ctx.config.sink_url);
+    u.searchParams.set('token', ctx.config.sink_token);
+    u.searchParams.set('view', 'stats');
+    const res = await fetch(u, { redirect: 'follow', signal: AbortSignal.timeout(8000) });
+    const txt = await res.text();
+    ok = res.ok;
+    try { const b = JSON.parse(txt); if (b && b.ok === false) ok = false; } catch (_) { ok = false; }
+    detail = `HTTP ${res.status}`;
+  } catch (e) {
+    detail = e.message;
+  }
+  try {
+    core.writeFileAtomic(ctx.paths.sinkCheck, `${JSON.stringify({ ts: core.nowIso(), ok, detail, url: core.sinkUrlKey(ctx.config) })}\n`);
+  } catch (_) { /* cache is best effort */ }
+  return { ok, detail };
+}
+
+// ------------------------------------------------------------------ start
+
+/**
+ * `dieu-phoi start [--json]`: one fast, network-free call for gate 1 when the UserPromptSubmit hook
+ * did not run: local health (sink from cache), fresh root task id, run dir created, scout brief path.
+ */
+function cmdStart(opts) {
+  const ctx = ctxOf(opts);
+  const reg = setupLib.registration(claudeDirOf(opts));
+  const info = core.startInfo(ctx);
+  const h = info.health;
+  if (!fs.existsSync(ctx.paths.hook)) h.problems.unshift(`chưa cài hook (${ctx.paths.hook}) — chạy \`dieu-phoi setup --dept <phòng>\`, log không được ghi`);
+  else if (!(reg.PostToolUse && reg.SubagentStop && reg.SessionStart)) h.problems.unshift('hook chưa đăng ký đủ trong settings.json — chạy lại `dieu-phoi setup`, log/trạng thái không được ghi');
+  if (!reg.UserPromptSubmit) h.problems.push('thiếu hook UserPromptSubmit — chạy lại `dieu-phoi setup` để bỏ được lệnh này');
+  if (!reg.permissions || reg.legacy_permissions) h.problems.push(`thiếu quyền ghi cho ${reg.permission_entries.dir} — chạy lại \`dieu-phoi setup\` (agent nền có thể không ghi được report)`);
+  h.ok = !h.problems.length;
+  if (opts.json) return { code: 0, out: JSON.stringify(info, null, 2) };
+  const out = [
+    `root_task_id: ${info.id}`,
+    `run_dir: ${info.run_dir}/ (đã tạo)`,
+    `step_ids: ${info.step_ids.join(' ')}`,
+    `health: ${core.healthLine(h)}`,
+    `scout_brief: ${info.scout_brief || '(không thấy — dùng references/brief-template.md mục E)'}`,
+  ];
+  return { code: 0, out: out.join('\n') };
+}
+
 // ------------------------------------------------------------------ hook / sync
 
 function cmdHook(opts) {
@@ -820,6 +867,6 @@ function cmdPlanTable(opts) {
 }
 
 module.exports = {
-  cmdSetup, cmdUninstall, cmdDoctor, cmdHook, cmdSync, cmdVerdict, cmdSteer, cmdStats, cmdRetro, cmdChoose, cmdCtx, cmdState, measureOrch,
+  cmdSetup, cmdUninstall, cmdDoctor, cmdStart, checkSinkLive, cmdHook, cmdSync, cmdVerdict, cmdSteer, cmdStats, cmdRetro, cmdChoose, cmdCtx, cmdState, measureOrch,
   cmdPlanTable, cmdNewId, requireTaskId, buildPlanTable, recordApprovedPlan, planTaskIdProblems, criticalPath, resolveAgentId, AGENT_OUTCOMES, USER_OUTCOMES, VERIFY,
 };

package/lib/setup.cjs

@@ -57,7 +57,7 @@ function stripOurHooks(settings) {
   return removed;
 }
 
-/** True when settings already hold exactly our two entries with this command. */
+/** True when settings already hold exactly our four entries with this command. */
 function alreadyRegistered(settings, cmd) {
   const hooks = settings && settings.hooks;
   if (!hooks || typeof hooks !== 'object') return false;
@@ -72,10 +72,11 @@ function alreadyRegistered(settings, cmd) {
         if (event === 'PostToolUse' && g.matcher === 'Agent') good++;
         else if (event === 'SubagentStop') good++;
         else if (event === 'SessionStart' && g.matcher === 'compact') good++;
+        else if (event === 'UserPromptSubmit' && !g.matcher) good++;
       }
     }
   }
-  return ours === 3 && good === 3;
+  return ours === 4 && good === 4;
 }
 
 function addOurHooks(settings, hookPath) {
@@ -89,6 +90,9 @@ function addOurHooks(settings, hookPath) {
   // after /compact or auto-compact: re-inject the orchestration state rebuilt from the log
   if (!Array.isArray(h.SessionStart)) h.SessionStart = [];
   h.SessionStart.push({ matcher: 'compact', hooks: [{ type: 'command', command: cmd, timeout: 10 }] });
+  // on a dieu-phoi prompt: pre-create the run dir + id so the first tool call can be the scout (no shell)
+  if (!Array.isArray(h.UserPromptSubmit)) h.UserPromptSubmit = [];
+  h.UserPromptSubmit.push({ hooks: [{ type: 'command', command: cmd, timeout: 5 }] });
 }
 
 // ------------------------------------------------------------------ run-dir permissions
@@ -340,7 +344,7 @@ function registration(claudeDir) {
   const perms = permissionEntries(runsDir());
   const legacy = permissionEntries(legacyRunsDirOf(claudeDir));
   const out = {
-    file, PostToolUse: false, SubagentStop: false, SessionStart: false, commands: [], permissions: false, permission_entries: perms,
+    file, PostToolUse: false, SubagentStop: false, SessionStart: false, UserPromptSubmit: false, commands: [], permissions: false, permission_entries: perms,
     runs_dir: perms.dir, runs_dir_exists: fs.existsSync(perms.dir), legacy_permissions: false,
   };
   let obj;
@@ -350,7 +354,7 @@ function registration(claudeDir) {
   out.legacy_permissions = legacy.allow.some((r) => Array.isArray(lp.allow) && lp.allow.includes(r))
     || (Array.isArray(lp.additionalDirectories) && lp.additionalDirectories.includes(legacy.dir));
   const hooks = obj.hooks || {};
-  for (const ev of ['PostToolUse', 'SubagentStop', 'SessionStart']) {
+  for (const ev of ['PostToolUse', 'SubagentStop', 'SessionStart', 'UserPromptSubmit']) {
     for (const g of Array.isArray(hooks[ev]) ? hooks[ev] : []) {
       for (const h of (g && Array.isArray(g.hooks) ? g.hooks : [])) {
         if (!isOurs(h)) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kienntpixon/dieu-phoi",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Hook + CLI ghi log subagent của Claude Code và chọn model/effort theo chi phí + thời gian tới lúc nghiệm thu.",
   "license": "MIT",
   "author": "kiennt <kiennt@pixon.games>",