@kienntpixon/dieu-phoi 0.5.3 → 0.6.0

package/hook.cjs

@@ -26,7 +26,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.5.3';
+const CORE_VERSION = '0.6.0';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -92,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. */
@@ -135,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'),
   };
@@ -849,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 = '';
@@ -1442,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) {
@@ -1465,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');
 }
@@ -1472,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) },
@@ -1587,6 +1651,605 @@ 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;
@@ -1631,6 +2294,7 @@ 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 } : {},
@@ -2546,16 +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,
+  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,
 };