@delorenj/pjangler 1.4.5 → 1.5.2

package/dist/prompt.js

@@ -347,7 +347,8 @@ function readPromptFacts(root, now) {
   let identifier;
   try {
     const manifest = JSON.parse(readFileSync2(join3(root, ".project.json"), "utf8"));
-    if (typeof manifest.project_slug === "string" && manifest.project_slug) slug = manifest.project_slug;
+    const projectId = manifest.project_id ?? manifest.project_slug;
+    if (typeof projectId === "string" && projectId.trim()) slug = projectId.trim().toLowerCase();
     const provider = manifest.ticket_provider;
     if (provider && typeof provider.identifier === "string" && provider.identifier) identifier = provider.identifier;
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delorenj/pjangler",
-  "version": "1.4.5",
+  "version": "1.5.2",
   "description": "Project subsystem bootstrapper CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -16,16 +16,17 @@
     "contracts",
     "templates/commonproject/copier.yml",
     "templates/commonproject/template",
-    "templates/hermes-agent/copier.yml",
-    "templates/hermes-agent/template",
     ".mise/scripts/versioning.sh",
-    ".mise/scripts/link-agentfiles.sh"
+    ".mise/scripts/link-agentfiles.sh",
+    "scripts/install-project-registry.mjs",
+    "scripts/migrate-project-registry.mjs",
+    "src/project/registryClient.ts"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "scripts": {
-    "build": "esbuild src/index.ts src/mcp-server.ts src/prompt.ts --bundle --packages=external --platform=node --format=esm --sourcemap --outdir=dist && node scripts/export-project-notebook-skill.mjs",
+    "build": "esbuild src/index.ts src/mcp-server.ts src/prompt.ts src/project-registry-service.ts src/notebook/journal-service-main.ts --bundle --packages=external --platform=node --format=esm --sourcemap --outbase=src --outdir=dist && node scripts/export-project-notebook-skill.mjs",
     "check:audit:prod": "npm audit --omit=dev",
     "check:lock": "node scripts/check-package-lock-parity.mjs",
     "check:submodules": "node scripts/check-submodule-contract.mjs",
@@ -40,10 +41,12 @@
     "migrate:down": "node-pg-migrate --migrations-dir migrations down",
     "migrate:create": "node-pg-migrate --migrations-dir migrations create",
     "prepublishOnly": "npm run check:lock && npm run check:submodules -- --remote --recursive --archive --npm && npm run build && npm run check:tracked-secrets",
-    "test:hermes-profile-inheritance": "node tests/hermes-profile-inheritance-regressions.mjs",
-    "test:coverage": "npm run build && NODE_OPTIONS=--max-old-space-size=12288 c8 --exclude='**/.pjan-*/**' --reporter=json-summary --reporter=text-summary --src=src --report-dir=coverage node scripts/run-tests.mjs",
+    "test:coverage": "npm run build && NODE_OPTIONS=--max-old-space-size=12288 c8 node scripts/run-tests.mjs",
     "coverage:check": "node scripts/coverage-ratchet.mjs",
-    "coverage:apply": "node scripts/coverage-ratchet.mjs --apply"
+    "coverage:apply": "node scripts/coverage-ratchet.mjs --apply",
+    "registry:serve": "node dist/project-registry-service.js",
+    "journal:serve": "node dist/notebook/journal-service-main.js",
+    "registry:install": "node scripts/install-project-registry.mjs"
   },
   "keywords": [
     "cli",
@@ -56,11 +59,13 @@
   "license": "MIT",
   "dependencies": {
     "@clack/prompts": "^1.4.0",
+    "@delorenj/skillex": "0.1.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.2",
     "pg": "^8.16.0",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "smol-toml": "^1.8.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/scripts/install-project-registry.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { execFileSync } from 'node:child_process';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const entrypoint = join(root, 'dist/project-registry-service.js');
+if (!existsSync(entrypoint)) throw new Error('Build first: npm run build');
+const directory = join(homedir(), '.config/systemd/user');
+mkdirSync(directory, { recursive: true });
+const unit = join(directory, 'pjangler-project-registry.service');
+const quote = value => `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`;
+writeFileSync(unit, `[Unit]\nDescription=PJangler manifest-owned project registry\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=${quote(process.execPath)} ${quote(entrypoint)}\nEnvironment=PGHOST=/var/run/postgresql\nEnvironment=PGDATABASE=33god\nEnvironment=PGUSER=${userInfo().username}\nEnvironment=PJ_REGISTRY_PORT=8764\nRestart=on-failure\nRestartSec=3\n\n[Install]\nWantedBy=default.target\n`);
+const runtimeDir = process.env.XDG_RUNTIME_DIR || `/run/user/${userInfo().uid}`;
+const systemdEnv = { ...process.env, ...(existsSync(runtimeDir) ? { XDG_RUNTIME_DIR: runtimeDir } : {}),
+  ...(!process.env.DBUS_SESSION_BUS_ADDRESS && existsSync(join(runtimeDir, 'bus')) ? { DBUS_SESSION_BUS_ADDRESS: `unix:path=${join(runtimeDir, 'bus')}` } : {}) };
+execFileSync('systemd-analyze', ['--user', 'verify', unit], { stdio: 'inherit', env: systemdEnv });
+execFileSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit', env: systemdEnv });
+execFileSync('systemctl', ['--user', 'enable', 'pjangler-project-registry.service'], { stdio: 'inherit', env: systemdEnv });
+execFileSync('systemctl', ['--user', 'restart', 'pjangler-project-registry.service'], { stdio: 'inherit', env: systemdEnv });
+let healthy = false;
+for (let attempt = 0; attempt < 30; attempt++) {
+  try {
+    const response = await fetch('http://127.0.0.1:8764/health', { signal: AbortSignal.timeout(1000) });
+    const health = await response.json();
+    if (response.ok && health.ok && health.service === 'pjangler-project-registry') { healthy = true; break; }
+  } catch {}
+  await delay(200);
+}
+if (!healthy) throw new Error('Registry failed readiness check; inspect journalctl --user -u pjangler-project-registry.service');
+console.log(`Installed and healthy: ${unit}`);

package/scripts/migrate-project-registry.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// One-way migration: manifests own values; YAML supplies only missing legacy
+// metadata and discovery locations. No live ticket-provider writes.
+import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync, lstatSync, openSync, closeSync, fsyncSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve, join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+import YAML from "yaml";
+import { normalizeProjectId } from "../src/project/registryClient.ts";
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => { const i = args.indexOf(name); return i < 0 ? fallback : args[i + 1]; };
+const apply = args.includes("--apply");
+const legacyPath = resolve(option("--legacy", join(homedir(), ".config/pjangler/projects.yaml")));
+const endpoint = option("--url", process.env.PJ_REGISTRY_URL || "http://localhost:8764").replace(/\/$/, "");
+const extraRepos = args.flatMap((arg, i) => arg === "--repo" ? [resolve(args[i + 1])] : []);
+const hash = text => createHash("sha256").update(text).digest("hex");
+const legacyText = existsSync(legacyPath) ? readFileSync(legacyPath, "utf8") : undefined;
+const legacy = legacyText ? YAML.parse(legacyText) : { projects: {} };
+const projects = new Map();
+for (const [id, record] of Object.entries(legacy.projects || {})) {
+  if (!record || typeof record !== "object" || typeof record.repo_path !== "string" || !record.repo_path.trim()) throw new Error(`Legacy project ${id} has no repo_path`);
+  const repo = resolve(record.repo_path);
+  if (projects.has(repo)) throw new Error(`Duplicate legacy repo_path ${repo}: ${projects.get(repo).id} and ${id}`);
+  projects.set(repo, { id, record });
+}
+// Keep authoritative values recursively; only absent fields are inherited.
+const mergeMissing = (current, fallback) => {
+  if (current === undefined) return fallback;
+  if (!current || typeof current !== "object" || Array.isArray(current) || !fallback || typeof fallback !== "object" || Array.isArray(fallback)) return current;
+  const result = { ...current };
+  for (const [key, value] of Object.entries(fallback)) result[key] = mergeMissing(result[key], value);
+  return result;
+};
+for (const path of extraRepos) if (!projects.has(path)) projects.set(path, { record: {} });
+const planned = [];
+const ids = new Map();
+
+// Preflight every location before the first write.
+for (const [repo, { id: legacyId, record }] of projects) {
+  const path = join(repo, ".project.json");
+  if (!existsSync(path)) throw new Error(`Missing authoritative manifest: ${path}`);
+  const fileStat = lstatSync(path);
+  if (!fileStat.isFile() || fileStat.isSymbolicLink()) throw new Error(`Expected regular manifest: ${path}`);
+  const original = readFileSync(path, "utf8");
+  const manifest = JSON.parse(original);
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new Error(`Expected a manifest object: ${path}`);
+  const id = normalizeProjectId(manifest.project_id ?? manifest.project_slug ?? legacyId);
+  if (manifest.project_id && manifest.project_slug && normalizeProjectId(manifest.project_slug) !== id) throw new Error(`Conflicting identities in ${path}`);
+  if (ids.has(id) && ids.get(id) !== path) throw new Error(`Duplicate project_id ${id}: ${path} and ${ids.get(id)}`);
+  ids.set(id, path);
+  const { name, description, slug: _slug, project_id: _id, repo_path: _repo, notebook, ...extensions } = record;
+  const fallback = { ...extensions, project_name: name, project_description: description,
+    ...(notebook ? { notebook: { binding: notebook } } : {}) };
+  // Empty legacy URL placeholders carry no metadata and canonical writers omit them.
+  if (fallback.ticket_provider?.board_url === "") {
+    fallback.ticket_provider = { ...fallback.ticket_provider };
+    delete fallback.ticket_provider.board_url;
+  }
+  const desired = mergeMissing(manifest, fallback);
+  // An explicit agents map is a complete declaration; do not revive removed roles.
+  if (manifest.agents !== undefined) desired.agents = manifest.agents;
+  desired.project_id = id;
+  delete desired.project_slug;
+  desired.repo_path = repo;
+  const text = `${JSON.stringify(desired, null, 2)}\n`;
+  planned.push({ project_id: id, manifest_path: path, changed: text !== original, originalHash: hash(original), mode: fileStat.mode & 0o777, text });
+}
+const request = async (path, body) => {
+  const response = await fetch(`${endpoint}${path}`, { method: "POST", headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error || `Registry HTTP ${response.status}`);
+  return result;
+};
+if (apply) {
+  const health = await fetch(`${endpoint}/health`, { signal: AbortSignal.timeout(5_000) });
+  if (!health.ok) throw new Error("Registry health check failed before migration");
+  const existingResponse = await fetch(`${endpoint}/v1/registry`, { signal: AbortSignal.timeout(15_000) });
+  if (!existingResponse.ok) throw new Error("Cannot inspect registry before migration");
+  const existing = await existingResponse.json();
+  for (const item of planned) {
+    const indexed = existing.__registry_status?.[item.project_id]?.manifest_path
+      ?? (existing.projects?.[item.project_id]?.repo_path ? join(existing.projects[item.project_id].repo_path, ".project.json") : undefined);
+    if (indexed && resolve(indexed) !== item.manifest_path) throw new Error(`Project ID collision ${item.project_id}: index=${indexed}, manifest=${item.manifest_path}`);
+  }
+  for (const item of planned) {
+    if (hash(readFileSync(item.manifest_path, "utf8")) !== item.originalHash) throw new Error(`Manifest changed during migration: ${item.manifest_path}`);
+    if (item.changed) {
+      const temporary = `${item.manifest_path}.${process.pid}.tmp`;
+      const fd = openSync(temporary, "wx", item.mode);
+      try { writeFileSync(fd, item.text); fsyncSync(fd); } finally { closeSync(fd); }
+      if (hash(readFileSync(item.manifest_path, "utf8")) !== item.originalHash) throw new Error(`Manifest changed before commit: ${item.manifest_path}`);
+      renameSync(temporary, item.manifest_path);
+      const directory = openSync(dirname(item.manifest_path), "r");
+      try { fsyncSync(directory); } finally { closeSync(directory); }
+    }
+    await request("/v1/index", { manifest_path: item.manifest_path });
+  }
+  if (legacy.notebook) {
+    // The running service may have been edited after the original migration.
+    // Re-read immediately before the settings write; a rerun only fills gaps.
+    const latestResponse = await fetch(`${endpoint}/v1/registry`, { signal: AbortSignal.timeout(15_000) });
+    if (!latestResponse.ok) throw new Error("Cannot inspect current settings before migration");
+    const latest = await latestResponse.json();
+    const notebook = mergeMissing(latest.notebook, legacy.notebook);
+    if (JSON.stringify(notebook) !== JSON.stringify(latest.notebook)) await request("/v1/settings", { notebook });
+  }
+  // An audit receipt contains locations/hashes only. YAML is no longer a
+  // production input; retain the migration source until the caller archives it.
+  const receiptPath = resolve(option("--receipt", join(homedir(), ".local/state/pjangler/registry-migration.json")));
+  mkdirSync(dirname(receiptPath), { recursive: true });
+  writeFileSync(receiptPath, JSON.stringify({ migrated_at: new Date().toISOString(), legacy_path: legacyPath,
+    legacy_hash: legacyText ? hash(legacyText) : null, endpoint,
+    projects: planned.map(({ text, originalHash, mode, ...item }) => ({ ...item, content_hash: hash(text) })) }, null, 2) + "\n");
+}
+console.log(JSON.stringify({ apply, endpoint, projects: planned.map(({ text, originalHash, mode, ...item }) => item) }, null, 2));

package/src/project/registryClient.ts

@@ -0,0 +1,62 @@
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export const DEFAULT_REGISTRY_URL = "http://localhost:8764";
+
+export function isRegistryServiceLocation(location: string): boolean {
+  return /^https?:\/\//i.test(location);
+}
+
+/** An explicit file location is an import/test adapter; production uses the service. */
+export function resolveRegistryLocation(location?: string, env: NodeJS.ProcessEnv = process.env): string {
+  const value = location || env.PJ_PROJECT_REGISTRY || env.PJ_REGISTRY_URL || DEFAULT_REGISTRY_URL;
+  if (isRegistryServiceLocation(value)) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash) throw new Error("Registry URL must not contain credentials, a query or a fragment");
+    return url.toString().replace(/\/$/, "");
+  }
+  return resolve(value.startsWith("~/") ? `${homedir()}/${value.slice(2)}` : value);
+}
+
+// Existing lifecycle/config APIs are synchronous. Isolate the network wait in
+// a bounded Node child rather than making a file cache a second authority.
+// Request bodies travel over stdin, never through shell interpolation/argv.
+const REQUEST = `
+let input='';
+for await (const chunk of process.stdin) input+=chunk;
+const {url,method,body,timeout}=JSON.parse(input);
+try {
+  const response=await fetch(url,{method,headers:{'Content-Type':'application/json'},
+    ...(body===undefined?{}:{body:JSON.stringify(body)}),signal:AbortSignal.timeout(timeout)});
+  const text=await response.text();
+  let result;try{result=JSON.parse(text)}catch{throw new Error('Registry returned invalid JSON')}
+  if(!response.ok) throw new Error(result.error||result.message||('Registry HTTP '+response.status));
+  process.stdout.write(JSON.stringify(result));
+} catch(error) {process.stderr.write(error.message);process.exitCode=1;}
+`;
+
+export function registryRequest<T>(location: string, method: string, path: string, body?: unknown): T {
+  const endpoint = resolveRegistryLocation(location);
+  if (!isRegistryServiceLocation(endpoint)) throw new Error("This operation requires the project registry service");
+  const timeout = 15_000;
+  const result = spawnSync(process.execPath, ["--input-type=module", "-e", REQUEST], {
+    input: JSON.stringify({ url: `${endpoint}${path}`, method, body, timeout }),
+    encoding: "utf8", timeout: timeout + 2_000, maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error) {
+    const detail = result.stderr?.trim() || result.error?.message || "request failed";
+    throw new Error(`Project registry request failed (${endpoint}): ${detail}. Check pjangler-project-registry.service; local pj info remains available.`);
+  }
+  try { return JSON.parse(result.stdout) as T; }
+  catch { throw new Error(`Project registry returned invalid JSON (${endpoint})`); }
+}
+
+export function normalizeProjectId(value: unknown): string {
+  if (typeof value !== "string") throw new Error("project_id is required");
+  const id = value.trim().toLowerCase();
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(id) || id.endsWith("-") || id.length > 128) {
+    throw new Error(`Invalid project_id: ${value}; use letters, digits and internal hyphens`);
+  }
+  return id;
+}

package/templates/commonproject/copier.yml

@@ -79,7 +79,7 @@ primary_language:
   default: python
   when: false
 
-# Whether to scaffold the project-scoped agent-hooks + skill fan-out layer
+# Whether to scaffold the project-scoped agent-hooks layer
 # (.agents/hooks + the mise enter/leave wiring that injects into each agent CLI's
 # per-user config). Defaults true so a bare `copier copy` still gets it. pjangler
 # passes `--data agent_hooks_layer=false` when the machine already runs a GLOBAL
@@ -91,7 +91,7 @@ agent_hooks_layer:
   when: false
 
 # When agent_hooks_layer is false, omit only the project-scoped hook tree. The
-# skills manifest stays — sync-skills.py writes project-local CLI dirs and is safe
+# skills manifest stays — Skillex writes project-local CLI dirs and is safe
 # even on machines that already run a global ~/.agents/hooks install.
 # The `.copier-noop-never-matches` sentinel keeps every pattern non-empty when the
 # layer is enabled, which copier requires.
@@ -107,6 +107,11 @@ _exclude:
   - "{% if agent_hooks_layer %}.copier-noop-never-matches{% else %}.agents/hooks/**{% endif %}"
   - "{% if agent_hooks_layer %}.copier-noop-never-matches{% else %}.agents/local.example.json{% endif %}"
 
+_skip_if_exists:
+  # Selection is project intent, not generated output. A refresh must preserve
+  # inheritance choices, exclusions, and active packs byte-for-byte.
+  - ".agents/skills.json"
+
 # --- Post-generation tasks ---
 #
 # NOTE: intentionally does NOT run `mise trust`. Trusting the repo fires the mise
@@ -114,27 +119,19 @@ _exclude:
 # into the caller's shared per-user CLI configs. Scaffolding must never mutate
 # global state as a side effect — the operator trusts/enters the repo themselves.
 _tasks:
-  # PJAN-82: seed the base ignore only when there is nothing to lose. `cp` over
-  # an existing .gitignore silently discarded whatever the repo already had,
-  # every time the template was re-rendered into a live project.
-  - "[ -s .gitignore ] || cp ~/.config/git/ignore .gitignore 2>/dev/null || [ -s .gitignore ] || echo '# Add ignores here' > .gitignore"
-  # Ensure secrets + per-dev agent-hook/skill overrides are ignored (appended after the base ignore).
-  # Each CLI root's hand-owned config is durable project state; the skill
-  # projections inside it are not — bmad-method and skills:sync rewrite them
-  # on every run, so they are re-ignored after the un-ignore lines (last
-  # match wins). _bmad/_config/manifest.yaml pins the version that
-  # reproduces them exactly.
-  # PJAN-82: appended once (a re-render used to duplicate the whole block), and
-  # the skill patterns carry no trailing slash so a SYMLINKED projection is
-  # ignored too — .gemini/.copilot/.kimi-code get a symlink, not a directory.
-  - "grep -q '^# Generated CLI configurations are durable project state' .gitignore 2>/dev/null || printf '\\n# Secrets + per-dev agent-hook/skill overrides (see .agents/local.example.json)\\n.env\\n.env.*\\n!.env.op\\n.agents/local.json\\n.lastagent\\n**/.claude/settings.local.json\\n\\n# Generated CLI configurations are durable project state...\\n!.claude/\\n!.claude/**\\n!.codex/\\n!.codex/**\\n!.gemini/\\n!.gemini/**\\n!.copilot/\\n!.copilot/**\\n!.opencode/\\n!.opencode/**\\n!.kimi-code/\\n!.kimi-code/**\\n# ...but their skill projections are regenerated, so they stay out of the tree.\\n# No trailing slash: some CLIs get a real directory here and some a symlink.\\n/.agents/skills\\n.claude/skills\\n.codex/skills\\n.gemini/skills\\n.copilot/skills\\n.opencode/skills\\n.kimi-code/skills\\n' >> .gitignore"
+  # A repository ignore file is a portable project contract, never a snapshot
+  # of one developer's core.excludesFile. Preserve existing content byte-for-
+  # byte and append only the small CommonProject-owned contract when absent.
+  # Machine-local backup/editor/CLI exclusions belong in the user's global
+  # ignore; `.agents/` is the sole canonical agent-config tree in Git.
+  - "touch .gitignore; if [ -s .gitignore ] && [ -n \"$(tail -c 1 .gitignore)\" ]; then printf '\\n' >> .gitignore; fi; grep -Fqx '# CommonProject repository contract' .gitignore 2>/dev/null || printf '%s\\n' '# CommonProject repository contract' >> .gitignore; for pattern in '.env' '.env.*' '!.env.op' '/.agents/local.json' '/.agents/skills'; do grep -Fqx -- \"$pattern\" .gitignore 2>/dev/null || printf '%s\\n' \"$pattern\" >> .gitignore; done"
   # PJAN-82: use the managed script, which refuses to replace a REAL CLAUDE.md.
   # `ln -sf` cannot distinguish a stale link it owns from a hand-written file it
   # must not touch, so a re-render into a live project destroyed the file and
   # reported success.
   - "./.mise/scripts/link-agentfiles.sh \"$(pwd)\""
-  # Materialize the declared Skillex packs' manifest + symlink topology
-  # without copying pack content or disturbing project-specific skills.
-  - "python3 .mise/scripts/provision-packs.py --root \"$(pwd)\""
+  # One explicit project activation after rendering. Trust only this generated
+  # config for this process; do not persist trust or execute enter/watch hooks.
+  - "MISE_TRUSTED_CONFIG_PATHS=\"$(pwd)/mise.toml\" mise run skills:sync"
   # Stamp the repo's absolute path into .project.json (the SOT) post-render.
   - "python3 -c \"import json,os,pathlib; p=pathlib.Path('.project.json'); d=json.loads(p.read_text()); d['repo_path']=os.getcwd(); p.write_text(json.dumps(d,indent=2)+chr(10))\""

package/templates/commonproject/template/.agents/hooks/README.md

@@ -29,17 +29,17 @@ You normally run nothing — `mise` does it on directory enter/leave (see
 | **Claude Code** | committed `.claude/settings.json` (`hooks` key, `$CLAUDE_PROJECT_DIR`) | project, committed | nothing to do — every clone gets it |
 | **Codex** | per-user `~/.codex/hooks.json` (absolute-path entries) | per-user, injected | `mise enter` → inject, `mise leave` → remove |
 | **Kimi** | per-user `~/.kimi-code/config.toml` (sentinel `[[hooks]]` block) | per-user, injected | `mise enter` → inject, `mise leave` → remove |
-| **Hermes** | runtime `config.yaml` `hooks:` + `shell-hooks-allowlist.json`, via an **adapter** | per-deployment | `mise enter` merges (idempotent, backed up) |
+| **Hermes** | runtime `config.yaml` `hooks:` + `shell-hooks-allowlist.json`, via an **adapter** | per-deployment | `mise enter` merges owned commands idempotently |
 
 **Kimi** is fully Claude-compatible (identical event names; payload `{prompt}` /
 `{tool_name, tool_input}` on stdin; `shell:true` commands; edit tools `Write`/`Edit`),
 so it **reuses the same guard-wrapped scripts** as Claude/Codex — just injected as a
 sentinel-bounded `[[hooks]]` block in the per-user `config.toml` (timeout in seconds;
-`KIMI_CODE_HOME` respected; backed up to `config.toml.caf-bak`; byte-exact reversible).
+`KIMI_CODE_HOME` respected; only the owned sentinel block is replaced).
 
 Each injection is **surgical & reversible** — `sync.py` only touches entries
-whose command points at this repo's `.agents/hooks/`, backs up before its first
-write (`*.caf-bak`), and an uninstall restores the original data.
+whose command points at this repo's `.agents/hooks/`; foreign settings are preserved.
+No adjacent backups are written.
 
 ## The hooks
 
@@ -136,3 +136,9 @@ Without a key the hooks **no-op gracefully** — recall/retain just do nothing.
 
 `gitmark/` holds standalone git helpers — committed for convenience, **not** part
 of the agent-hook fan-out.
+
+## Central hook ownership
+
+On a machine with an activated Bloodbank hook-hub, `~/.config/33god/hook-hub/ownership.json` identifies the CLI families and concerns that have completed native cutover. Fanout omits those concerns, removes its earlier injected copies, and preserves all foreign commands. Runtime guards also consult the hub ownership helper, so committed project fallback settings cannot double-fire after cutover. A paused central concern remains owned and is not restored by a later project sync.
+
+Without that manifest this template continues to provide standalone project hooks. Codex timeouts are seconds. Claude, Codex, and Kimi use `SessionEnd` for session closure; Hermes uses `on_session_finalize`. Stop/`on_session_end` indicate turn completion.

package/templates/commonproject/template/.agents/hooks/hermes/hindsight-hook.sh

@@ -4,7 +4,7 @@
 # Hermes fires shell hooks with the payload piped as JSON on stdin:
 #   {"hook_event_name","tool_name","tool_input","session_id","cwd","extra"}
 # and runs the command shell=False (argv), so this is invoked as:
-#   hindsight-hook.sh <on_session_end|post_tool_call>
+#   hindsight-hook.sh <on_session_finalize|post_tool_call>
 #
 # Why an adapter (not the Claude hindsight scripts verbatim):
 #   - Hermes has NO user-prompt event, so recall has no attach point here.
@@ -16,6 +16,16 @@
 set -uo pipefail
 
 EVENT="${1:-}"
+HUB_CONCERN=""
+case "$EVENT" in
+  post_tool_call) HUB_CONCERN=hindsight-retain ;;
+  on_session_finalize) HUB_CONCERN=hindsight-session-end ;;
+esac
+if [[ -n "$HUB_CONCERN" && "${BB_HOOK_HUB:-}" != "off" && -f "$HOME/.agents/hooks/hub/ownership.py" ]] &&
+   python3 "$HOME/.agents/hooks/hub/ownership.py" "$HUB_CONCERN" --cli hermes; then
+  cat >/dev/null 2>&1 || true
+  exit 0
+fi
 HERMES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"   # .agents/hooks/hermes
 REPO_ROOT="$(cd "${HERMES_DIR}/../../.." && pwd)"            # the project repo (NOT the PM submodule)
 
@@ -50,7 +60,7 @@ case "$EVENT" in
     snippet=$(printf '%s' "$content" | head -3 | tr '\n' ' ' | cut -c1-200)
     retain_detached "code-edit" "Hermes ${tool} edited ${path:-<no-path>}: ${snippet}"
     ;;
-  on_session_end)
+  on_session_finalize)
     hook_disabled "hindsight-session-end" && exit 0
     sid=$(jq -r '.session_id // "unknown"' <<<"$INPUT" 2>/dev/null || echo unknown)
     retain_detached "session-summary" "Hermes PM session ${sid} ended at $(date -u +%Y-%m-%dT%H:%M:%SZ)"

package/templates/commonproject/template/.agents/hooks/hooks.master.json

@@ -44,26 +44,26 @@
       "config_target": ".claude/settings.json",
       "base_dir": "$CLAUDE_PROJECT_DIR/.agents/hooks",
       "timeout_unit": "s",
-      "owns_hooks_key": true,
+      "owns_hooks_key": false,
       "lifecycle_events": {
         "user_prompt": "UserPromptSubmit",
         "post_tool": "PostToolUse",
-        "session_end": "Stop"
+        "session_end": "SessionEnd"
       },
-      "notes": "Committed to the repo, so every dev gets these automatically with NO bootstrap. Claude expands $CLAUDE_PROJECT_DIR in hook commands at runtime. sync owns the entire `hooks` key of this file."
+      "notes": "Project hooks remain portable fallbacks. Fanout owns only its canonical command paths and preserves foreign groups. Activated Bloodbank hub concerns are omitted automatically."
     },
     "codex": {
       "enabled": true,
       "dialect": "codex_hooks",
       "config_target": "~/.codex/hooks.json",
       "base_dir": "{repo}/.agents/hooks",
-      "timeout_unit": "ms",
+      "timeout_unit": "s",
       "lifecycle_events": {
         "user_prompt": "UserPromptSubmit",
         "post_tool": "PostToolUse",
-        "session_end": "Stop"
+        "session_end": "SessionEnd"
       },
-      "notes": "Codex has no project-scoped hook file, so sync INJECTS absolute-path entries into the per-user ~/.codex/hooks.json on `mise enter` and REMOVES them on `mise leave`. Idempotent; backs up to ~/.codex/hooks.json.caf-bak before first write. Set CAF_HOOKS_SKIP_CODEX=1 to opt out (e.g. if you already run these hooks globally)."
+      "notes": "Native timeouts are seconds. Fanout replaces only this project hook path and suppresses concerns already owned by the activated hub. SessionEnd is true closure; Stop completes a turn."
     },
     "hermes": {
       "enabled": true,
@@ -75,9 +75,9 @@
       "timeout_s": 5,
       "lifecycle_events": {
         "post_tool": "post_tool_call",
-        "session_end": "on_session_end"
+        "session_end": "on_session_finalize"
       },
-      "notes": "Hermes runs hooks shell=False (argv) with the payload as JSON on stdin and requires commands in shell-hooks-allowlist.json. It has NO user-prompt event, so hindsight-recall is not wired. Instead of the Claude-shaped scripts, Hermes uses the ADAPTER (hermes/hindsight-hook.sh) which translates the Hermes payload and pins the project bank (repo basename) (resolve_bank from the runtime cwd would resolve to the PM submodule). sync merges into the per-deployment runtime config.yaml + allowlist (idempotent, backed up, skipped if the runtime is absent). Disable per-dev via local.json disabled_agents:[\"hermes\"]."
+      "notes": "Standalone project fallback adapter. on_session_finalize is true session closure; on_session_end is a turn. The active central hub owns fleet hooks and suppresses this fallback."
     },
     "kimi": {
       "enabled": true,
@@ -89,9 +89,9 @@
       "lifecycle_events": {
         "user_prompt": "UserPromptSubmit",
         "post_tool": "PostToolUse",
-        "session_end": "Stop"
+        "session_end": "SessionEnd"
       },
-      "notes": "Kimi Code CLI hooks live in the per-user ~/.kimi-code/config.toml (KIMI_CODE_HOME overrides) as a `hooks` array of {event,command,matcher?,timeout}. Kimi is Claude-compatible: identical event names, payload {hook_event_name,session_id,cwd,prompt} / {tool_name,tool_input} on stdin, shell:true commands, timeout in SECONDS, edit tools named Write/Edit. So it reuses the SAME scripts (guard-wrapped) as claude/codex. No project-local config.toml exists, so sync INJECTS a sentinel-bounded [[hooks]] block on enter and removes it on leave (idempotent text-merge, backs up to config.toml.caf-bak). Disable per-dev via local.json disabled_agents:[\"kimi\"]."
+      "notes": "Kimi uses ~/.kimi-code/config.toml (or KIMI_CODE_HOME). Native timeouts are seconds. Sentinel-owned fallback hooks are suppressed automatically when the hub owns each concern."
     }
   }
 }

package/templates/commonproject/template/.agents/hooks/lib/hook-guard.sh

@@ -17,6 +17,19 @@ set -uo pipefail
 HOOK_ID="${1:-}"
 shift || true
 
+# A generated project can keep its portable fallback settings in Git while
+# this machine routes the concern centrally. Paused hub concerns remain owned.
+HUB_CONCERN="$HOOK_ID"
+case "$HUB_CONCERN" in
+  skill-check-reminder) HUB_CONCERN=skill-reminder ;;
+  merge-forward-session-rebalance) HUB_CONCERN=merge-forward ;;
+esac
+if [[ "${BB_HOOK_HUB:-}" != "off" && -f "$HOME/.agents/hooks/hub/ownership.py" ]] &&
+   python3 "$HOME/.agents/hooks/hub/ownership.py" "$HUB_CONCERN"; then
+  cat >/dev/null 2>&1 || true
+  exit 0
+fi
+
 # shellcheck source=local-config.sh
 source "$(dirname "${BASH_SOURCE[0]}")/local-config.sh"