@kienntpixon/dieu-phoi 0.5.2 → 0.6.0

package/hook.cjs

@@ -9,7 +9,8 @@
  * handoff watchdog), `--gate` (PreToolUse(Agent), gen-2 helper rules) and `--gate-release`. It must stay
  * self-contained: Node built-ins only, no requires of other package files.
  *
- * Hook rules: stdout only for the JSON of SessionStart(compact) / UserPromptSubmit, always exit 0,
+ * Hook rules: stdout only for the JSON of SessionStart(compact) / UserPromptSubmit / a PostToolUse(Agent) warning
+ * (core 0.5.3: bad dp tag, handoff chain), always exit 0,
  * no network.
  * Errors go to <home>/hook-errors.log.
  *
@@ -25,7 +26,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.5.2';
+const CORE_VERSION = '0.6.0';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -91,6 +92,42 @@ function writeFileAtomic(file, content, mode) {
   renameWithRetry(tmp, file);
 }
 
+/**
+ * Short advisory lock (O_EXCL file) for read-modify-write of shared state while parallel sessions run hooks.
+ * Returns a release function, or null when the lock was not obtained within `timeoutMs` (callers choose whether
+ * to go on unlocked or give up). A lock older than `staleMs` (holder died) is taken over. Release only removes
+ * the file if it is still ours, so a taken-over lock is never deleted by its old holder.
+ */
+function acquireFileLock(file, o) {
+  const timeoutMs = (o && o.timeoutMs) || 5000;
+  const staleMs = (o && o.staleMs) || 30000;
+  const token = `${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  const deadline = Date.now() + timeoutMs;
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); } catch (_) { /* surfaces below */ }
+  for (let spin = 0; ; spin++) {
+    try {
+      fs.writeFileSync(file, token, { flag: 'wx' });
+      return () => {
+        try { if (fs.readFileSync(file, 'utf8') === token) fs.unlinkSync(file); } catch (_) { /* gone */ }
+      };
+    } catch (e) {
+      if (e.code !== 'EEXIST' && e.code !== 'EPERM' && e.code !== 'EACCES' && e.code !== 'EBUSY') return null;
+    }
+    try {
+      if (Date.now() - fs.statSync(file).mtimeMs > staleMs) { fs.unlinkSync(file); continue; }
+    } catch (_) { /* vanished: retry at once */ }
+    if (Date.now() >= deadline) return null;
+    sleepSync(spin < 20 ? 2 : 10);
+  }
+}
+
+/** Run fn under the lock; `fn` also runs (unlocked) when the lock times out unless o.required. Returns {locked, value}. */
+function withFileLock(file, o, fn) {
+  const release = acquireFileLock(file, o);
+  if (!release && o && o.required) return { locked: false, skipped: true, value: undefined };
+  try { return { locked: !!release, skipped: false, value: fn() }; } finally { if (release) release(); }
+}
+
 // ------------------------------------------------------------------ paths / config
 
 /** Claude config dir: CLAUDE_CONFIG_DIR, else ~/.claude. */
@@ -126,6 +163,7 @@ function pathsFor(home) {
     events: path.join(data, 'events.jsonl'),
     segments: path.join(data, 'segments'),
     plans: path.join(data, 'plans'),
+    suggest: path.join(data, 'suggest'),
     skippedInternal: path.join(data, 'skipped-internal.json'),
     syncOffset: path.join(data, 'sync-offset.json'),
     syncSpawn: path.join(data, 'sync-spawn.json'),
@@ -133,6 +171,8 @@ function pathsFor(home) {
     sinkCheck: path.join(data, 'sink-check.json'),
     syncRejected: path.join(data, 'sync-rejected.jsonl'),
     lock: path.join(data, 'sync.lock'),
+    eventsLock: path.join(data, 'events.lock'),
+    ctxWarnLock: path.join(data, 'ctx-warn.lock'),
     config: path.join(home, 'config.json'),
     errlog: path.join(home, 'hook-errors.log'),
   };
@@ -263,6 +303,87 @@ function taskIdError(id) {
   return `task_id "${id}" không hợp lệ: cần đúng 8 ký tự a-z0-9 (vd. ${newTaskId()}) — lấy id bằng \`dieu-phoi new-id\``;
 }
 
+// ------------------------------------------------------------------ tag check (core 0.5.3, retro 2026-10-22)
+//
+// 76 dp-exec ($407, 25% of 10-19..21 cost) lost their task_id because the brief put the id in the type slot
+// (`[dp:<id>|…]`, no `task=`). parseTag stays strict (the gen-2 gate relies on it); resolveTag diagnoses the tag,
+// flags it (`tag_issue`) and recovers the task_id only when the guess is safe.
+
+const DEFAULT_EXTRA_TYPES = ['art-gen'];
+
+/** Fixed task types + the profile's extra_task_types (art-gen when no profile is readable). */
+function knownTaskTypes(ctx) {
+  const out = TASK_TYPES.concat(DEFAULT_EXTRA_TYPES);
+  const sd = ctx && ctx.config && ctx.config.skill_dir;
+  if (sd) {
+    const prof = readJsonFile(path.join(sd, 'profile', 'profile.json'), null);
+    const extra = prof && Array.isArray(prof.extra_task_types) ? prof.extra_task_types : [];
+    for (const t of extra) if (typeof t === 'string' && !out.includes(t)) out.push(t);
+  }
+  return out;
+}
+
+/**
+ * parseTag + diagnosis. null when the first line has no `[dp:` tag at all. Otherwise a tag (never dropped), plus:
+ * - `tag_issue`: `type-is-id` (an 8-char [a-z0-9] id in the type slot), `bad-type` (type not a known task type),
+ *   `missing-task` (no `task=`), joined with `+`;
+ * - `task_id_inferred: true` + `task_id` = the type-slot token, only when `task=` is missing, the token matches the
+ *   task_id format, is not a known type, and either holds a digit or the prompt names it in a run-file path /
+ *   `task=` (`dp-out-<id>`, `handoff-<id>`) — the same test that tells `type-is-id` from `bad-type` (an 8-letter label
+ *   such as "planning" stays a label). Then task_type = another tag part that is a known type, else `untagged`.
+ */
+function resolveTag(text, known) {
+  if (typeof text !== 'string') return null;
+  const body = text.replace(/^/, '');
+  const first = body.split(/\r?\n/, 1)[0].trim();
+  const m = /^\[dp:([^\]]*)\]/.exec(first);
+  if (!m) return null;
+  const types = Array.isArray(known) && known.length ? known : TASK_TYPES.concat(DEFAULT_EXTRA_TYPES);
+  const parts = m[1].split('|').map((s) => s.trim());
+  const head = (parts[0] || '').toLowerCase();
+  const rest = parts.slice(1);
+  let tag = parseTag(body);
+  // type slot unusable for parseTag (e.g. an id starting with a digit): parse the other parts on their own
+  if (!tag) tag = parseTag(`[dp:untagged|${rest.join('|')}]`);
+  const issues = [];
+  const altType = rest.map((p) => p.toLowerCase()).find((p) => types.includes(p)) || null;
+  // an id, not a label: id format, not a known type, and a digit or a run-file / task= mention ("planning" is a label)
+  const named = new RegExp(`(?:dp-out-|handoff-|task=)${escRe(head)}(?![a-z0-9])`).test(body.slice(first.length));
+  const idLike = TASK_ID_RE.test(head) && !types.includes(head) && (/\d/.test(head) || named);
+  if (idLike) issues.push('type-is-id');
+  else if (!types.includes(head)) {
+    issues.push('bad-type');
+    tag.bad_type = parts[0]; // the offending token (task_type may be replaced by a valid altType below)
+  }
+  if (!tag.task_id) {
+    issues.push('missing-task');
+    if (idLike) {
+      tag.task_id = head;
+      tag.task_id_inferred = true;
+    }
+  }
+  if (idLike || tag.task_type === 'untagged') tag.task_type = altType || 'untagged';
+  else if (!types.includes(tag.task_type) && altType) tag.task_type = altType;
+  if (issues.length) tag.tag_issue = issues.join('+');
+  return tag;
+}
+
+/** One Vietnamese line for the orchestrator about a flagged tag (null when the tag is fine). */
+function tagIssueMessage(tag, known) {
+  if (!tag || !tag.tag_issue) return null;
+  const what = [];
+  const codes = tag.tag_issue.split('+');
+  if (codes.includes('no-tag')) what.push('agent dp-* được giao mà không có thẻ `[dp:...]` ở dòng đầu prompt');
+  if (codes.includes('type-is-id')) what.push('ô đầu của thẻ là một task id, không phải loại task');
+  if (codes.includes('bad-type')) what.push(`loại "${tag.bad_type || tag.task_type}" không nằm trong danh sách loại hợp lệ`);
+  if (codes.includes('missing-task')) what.push('thiếu `task=<id>`');
+  const got = tag.task_id_inferred
+    ? ` Hook đã suy task_id=${tag.task_id} từ ô loại (log ghi \`task_id_inferred\`), loại ghi là "${tag.task_type}".`
+    : (tag.task_id ? '' : ' Lượt này KHÔNG có task_id: không vào stats/choose/retro.');
+  const types = (Array.isArray(known) && known.length ? known : TASK_TYPES.concat(DEFAULT_EXTRA_TYPES)).join(', ');
+  return `dieu-phoi: thẻ của agent vừa giao sai (tag_issue=${tag.tag_issue}): ${what.join('; ')}.${got} Lần giao sau dùng đúng \`[dp:<task_type>|s<n>|<urgency>|try<n>|task=<id>|role=<role>]\`, task_type là một trong: ${types}; id lấy bằng \`dieu-phoi new-id\`.`;
+}
+
 // ------------------------------------------------------------------ models / pricing
 
 function normalizeModel(m) {
@@ -387,10 +508,13 @@ function firstPromptText(lines) {
   return null;
 }
 
-/** Tag from the first user message of the transcript (the original prompt). */
-function tagFromTranscript(lines) {
+/**
+ * Tag from the first user message of the transcript (the original prompt). Core 0.5.3: resolveTag, so a tag with the
+ * id in the type slot still yields its task_id (complete events, watchdog handoff file name, inline results).
+ */
+function tagFromTranscript(lines, known) {
   const text = firstPromptText(lines);
-  return text === null ? null : parseTag(text);
+  return text === null ? null : resolveTag(text, known);
 }
 
 /**
@@ -763,8 +887,17 @@ function findSessionTranscript(claudeDir, sessionId) {
  * event — readers skip the fragment as one unparsable line. Withdrawing a task = `dieu-phoi discard`, never an
  * edit of this file.
  */
+const EVENTS_LOCK_WAIT_MS = 1500;
+
 function appendEvent(ctx, ev) {
   fs.mkdirSync(ctx.paths.data, { recursive: true });
+  // Core 0.5.4: appends take events.lock so `prune --yes` (which rewrites the file under the same lock) can never
+  // lose a line that lands between its read and its rename. Lock wait is capped well under the shortest hook timeout
+  // (UserPromptSubmit 5 s) so a stuck lock cannot get the hook killed mid-write; on timeout append anyway (never drop telemetry).
+  withFileLock(ctx.paths.eventsLock, { timeoutMs: EVENTS_LOCK_WAIT_MS, staleMs: 30000 }, () => appendEventRaw(ctx, ev));
+}
+
+function appendEventRaw(ctx, ev) {
   const fd = fs.openSync(ctx.paths.events, 'a+');
   try {
     let lead = '';
@@ -1356,13 +1489,29 @@ function stepIds(root, n) {
   return Array.from(ids);
 }
 
-function startInfo(ctx) {
+/**
+ * core 0.6.0 (s3): project_knowledge of the repo at `cwd` — null outside a repo or without a store. Refreshes that repo
+ * only (one git diff-tree on a HEAD/index cache miss, never git status); related repos report their cache.
+ */
+function startKnowledgeOf(cwd) {
+  if (!cwd || typeof cwd !== 'string') return null;
+  try { return startKnowledge(cwd); } catch (_) { return null; }
+}
+
+function startInfo(ctx, cwd) {
   const run = startRun();
   const health = quickHealth(ctx, run.runs);
-  return {
+  const info = {
     id: run.id, run_dir: run.run_dir, step_ids: stepIds(run.id, START_STEP_IDS), health, scout_brief: scoutBriefPath(ctx),
     orch_lessons: orchLessons(ctx),
   };
+  const k = startKnowledgeOf(cwd);
+  if (k) info.knowledge = k;
+  return info;
+}
+
+function knowledgeLines(info) {
+  return info && info.knowledge && Array.isArray(info.knowledge.lines) ? info.knowledge.lines : [];
 }
 
 function orchLessonLines(info) {
@@ -1379,6 +1528,7 @@ function formatStartBlock(info) {
     `health: ${healthLine(info.health)}`,
     `scout_brief: ${info.scout_brief || '(không thấy — dùng references/brief-template.md mục E)'}`,
     ...orchLessonLines(info),
+    ...knowledgeLines(info),
     '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');
 }
@@ -1386,7 +1536,7 @@ function formatStartBlock(info) {
 /** 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);
+  const info = startInfo(ctx, typeof p.cwd === 'string' ? p.cwd : null);
   return {
     stdout: JSON.stringify({
       hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: formatStartBlock(info) },
@@ -1409,11 +1559,704 @@ function extractAgentId(tr) {
   return m ? m[1] : null;
 }
 
+// ------------------------------------------------------------------ core 0.5.3: choose's tier per task (retro 2026-10-22)
+//
+// `choose --task <id>` and `plan-table --approve` leave data/suggest/<task>-<role>.json; the next dispatch of that
+// task + role copies it as `suggested_tier` (choose's own pick, before a user override) and `choose_tier` (what
+// choose answered), next to the tier actually dispatched. Older than SUGGEST_MAX_AGE_MS -> ignored.
+
+const SUGGEST_MAX_AGE_MS = 14 * 24 * 3600 * 1000;
+
+function suggestFile(ctx, taskId, role) {
+  return path.join(ctx.paths.suggest, `${safeName(taskId)}-${safeName(role || 'exec')}.json`);
+}
+
+/**
+ * rec: { task_id, role?, suggested_tier, choose_tier?, source: 'choose'|'plan', keep_suggested? }. keep_suggested:
+ * a `choose --approved` answer carries no Thompson pick, so an earlier record's suggested_tier (from the plan table)
+ * is kept. Best effort: returns the written record or null.
+ */
+function recordSuggestion(ctx, rec) {
+  if (!rec || !isValidTaskId(rec.task_id) || typeof rec.suggested_tier !== 'string') return null;
+  const role = rec.role || 'exec';
+  const file = suggestFile(ctx, rec.task_id, role);
+  const prev = rec.keep_suggested ? readSuggestion(ctx, rec.task_id, role) : null;
+  const out = {
+    task_id: rec.task_id,
+    role,
+    suggested_tier: prev && prev.suggested_tier ? prev.suggested_tier : rec.suggested_tier,
+    choose_tier: rec.choose_tier || rec.suggested_tier,
+    source: prev && prev.suggested_tier ? prev.source : (rec.source || 'choose'),
+    ts: nowIso(),
+  };
+  try {
+    fs.mkdirSync(ctx.paths.suggest, { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(out)}\n`);
+    pruneSuggest(ctx);
+  } catch (e) {
+    logError(ctx.home, e, 'suggest');
+    return null;
+  }
+  return out;
+}
+
+function readSuggestion(ctx, taskId, role) {
+  if (!isValidTaskId(taskId)) return null;
+  const r = readJsonFile(suggestFile(ctx, taskId, role), null);
+  if (!r || typeof r !== 'object' || typeof r.suggested_tier !== 'string') return null;
+  const t = Date.parse(r.ts);
+  if (!(Date.now() - t <= SUGGEST_MAX_AGE_MS)) return null;
+  return r;
+}
+
+function pruneSuggest(ctx) {
+  let names = [];
+  try { names = fs.readdirSync(ctx.paths.suggest); } catch (_) { return; }
+  const now = Date.now();
+  for (const n of names) {
+    const f = path.join(ctx.paths.suggest, n);
+    try { if (now - fs.statSync(f).mtimeMs > 2 * SUGGEST_MAX_AGE_MS) fs.unlinkSync(f); } catch (_) { /* gone */ }
+  }
+}
+
+// ------------------------------------------------------------------ core 0.5.3: handoff chains (retro 2026-10-22)
+//
+// 15/63 feature-impl tasks handed off >= 2 times (19% of feature-impl cost); one chain ran 10 handoffs ($70) and
+// failed. From the 3rd handoff of a task the orchestrator is told to stop continuing and have a planner re-split.
+
+const HANDOFF_CHAIN_WARN = 3;
+
+/** Number of agents whose `complete` event has handoff:true for this task (substring scan of events.jsonl). */
+function countTaskHandoffs(ctx, taskId) {
+  if (!taskId) return 0;
+  let txt;
+  try { txt = fs.readFileSync(ctx.paths.events, 'utf8'); } catch (_) { return 0; }
+  const needle = `"task_id":${JSON.stringify(taskId)}`;
+  const agents = new Set();
+  let i = txt.indexOf(needle);
+  while (i >= 0) {
+    const start = txt.lastIndexOf('\n', i) + 1;
+    const end = txt.indexOf('\n', i);
+    const line = txt.slice(start, end < 0 ? undefined : end);
+    if (line.includes('"kind":"complete"') && line.includes('"handoff":true')) {
+      const m = /"agent_id":("(?:[^"\\]|\\.)*")/.exec(line);
+      agents.add(m ? m[1] : `@${start}`);
+    }
+    i = end < 0 ? -1 : txt.indexOf(needle, end);
+  }
+  return agents.size;
+}
+
+function handoffChainMessage(taskId, n) {
+  return `dieu-phoi: task ${taskId} đã handoff ${n} lần (trần ${HANDOFF_CHAIN_WARN}). Đừng nối tiếp thêm: nếu agent vừa giao là agent tiếp nối, cân nhắc dừng nó và giao planner (dp-scout) đọc handoff-${taskId}.md rồi chia phần còn lại thành bước mới (task_id mới từ \`dieu-phoi new-id\`).`;
+}
+
+// ------------------------------------------------------------------ core 0.6.0 (unreleased): project identity
+//
+// A project (= one git repo, however many worktrees/clones) gets a stable key so every session and worktree can
+// share one knowledge store (~/.dieu-phoi/projects/<name>-<sha8(key)>/). Everything here is plain file reads —
+// never spawns git — because it runs in hooks on the hot path.
+//   key = "remote:<host>/<path>" from remote.origin.url (credentials, scheme, .git stripped; host lower-cased)
+//       | "git:<realpath of git-common-dir>"  for a repo without remote (worktrees share the common dir)
+// A repo that later gains a remote changes key: `dieu-phoi knowledge rekey` records the new key as an alias of the
+// existing store dir (<projects>/aliases.json); the dir itself is never renamed.
+
+/** Knowledge store root: ~/.dieu-phoi/projects (override: DIEU_PHOI_PROJECTS_DIR, absolute). */
+function projectsDir() {
+  if (process.env.DIEU_PHOI_PROJECTS_DIR) return path.resolve(process.env.DIEU_PHOI_PROJECTS_DIR);
+  return path.join(os.homedir(), '.dieu-phoi', 'projects');
+}
+
+function realDir(p) {
+  try { return fs.realpathSync.native(p); } catch (_) { /* fall through */ }
+  try { return fs.realpathSync(p); } catch (_) { return path.resolve(p); }
+}
+
+function toSlash(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+/** Comparable form of a local path: forward slashes, no trailing slash, lower-case on Windows. */
+function pathId(p) {
+  const s = toSlash(p).replace(/\/+$/, '');
+  return process.platform === 'win32' ? s.toLowerCase() : s;
+}
+
+function readTextFile(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
+}
+
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch (_) { return false; }
+}
+
+function gitDirsOf(root, gitDir) {
+  const cd = readTextFile(path.join(gitDir, 'commondir'));
+  const commonDir = cd && cd.trim() ? path.resolve(gitDir, cd.trim()) : gitDir;
+  return { root, gitDir, commonDir };
+}
+
+/**
+ * Walk up from `start` to the nearest repo. `.git` may be a directory (main checkout) or a file `gitdir: <path>`
+ * (linked worktree or submodule); a linked worktree's `commondir` file points at the shared git dir.
+ * Returns { root, gitDir, commonDir } (root null for a bare repo / a git dir passed directly) or null.
+ */
+function findGit(start) {
+  let dir;
+  try {
+    dir = path.resolve(start);
+    if (!fs.statSync(dir).isDirectory()) dir = path.dirname(dir);
+  } catch (_) { return null; }
+  if (fs.existsSync(path.join(dir, 'HEAD')) && isDir(path.join(dir, 'objects')) && isDir(path.join(dir, 'refs'))) {
+    return gitDirsOf(null, dir); // bare repo or a .git dir itself
+  }
+  for (let i = 0; i < 64; i++) {
+    const dotgit = path.join(dir, '.git');
+    let st = null;
+    try { st = fs.statSync(dotgit); } catch (_) { /* none here */ }
+    if (st && st.isDirectory()) return gitDirsOf(dir, dotgit);
+    if (st && st.isFile()) {
+      const m = /^gitdir:\s*(.+?)\s*$/m.exec(readTextFile(dotgit) || '');
+      if (m) return gitDirsOf(dir, path.resolve(dir, m[1]));
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+  return null;
+}
+
+function unquoteGitValue(v) {
+  let s = String(v).trim();
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') s = s.slice(1, -1).replace(/\\(.)/g, '$1');
+  return s.trim();
+}
+
+/** remote.origin.url from the text of a git config (INI subset: [remote "origin"] url = ...). */
+function originUrlFromConfig(text) {
+  let inOrigin = false;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t[0] === '#' || t[0] === ';') continue;
+    const h = /^\[\s*([A-Za-z0-9.-]+)(?:\s+"((?:[^"\\]|\\.)*)")?\s*\](.*)$/.exec(t);
+    if (h) {
+      inOrigin = h[1].toLowerCase() === 'remote' && h[2] === 'origin';
+      const rest = h[3].trim();
+      const u0 = inOrigin && rest ? /^url\s*=\s*(.*)$/i.exec(rest) : null;
+      if (u0) return unquoteGitValue(u0[1]);
+      continue;
+    }
+    if (!inOrigin) continue;
+    const u = /^url\s*=\s*(.*)$/i.exec(t);
+    if (u) return unquoteGitValue(u[1]);
+  }
+  return null;
+}
+
+/**
+ * Canonical form of a remote URL: `host/path` for ssh/https/git/scp-like URLs (credentials, scheme, ssh port, query,
+ * trailing `.git` and slashes dropped; host lower-cased; a non-default http(s) port is kept), `file:<path>` for local
+ * remotes. ssh and https clones of the same repo therefore share a key. Null for an empty value.
+ */
+function normalizeRemoteUrl(raw) {
+  const s = String(raw == null ? '' : raw).trim();
+  if (!s) return null;
+  let host = null;
+  let p = null;
+  const url = /^([a-z][a-z0-9+.-]*):\/\/(.*)$/i.exec(s);
+  if (url && url[1].toLowerCase() !== 'file') {
+    const scheme = url[1].toLowerCase();
+    const rest = url[2];
+    const slash = rest.indexOf('/');
+    const auth = slash < 0 ? rest : rest.slice(0, slash);
+    p = slash < 0 ? '' : rest.slice(slash + 1);
+    const hostport = auth.slice(auth.lastIndexOf('@') + 1);
+    const hp = /^(\[[^\]]+\]|[^:]*)(?::(\d*))?$/.exec(hostport) || [null, hostport, ''];
+    host = hp[1].toLowerCase();
+    const port = hp[2];
+    if (port && /^https?$/.test(scheme) && !(scheme === 'http' && port === '80') && !(scheme === 'https' && port === '443')) {
+      host += `:${port}`;
+    }
+  } else {
+    const scp = !url && !/^[A-Za-z]:[\\/]/.test(s) ? /^(?:[^/\\:@]*@)?([^/\\:]+):(?!\/\/)(.*)$/.exec(s) : null;
+    if (scp) {
+      host = scp[1].toLowerCase();
+      p = scp[2];
+    } else {
+      let local = url ? url[2] : s; // file://...
+      if (url) local = local.replace(/^\/(?=[A-Za-z]:)/, '');
+      local = toSlash(local).replace(/[?#].*$/, '').replace(/\/+$/, '').replace(/\.git$/i, '');
+      return `file:${pathId(local)}`;
+    }
+  }
+  p = toSlash(p).replace(/[?#].*$/, '').replace(/^\/+/, '').replace(/\/+$/, '').replace(/\.git$/i, '').replace(/\/+$/, '');
+  if (!host) return null;
+  return p ? `${host}/${p}` : host;
+}
+
+function safeName(n) {
+  const s = String(n || '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 40);
+  return s || 'repo';
+}
+
+function gitFallbackName(commonDir) {
+  const base = path.basename(commonDir);
+  return safeName(base === '.git' ? path.basename(path.dirname(commonDir)) : base.replace(/\.git$/i, ''));
+}
+
+function keyDirName(key, name) {
+  return `${name}-${sha8(key)}`;
+}
+
+/** A store dir name as this module makes them (also guards aliases.json / --from against traversal). */
+function isStoreDirName(n) {
+  return typeof n === 'string' && /^[A-Za-z0-9._-]+$/.test(n) && !/^\.+$/.test(n);
+}
+
+function aliasesFile() {
+  return path.join(projectsDir(), 'aliases.json');
+}
+
+function loadAliases() {
+  const a = readJsonFile(aliasesFile(), {});
+  return a && typeof a === 'object' && !Array.isArray(a) ? a : {};
+}
+
+/**
+ * Project identity of any path inside a repo (main checkout, linked worktree, clone) — file reads only.
+ * `dir` is the store dir (it need not exist yet); `alias` is true when the dir was reached through aliases.json.
+ * With `fallback`, also reports `rekey_from`: the dir name of the remote-less (git-common-dir) key when that store
+ * exists but the remote key's does not (the repo gained a remote since). Null when `start` is not in a repo.
+ */
+function resolveProject(start, opts) {
+  const g = findGit(start);
+  if (!g) return null;
+  const o = opts || {};
+  const raw = originUrlFromConfig(readTextFile(path.join(g.commonDir, 'config')));
+  const remote = raw ? normalizeRemoteUrl(raw) : null;
+  const gitKey = `git:${pathId(realDir(g.commonDir))}`;
+  const gitName = gitFallbackName(g.commonDir);
+  const key = remote ? `remote:${remote}` : gitKey;
+  const name = remote ? safeName(remote.split('/').pop() || remote) : gitName;
+  const own = keyDirName(key, name);
+  const store = projectsDir();
+  let dirName = own;
+  let alias = false;
+  if (!isDir(path.join(store, own))) {
+    const a = loadAliases()[key];
+    if (isStoreDirName(a) && isDir(path.join(store, a))) { dirName = a; alias = true; }
+  }
+  const out = {
+    root: g.root ? toSlash(g.root) : null,
+    git_dir: toSlash(g.gitDir),
+    common_dir: toSlash(g.commonDir),
+    key,
+    kind: remote ? 'remote' : 'git',
+    remote,
+    name,
+    dir_name: dirName,
+    dir: toSlash(path.join(store, dirName)),
+    exists: isDir(path.join(store, dirName)),
+    alias,
+  };
+  if (o.fallback && remote && !out.exists) {
+    const legacy = keyDirName(gitKey, gitName);
+    if (isDir(path.join(store, legacy))) out.rekey_from = legacy;
+  }
+  return out;
+}
+
+const SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/i;
+const PER_WORKTREE_REF_RE = /^refs\/(bisect|worktree|rewritten)\//;
+
+function resolveRef(g, ref, depth) {
+  if (depth > 5) return null;
+  const base = PER_WORKTREE_REF_RE.test(ref) ? g.gitDir : g.commonDir;
+  const loose = readTextFile(path.join(base, ref));
+  if (loose != null) {
+    const v = loose.trim();
+    if (SHA_RE.test(v)) return v.toLowerCase();
+    const sym = /^ref:\s*(\S+)/.exec(v);
+    return sym ? resolveRef(g, sym[1], depth + 1) : null;
+  }
+  const packed = readTextFile(path.join(g.commonDir, 'packed-refs'));
+  if (packed) {
+    const needle = ` ${ref}`;
+    for (const line of packed.split(/\r?\n/)) {
+      if (line.endsWith(needle) && /^[0-9a-f]{40}/i.test(line)) return line.slice(0, line.length - needle.length).trim().toLowerCase();
+    }
+  }
+  return null;
+}
+
+/**
+ * HEAD of the repo around `start` (a path, or the object findGit returned) without spawning git, in < 1 ms:
+ * { branch, sha, detached } | { branch, sha: null, unborn: true } | { sha: null, unsupported: 'reftable' } | null.
+ * `unsupported` means the caller must fall back to `git rev-parse` (CLI only, never in a hook).
+ */
+function readHead(start) {
+  const g = start && typeof start === 'object' && start.gitDir ? start : findGit(start);
+  if (!g) return null;
+  const txt = readTextFile(path.join(g.gitDir, 'HEAD'));
+  if (txt == null) return null;
+  const t = txt.trim();
+  if (SHA_RE.test(t)) return { branch: null, sha: t.toLowerCase(), detached: true };
+  const m = /^ref:\s*(\S+)/.exec(t);
+  if (!m) return null;
+  const ref = m[1];
+  if (ref === 'refs/heads/.invalid' || isDir(path.join(g.commonDir, 'reftable'))) {
+    return { branch: null, sha: null, detached: false, unsupported: 'reftable' };
+  }
+  const branch = ref.replace(/^refs\/heads\//, '');
+  const sha = resolveRef(g, ref, 0);
+  return sha ? { branch, sha, detached: false } : { branch, sha: null, detached: false, unborn: true };
+}
+
+// ------------------------------------------------------------------ core 0.6.0 (unreleased), s3: knowledge freshness
+//
+// A knowledge section is stale when a file matching its `paths` globs differs between the commit it was merged at
+// (`sha`) and the HEAD of the worktree asking. Used by the start block here and by `knowledge get/list/status`
+// (lib/knowledge.cjs). Lives in hook.cjs because the installed hook is a single file (builtins only). Rules, from
+// measurements on the pixon-fast-forward repos (contract r1-2 §2):
+//   - ONE git process per check, whatever the number of distinct section shas: `git diff-tree --stdin` reads one
+//     "<sha> <HEAD>" line per sha. Always `--no-renames` (rename detection: 12.8 s vs 77 ms on pff-dressmaker) and a
+//     pathspec = the union of the sections' globs.
+//   - The result is cached per (worktree HEAD, index.json mtime+size) in <store>/cache/freshness.json; HEAD is read
+//     from files (readHead), so an unchanged HEAD costs a stat and a small JSON read, no process.
+//   - A section sha missing from the object store (merged in another clone, branch deleted and gc'd) or abbreviated is
+//     "unknown", never fresh, never a crash. A sha on an unmerged branch that exists locally is diffed like any other
+//     commit: the net diff is what differs between the code the knowledge describes and the code checked out.
+//   - Uncommitted changes only with `--dirty` (CLI): `git --no-optional-locks status -uno --no-renames`, 2 s timeout,
+//     "chưa kiểm" when it runs out (pff-rotate-rings: 67 s cold). Hooks never run git status.
+//   - The start block refreshes the cwd repo only (one diff-tree on a cache miss); related repos show their cache.
+
+const FRESH_CACHE_MAX = 12; // HEADs remembered per store (worktrees of one repo share the store)
+const DIFF_TIMEOUT_MS = 10000;
+const HOOK_DIFF_TIMEOUT_MS = 1500;
+const DIRTY_TIMEOUT_MS = 2000;
+const PATHSPEC_MAX_CHARS = 6000; // beyond this: no pathspec (Windows command line limit), filter in JS only
+const STALE_FILES_KEEP = 50; // stale files kept per section (the count stays exact)
+const FULL_SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/i;
+
+/**
+ * Does repo-relative file `rel` match glob `g`? `**` spans directories (`a/**` and `**\/x`), `*`/`?` stay within one
+ * segment, a trailing `/` or a wildcard-free pattern naming a directory matches everything below it.
+ */
+function globMatch(g, rel) {
+  let p = toSlash(String(g).trim()).replace(/^\.\//, '').replace(/^\/+/, '');
+  const f = toSlash(rel).replace(/^\.\//, '').replace(/^\/+/, '');
+  if (!p) return false;
+  const ci = process.platform === 'win32';
+  const eq = (a, b) => (ci ? a.toLowerCase() === b.toLowerCase() : a === b);
+  if (!/[*?]/.test(p)) {
+    const d = p.replace(/\/+$/, '');
+    return eq(f, d) || eq(f.slice(0, d.length + 1), `${d}/`);
+  }
+  if (p.endsWith('/')) p += '**';
+  let re = '';
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    if (c === '*') {
+      if (p[i + 1] === '*') {
+        if (p[i + 2] === '/') { re += '(?:.*/)?'; i += 2; } else { re += '.*'; i += 1; }
+      } else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`, ci ? 'i' : '').test(f);
+}
+
+/**
+ * git pathspecs for a set of globs (a superset filter; the exact match is globMatch). Null = no pathspec (whole
+ * repo): a glob matching everything, one git would refuse (absolute, `..`), or a list too long for a command line.
+ */
+function pathspecOf(globs) {
+  const magic = process.platform === 'win32' ? ':(glob,icase)' : ':(glob)';
+  const out = new Set();
+  for (const g0 of globs) {
+    const g = toSlash(String(g0).trim()).replace(/^\.\//, '').replace(/^\/+/, '');
+    if (!g || /^[*/]+$/.test(g)) return null;
+    if (/^[A-Za-z]:/.test(g) || g.split('/').includes('..') || g.startsWith(':')) return null;
+    if (g.endsWith('/')) out.add(`${magic}${g}**`);
+    else if (!/[*?[]/.test(g)) { out.add(`${magic}${g}`); out.add(`${magic}${g}/**`); } else out.add(`${magic}${g}`);
+  }
+  const list = Array.from(out);
+  if (!list.length || list.join(' ').length > PATHSPEC_MAX_CHARS) return null;
+  return list;
+}
+
+/** One git process (read-only: --no-optional-locks), bounded by a timeout; we started it, we may kill it. */
+function runGit(cwd, args, input, timeoutMs) {
+  const t0 = Date.now();
+  const r = require('child_process').spawnSync('git', ['--no-optional-locks', '-c', 'core.quotepath=off', ...args], {
+    cwd, input, encoding: 'utf8', windowsHide: true, timeout: timeoutMs, maxBuffer: 256 * 1024 * 1024,
+  });
+  const ms = Date.now() - t0;
+  if (r.error && r.error.code === 'ETIMEDOUT') return { ok: false, timedOut: true, ms, error: `quá ${timeoutMs} ms` };
+  if (r.error) return { ok: false, ms, error: r.error.message };
+  if (r.status !== 0) return { ok: false, ms, error: (r.stderr || '').trim().split(/\r?\n/)[0] || `exit ${r.status}` };
+  return { ok: true, ms, stdout: r.stdout || '' };
+}
+
+/**
+ * Files changed between each sha and `head` (one `git diff-tree --stdin` for all of them). `--always` prints the
+ * header line even for an empty diff, so a sha without header is an object this repo does not have (diff-tree skips
+ * those silently, exit 0). Returns { bySha: Map<sha, files[]>, missing: Set<sha>, ms } or { error, timedOut, ms }.
+ */
+function diffShas(root, shas, head, globs, timeoutMs) {
+  const spec = pathspecOf(globs);
+  const base = ['diff-tree', '--stdin', '--always', '-r', '--name-only', '--no-renames', '-z'];
+  const input = shas.map((s) => `${s} ${head}\n`).join('');
+  let r = runGit(root, spec ? base.concat('--', spec) : base, input, timeoutMs);
+  if (!r.ok && !r.timedOut && spec) r = runGit(root, base, input, timeoutMs); // pathspec refused: filter in JS only
+  if (!r.ok) return { error: r.error, timedOut: !!r.timedOut, ms: r.ms };
+  const want = new Set(shas.map((s) => s.toLowerCase()));
+  const bySha = new Map();
+  let cur = null;
+  for (const tok of r.stdout.split('\0')) {
+    const t = tok.replace(/^\n+/, '');
+    if (!t) continue;
+    const low = t.toLowerCase();
+    if (want.has(low) && !bySha.has(low)) { cur = []; bySha.set(low, cur); continue; }
+    if (cur) cur.push(t);
+  }
+  const missing = new Set(Array.from(want).filter((s) => !bySha.has(s)));
+  return { bySha, missing, ms: r.ms };
+}
+
+/** Uncommitted tracked changes (`status -uno`, no index refresh write), bounded by a timeout. CLI only. */
+function dirtyFiles(root, globs, timeoutMs) {
+  const spec = pathspecOf(globs);
+  const base = ['status', '--porcelain=v1', '-z', '-uno', '--no-renames'];
+  const r = runGit(root, spec ? base.concat('--', spec) : base, undefined, timeoutMs || DIRTY_TIMEOUT_MS);
+  if (!r.ok) return { error: r.error, timedOut: !!r.timedOut, ms: r.ms };
+  const files = r.stdout.split('\0').filter((x) => x.length > 3).map((x) => x.slice(3));
+  return { files, ms: r.ms };
+}
+
+function indexStamp(dir) {
+  try {
+    const st = fs.statSync(path.join(dir, 'index.json'));
+    return { mtime: st.mtimeMs, size: st.size };
+  } catch (_) { return null; }
+}
+
+function freshnessCacheFile(dir) {
+  return path.join(dir, 'cache', 'freshness.json');
+}
+
+function readFreshCache(dir) {
+  try {
+    const c = JSON.parse(fs.readFileSync(freshnessCacheFile(dir), 'utf8'));
+    return c && Array.isArray(c.entries) ? c : { entries: [] };
+  } catch (_) { return { entries: [] }; }
+}
+
+function cachedFor(dir, head, stamp) {
+  if (!head || !stamp) return null;
+  return readFreshCache(dir).entries.find((e) => e.head === head && e.index_mtime === stamp.mtime && e.index_size === stamp.size) || null;
+}
+
+/** Best effort (tmp+rename, last writer wins); a store that vanished or is read-only only loses the cache. */
+function writeFreshCache(dir, entry) {
+  try {
+    const rest = readFreshCache(dir).entries.filter((e) => e.head !== entry.head);
+    writeFileAtomic(freshnessCacheFile(dir), `${JSON.stringify({ schema: 1, entries: [entry, ...rest].slice(0, FRESH_CACHE_MAX) })}\n`);
+  } catch (_) { /* cache only */ }
+}
+
+function freshCounts(sections) {
+  const c = { total: 0, fresh: 0, stale: 0, unknown: 0 };
+  for (const s of Object.values(sections)) { c.total++; c[s.state] = (c[s.state] || 0) + 1; }
+  return c;
+}
+
+/**
+ * Freshness of every section of a store, for the worktree at `root`.
+ *   o = { dir (store), idx (parsed index), root (worktree root), head (readHead result), stamp (indexStamp),
+ *         cache (default true), timeoutMs }
+ * Returns { head, branch, cached, ms_git, computed, sections: { id: { state: fresh|stale|unknown, files?, n_files?,
+ * why? } }, counts, error? }. Only a complete answer is cached (no git error, HEAD known).
+ */
+function computeFreshness(o) {
+  const idx = o.idx;
+  const head = o.head && o.head.sha ? o.head.sha.toLowerCase() : null;
+  const out = { head, branch: o.head ? o.head.branch || null : null, cached: false, ms_git: 0 };
+  const stamp = o.stamp || indexStamp(o.dir);
+  if (head && o.cache !== false) {
+    const hit = cachedFor(o.dir, head, stamp);
+    if (hit) return Object.assign(out, { cached: true, computed: hit.computed, sections: hit.sections, counts: freshCounts(hit.sections) });
+  }
+  const sections = {};
+  const pending = new Map(); // sha -> [section]
+  let why = null;
+  if (!head) why = o.head && o.head.unsupported ? `HEAD không đọc được từ file (${o.head.unsupported})` : 'không đọc được HEAD (repo chưa có commit?)';
+  else if (!o.root) why = 'repo không có thư mục làm việc (bare)';
+  for (const s of idx.sections) {
+    const sha = String(s.sha || '').toLowerCase();
+    if (why) sections[s.id] = { state: 'unknown', why };
+    else if (!sha || sha === 'none') sections[s.id] = { state: 'unknown', why: 'mục chưa có sha' };
+    else if (sha === head) sections[s.id] = { state: 'fresh' };
+    else if (!FULL_SHA_RE.test(sha)) sections[s.id] = { state: 'unknown', why: `sha rút gọn ${sha} — merge lại với head: đầy đủ` };
+    else { if (!pending.has(sha)) pending.set(sha, []); pending.get(sha).push(s); }
+  }
+  let error = null;
+  if (pending.size) {
+    const globs = [];
+    for (const list of pending.values()) for (const s of list) globs.push(...(s.paths || []));
+    const d = diffShas(o.root, Array.from(pending.keys()), head, globs, o.timeoutMs || DIFF_TIMEOUT_MS);
+    out.ms_git = d.ms || 0;
+    if (d.error) error = d.error;
+    for (const [sha, list] of pending) {
+      for (const s of list) {
+        if (d.error) { sections[s.id] = { state: 'unknown', why: `git diff-tree lỗi: ${d.error}` }; continue; }
+        if (d.missing.has(sha)) { sections[s.id] = { state: 'unknown', why: `commit ${sha.slice(0, 7)} không có trong repo này (clone/nhánh khác chưa fetch?)` }; continue; }
+        const files = d.bySha.get(sha).filter((f) => (s.paths || []).some((g) => globMatch(g, f)));
+        sections[s.id] = files.length ? { state: 'stale', files: files.slice(0, STALE_FILES_KEEP), n_files: files.length } : { state: 'fresh' };
+      }
+    }
+  }
+  Object.assign(out, { computed: new Date().toISOString(), sections, counts: freshCounts(sections) });
+  if (error) out.error = error;
+  if (head && !error && o.cache !== false && stamp) {
+    writeFreshCache(o.dir, { head, index_mtime: stamp.mtime, index_size: stamp.size, computed: out.computed, sections });
+  }
+  return out;
+}
+
+/** Adds `dirty` (uncommitted files matching each section) in place; returns { checked, why?, ms }. */
+function addDirty(fr, idx, root, timeoutMs) {
+  if (!root) return { checked: false, why: 'repo không có thư mục làm việc' };
+  const globs = [];
+  for (const s of idx.sections) globs.push(...(s.paths || []));
+  const d = dirtyFiles(root, globs, timeoutMs);
+  if (d.error) return { checked: false, why: d.timedOut ? `chưa kiểm (git status ${d.error})` : `git status lỗi: ${d.error}`, ms: d.ms };
+  for (const s of idx.sections) {
+    const files = d.files.filter((f) => (s.paths || []).some((g) => globMatch(g, f)));
+    if (files.length && fr.sections[s.id]) fr.sections[s.id].dirty = files.slice(0, STALE_FILES_KEEP);
+  }
+  return { checked: true, ms: d.ms, n: d.files.length };
+}
+
+function shortFileList(files, n) {
+  const k = n || 3;
+  const f = files || [];
+  return f.slice(0, k).join(', ') + (f.length > k ? ` (+${f.length - k})` : '');
+}
+
+/** "N mục, k stale (ids), u không xác định (ids)". */
+function knowledgeSummary(fr, n) {
+  const ids = (st) => Object.keys(fr.sections).filter((id) => fr.sections[id].state === st);
+  const stale = ids('stale');
+  const unk = ids('unknown');
+  const parts = [`${n} mục`, `${stale.length} stale${stale.length ? ` (${shortFileList(stale, 6)})` : ''}`];
+  if (unk.length) parts.push(`${unk.length} không xác định (${shortFileList(unk, 4)})`);
+  return parts.join(', ');
+}
+
+/** index.json of a store, tolerant (null when missing or unreadable). */
+function readStoreIndex(dir) {
+  try {
+    const idx = JSON.parse(fs.readFileSync(path.join(dir, 'index.json'), 'utf8').replace(/^/, ''));
+    if (!idx || typeof idx !== 'object' || Array.isArray(idx)) return null;
+    if (!Array.isArray(idx.sections)) idx.sections = [];
+    if (!Array.isArray(idx.related)) idx.related = [];
+    return idx;
+  } catch (_) { return null; }
+}
+
+/** Cache-only status of a related repo (no git process): "N mục, k stale (cache)" or why it is unchecked. */
+function relatedStatus(r) {
+  const rp = typeof r.path === 'string' && r.path ? nativePath(r.path) : null;
+  const info = rp && isDir(rp) ? resolveProject(rp) : null;
+  if (!info || info.key !== r.key || !info.exists) return { name: r.name, rel: r.rel, text: 'chưa có kho / không thấy repo' };
+  const stamp = indexStamp(info.dir);
+  const idx = stamp ? readStoreIndex(info.dir) : null;
+  if (!idx) return { name: r.name, rel: r.rel, text: 'chưa có kho' };
+  const h = readHead(rp);
+  const hit = h && h.sha ? cachedFor(info.dir, h.sha.toLowerCase(), stamp) : null;
+  const n = idx.sections.length;
+  if (!hit) return { name: r.name, rel: r.rel, n, text: `${n} mục, độ tươi chưa kiểm (làm tươi khi get --follow / --repo)` };
+  return { name: r.name, rel: r.rel, n, counts: freshCounts(hit.sections), text: `${knowledgeSummary({ sections: hit.sections }, n)} (cache)` };
+}
+
+/**
+ * Knowledge lines for the start block of the repo at `cwd`; null outside a repo or when the repo has no store.
+ * Refreshes this repo only (at most one git diff-tree, on a cache miss, bounded by HOOK_DIFF_TIMEOUT_MS; never git
+ * status); related repos report their cache. Never throws.
+ */
+function startKnowledge(cwd, opts) {
+  const t0 = Date.now();
+  try {
+    if (!cwd) return null;
+    const info = resolveProject(cwd);
+    if (!info || !info.exists) return null;
+    const stamp = indexStamp(info.dir);
+    if (!stamp) return null;
+    const idx = readStoreIndex(info.dir);
+    if (!idx) return { dir: info.dir, lines: [`project_knowledge: ${info.dir} — index.json không đọc được (\`dieu-phoi knowledge list\` để xem lỗi)`] };
+    const fr = computeFreshness({ dir: info.dir, idx, root: info.root, head: readHead(cwd), stamp, timeoutMs: (opts && opts.timeoutMs) || HOOK_DIFF_TIMEOUT_MS });
+    const related = idx.related.map(relatedStatus);
+    const n = idx.sections.length;
+    const tail = fr.error ? ` — git lỗi (${fr.error}), chạy \`dieu-phoi knowledge status\`` : '';
+    const lines = [`project_knowledge: ${info.dir} — ${knowledgeSummary(fr, n)}${fr.head ? ` · HEAD ${fr.head.slice(0, 7)}` : ''}${tail} · \`dieu-phoi knowledge list\` rồi \`get <id>\``];
+    for (const r of related) lines.push(`  related: ${r.name} (${r.rel === 'parent' ? 'cha' : 'con'}) — ${r.text}`);
+    return {
+      dir: info.dir, name: info.name, key: info.key, head: fr.head, cached: fr.cached, ms: Date.now() - t0, ms_git: fr.ms_git,
+      counts: fr.counts, stale: Object.keys(fr.sections).filter((id) => fr.sections[id].state === 'stale'),
+      related: related.map((r) => ({ name: r.name, rel: r.rel, counts: r.counts || null, text: r.text })), lines,
+    };
+  } catch (e) {
+    return { lines: [], error: e.message, ms: Date.now() - t0 };
+  }
+}
+
+/** git-bash style `/d/x` -> `D:/x` on Windows (other platforms and other paths unchanged). */
+function nativePath(c) {
+  return process.platform === 'win32' ? String(c).replace(/^\/([a-zA-Z])(?=\/|$)/, '$1:') : String(c);
+}
+
+/** First existing dir named by a `repo: <path>` phrase of a brief (git-bash `/d/x` paths accepted). */
+function repoFromBrief(prompt) {
+  if (typeof prompt !== 'string' || !prompt) return null;
+  const head = prompt.slice(0, 6000);
+  const re = /(?:^|[\s(])repo\s*:\s*(`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|\S+)/gi;
+  let m;
+  while ((m = re.exec(head))) {
+    let c = m[1];
+    if (/^[`"']/.test(c)) c = c.slice(1, -1);
+    c = c.replace(/[.,;:)\]]+$/, '').trim();
+    if (!c || /[<>*?|]/.test(c)) continue;
+    c = nativePath(c);
+    if (isDir(c)) return path.resolve(c);
+  }
+  return null;
+}
+
+/**
+ * Project of a hook payload: the brief's `repo:` target wins (a session in the parent repo works on a child repo),
+ * else the payload cwd. Returns { project: <store dir name>, project_src: 'repo'|'cwd' }, or {} when neither is in a repo.
+ */
+function projectFields(p) {
+  try {
+    const ti = p && p.tool_input && typeof p.tool_input === 'object' ? p.tool_input : {};
+    const cands = [['repo', repoFromBrief(ti.prompt)], ['cwd', p && typeof p.cwd === 'string' && p.cwd ? p.cwd : null]];
+    for (const [src, dir] of cands) {
+      if (!dir) continue;
+      const r = resolveProject(dir);
+      if (r) return { project: r.dir_name, project_src: src };
+    }
+  } catch (_) { /* identity is best effort; never break the dispatch event */ }
+  return {};
+}
+
 function buildDispatch(p, ctx) {
   const ti = p.tool_input && typeof p.tool_input === 'object' ? p.tool_input : {};
   const tr = p.tool_response;
   const trObj = tr && typeof tr === 'object' && !Array.isArray(tr) ? tr : {};
-  const tag = parseTag(ti.prompt) || UNTAGGED;
+  const subagentType = typeof ti.subagent_type === 'string' && ti.subagent_type ? ti.subagent_type : 'general-purpose';
+  let tag = resolveTag(ti.prompt, knownTaskTypes(ctx));
+  if (!tag) tag = /^dp-/.test(subagentType) ? Object.assign({}, UNTAGGED, { tag_issue: 'no-tag' }) : UNTAGGED;
   const explicitEffort = typeof ti.effort === 'string' && ti.effort ? ti.effort : null;
   const parentEffort = p.effort && typeof p.effort === 'object' ? p.effort.level : null;
   // agent_id must never be empty (the sink keys on it): agentId -> tool_use_id -> random.
@@ -1432,6 +2275,8 @@ function buildDispatch(p, ctx) {
     session: p.session_id ? sha8(p.session_id) : null,
     task_id: tag.task_id,
     ...(tag.task_id && !isValidTaskId(tag.task_id) ? { task_id_invalid: true } : {}),
+    ...(tag.task_id_inferred ? { task_id_inferred: true } : {}),
+    ...(tag.tag_issue ? { tag_issue: tag.tag_issue } : {}),
     task_type: tag.task_type,
     score: tag.score,
     urgency: tag.urgency,
@@ -1440,7 +2285,7 @@ function buildDispatch(p, ctx) {
     model: normalizeModel(trObj.resolvedModel) || normalizeModel(ti.model) || null,
     effort: explicitEffort || parentEffort || null,
     effort_inherited: !explicitEffort,
-    subagent_type: typeof ti.subagent_type === 'string' && ti.subagent_type ? ti.subagent_type : 'general-purpose',
+    subagent_type: subagentType,
     background: ti.run_in_background === true || trObj.isAsync === true,
     // Orchestrator (main session) at the moment of this dispatch. Raw session_id joins with `dieu-phoi ctx`.
     session_id: typeof p.session_id === 'string' && p.session_id ? p.session_id : null,
@@ -1449,15 +2294,55 @@ function buildDispatch(p, ctx) {
     orch_compactions: orch.compactions,
     orch_cum_usd: orch.cum_usd,
   }, tag.parent_task_id ? { parent_task_id: tag.parent_task_id } : {},
+  projectFields(p),
+  tierFields(ctx, tag, normalizeModel(trObj.resolvedModel) || normalizeModel(ti.model) || null, explicitEffort || parentEffort || null),
   // core 0.5.0: an Agent call made inside a subagent (gen-2) carries the caller's agent_id
   typeof p.agent_id === 'string' && p.agent_id ? { parent_agent_id: p.agent_id } : {},
   commonFields(ctx));
 }
 
+/** suggested_tier / choose_tier / suggested_source / dispatched_tier / tier_mismatch, only when choose left a record. */
+function tierFields(ctx, tag, model, effort) {
+  const s = tag.task_id ? readSuggestion(ctx, tag.task_id, tag.role) : null;
+  if (!s) return {};
+  const dispatched = tierOf(model, effort);
+  const out = {
+    suggested_tier: s.suggested_tier,
+    choose_tier: s.choose_tier || s.suggested_tier,
+    suggested_source: s.source || null,
+    dispatched_tier: dispatched,
+  };
+  if (dispatched && !dispatched.includes('?')) out.tier_mismatch = dispatched !== out.choose_tier;
+  return out;
+}
+
+/**
+ * Core 0.5.3: besides the dispatch event, a dieu-phoi dispatch with a flagged tag (tag_issue) or a task already on
+ * its HANDOFF_CHAIN_WARN-th handoff gets a warning back to the caller as PostToolUse additionalContext (the
+ * returned event carries it as a non-enumerable `stdout`, never written to the log).
+ */
 function handlePostToolUse(p, ctx) {
   if (p.tool_name !== 'Agent' && p.tool_name !== 'Task') return null;
   const ev = buildDispatch(p, ctx);
+  const notes = [];
+  if (ev.tag_issue) {
+    const ti = p.tool_input && typeof p.tool_input === 'object' ? p.tool_input : {};
+    const known = knownTaskTypes(ctx);
+    const tag = resolveTag(ti.prompt, known) || { tag_issue: ev.tag_issue, task_id: null, task_type: ev.task_type };
+    notes.push(tagIssueMessage(tag, known));
+  }
+  if (ev.task_id && ev.role === 'exec') {
+    const n = countTaskHandoffs(ctx, ev.task_id);
+    if (n) ev.task_handoffs = n;
+    if (n >= HANDOFF_CHAIN_WARN) notes.push(handoffChainMessage(ev.task_id, n));
+  }
   appendEvent(ctx, ev);
+  if (notes.length) {
+    Object.defineProperty(ev, 'stdout', {
+      enumerable: false,
+      value: JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: notes.join('\n') } }),
+    });
+  }
   return ev;
 }
 
@@ -1626,7 +2511,7 @@ function handleSubagentStop(p, ctx) {
     const last = lastUuidOf(lines);
     if (last && seen.has(last)) return null; // same segment reported twice
     sum = summarizeTranscript(lines, { afterUuids: seen, pricing: loadPricing(ctx) });
-    tag = tagFromTranscript(lines);
+    tag = tagFromTranscript(lines, knownTaskTypes(ctx));
   }
   const t = tag || UNTAGGED;
   const ev = Object.assign({
@@ -1648,7 +2533,7 @@ function handleSubagentStop(p, ctx) {
     tokens: sum ? sum.tokens : null,
     cost_usd: sum ? sum.cost_usd : null,
     model: sum ? sum.model : null,
-  }, commonFields(ctx));
+  }, t.task_id_inferred ? { task_id_inferred: true } : {}, t.tag_issue ? { tag_issue: t.tag_issue } : {}, commonFields(ctx));
   // Core 0.5.2 (retro 2026-10-18): how the segment ended, measured here instead of re-reading transcripts later.
   // Labels and numbers only, never text.
   const why = exists ? abortReasonOf(lines) : null;
@@ -1821,7 +2706,7 @@ function readSlice(fd, start, len) {
  * Tag of the subagent's first prompt, read from the head of its transcript only.
  * Returns { found: false } while no user line is on disk yet (transcript written async), else { found: true, tag|null }.
  */
-function readHeadTag(file) {
+function readHeadTag(file, known) {
   let fd;
   try { fd = fs.openSync(file, 'r'); } catch (_) { return { found: false, tag: null }; }
   try {
@@ -1831,7 +2716,7 @@ function readHeadTag(file) {
       const text = readSlice(fd, 0, len).toString('utf8');
       const complete = len === size ? text : text.slice(0, text.lastIndexOf('\n') + 1);
       const lines = parseJsonl(complete);
-      if (lines.some((l) => l && l.type === 'user' && l.message)) return { found: true, tag: tagFromTranscript(lines), prompt: firstPromptText(lines) };
+      if (lines.some((l) => l && l.type === 'user' && l.message)) return { found: true, tag: tagFromTranscript(lines, known), prompt: firstPromptText(lines) };
       if (len >= size || len >= WATCH_HEAD_MAX) return { found: false, tag: null };
     }
   } finally {
@@ -1902,7 +2787,7 @@ function watchState(p, ctx, agentId) {
   if (!st || typeof st !== 'object') {
     st = null;
     if (tpath) {
-      const h = readHeadTag(tpath);
+      const h = readHeadTag(tpath, knownTaskTypes(ctx));
       if (h.found) {
         st = h.tag
           ? { dp: true, task_id: h.tag.task_id, run_id: h.tag.task_id ? null : runIdFromPrompt(h.prompt), role: h.tag.role, parent_task_id: h.tag.parent_task_id || null, fired: 0, t: Date.now() }
@@ -2325,15 +3210,18 @@ async function runSync(ctx, opts) {
 // ------------------------------------------------------------------ exports / main
 
 module.exports = {
-  runsDir, loadPlans, isDieuPhoiPrompt, foldPrompt, sinkStatusCached, sinkUrlKey, SINK_CACHE_TTL_MS, scoutBriefPath, quickHealth, startRun, startInfo, orchLessons, orchLessonLines, abortReasonOf, completionStatus, logGate, QUOTA_PAUSE_MARKER, stepIds, START_STEP_IDS, healthLine, formatStartBlock, handleUserPromptSubmit, START_PREFIX, 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, startKnowledgeOf, knowledgeLines, orchLessons, orchLessonLines, abortReasonOf, completionStatus, logGate, QUOTA_PAUSE_MARKER, 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, renameWithRetry, acquireLock, defaultClaudeDir, resolveHome, pathsFor, loadConfig, makeCtx,
-  logError, computeUserHash, userHash, commonFields, parseTag, TASK_ID_RE, isValidTaskId, newTaskId, taskIdError, normalizeModel, loadPricing,
+  sha8, nowIso, readJsonFile, writeFileAtomic, renameWithRetry, acquireLock, acquireFileLock, withFileLock, defaultClaudeDir, resolveHome, pathsFor, loadConfig, makeCtx,
+  logError, computeUserHash, userHash, commonFields, parseTag, resolveTag, knownTaskTypes, tagIssueMessage, DEFAULT_EXTRA_TYPES,
+  recordSuggestion, readSuggestion, suggestFile, SUGGEST_MAX_AGE_MS, countTaskHandoffs, handoffChainMessage, HANDOFF_CHAIN_WARN, tierFields, TASK_ID_RE, isValidTaskId, newTaskId, taskIdError, normalizeModel, loadPricing,
   priceFor, usageBuckets, requestCost, parseJsonl, readTranscript, lastUuidOf,
   firstPromptText, tagFromTranscript, summarizeTranscript,
-  RESULT_ROLES, BLOCKED_RESULT_NAME_RE, resultFileName, findResultFiles, resultRunDir, finalAssistantText, persistInlineResult, orchestratorUsage, orchCacheFile, findSessionTranscript, SESSION_ID_RE, HOOK_COLD_MAX_BYTES, appendEvent, eventLinesFrom, readEventLines, readEvents, readEventsBuffer, archiveFiles, readArchiveLines,
+  RESULT_ROLES, BLOCKED_RESULT_NAME_RE, resultFileName, findResultFiles, resultRunDir, finalAssistantText, persistInlineResult, orchestratorUsage, orchCacheFile, findSessionTranscript, SESSION_ID_RE, HOOK_COLD_MAX_BYTES, appendEvent, EVENTS_LOCK_WAIT_MS, eventLinesFrom, readEventLines, readEvents, readEventsBuffer, archiveFiles, readArchiveLines,
   loadSyncOffset, saveSyncOffset, recordRejected, unsyncedInfo, loadSegments, saveSegments, segmentFile,
   HANDOFF_MARKER, HANDOFF_THRESHOLDS, watchThresholds, GATE_MAX_CHILDREN, HELPER_AGENT_TYPE, watchAgentId, subagentTranscriptPath, readHeadTag, lastContextTokens, watchState, handoffMessage, handleWatch, handleGate, handleGateRelease, gateDir, gateSlots, gateReserve, gateConfirm, GATE_PENDING_MS,
+  globMatch, pathspecOf, diffShas, dirtyFiles, computeFreshness, addDirty, indexStamp, freshnessCacheFile, readFreshCache, cachedFor, freshCounts, knowledgeSummary, shortFileList, readStoreIndex, relatedStatus, startKnowledge, FRESH_CACHE_MAX, DIFF_TIMEOUT_MS, HOOK_DIFF_TIMEOUT_MS, DIRTY_TIMEOUT_MS,
+  projectsDir, findGit, originUrlFromConfig, normalizeRemoteUrl, resolveProject, readHead, repoFromBrief, projectFields, nativePath, isStoreDirName, aliasesFile, loadAliases, keyDirName,
   extractAgentId, hasAssistantUsage, hasDispatch, buildDispatch, handlePostToolUse, handleSubagentStop, maybeSpawnSync, runHook, runSync,
 };