kenaz 0.3.2 → 0.3.5

package/core/.formation/bifrost/codex-doctor.js

@@ -40,12 +40,47 @@ function writeIfChanged(f, text) {
   return 'written';
 }
 
+// Global Codex instructions (~/.codex/AGENTS.md, read by every Codex session): a marked Kenaz block,
+// so Codex agents know how to report Kenaz problems (wish / field report) like Claude's /Ansuz does.
+// Only the text between the markers is ours; the user's own content is never touched.
+const AGENTS_BEGIN = '<!-- kenaz:begin (managed by kenaz install; edits here are overwritten) -->';
+const AGENTS_END = '<!-- kenaz:end -->';
+function agentsBlock() {
+  return [AGENTS_BEGIN, '## Kenaz',
+    '- Kenaz tools come from the `kenaz-dashboard` MCP server (kenaz-server on 127.0.0.1:18080); `$kenaz status|init|ygg ...` runs the Kenaz CLI (needs network access to 127.0.0.1).',
+    '- When Kenaz itself blocks or degrades the work (a tool/hook/install/peer/dispatch failure, wrong data, missing capability), call `kenaz_wish_create` BEFORE working around it:',
+    '  projectPath = this project; scope = `kenaz` (Kenaz problem) or `project`; wish_type = `bug` | `feature` | `question`;',
+    '  content = one-line repro + expected vs actual + versions (`npx kenaz doctor` lines) + session id. Never paste keys or tokens.',
+    '  A scope=kenaz wish is sent to the Kenaz team as a field report. Report each problem once, then finish the work with the workaround and tell the user the wish was filed.',
+    AGENTS_END].join('\n');
+}
+function withoutAgentsBlock(text) {
+  const a = text.indexOf(AGENTS_BEGIN), b = text.indexOf(AGENTS_END);
+  if (a < 0 || b < a) return text;
+  return (text.slice(0, a) + text.slice(b + AGENTS_END.length)).replace(/\n{3,}/g, '\n\n').trim() + '\n';
+}
+function installAgentsBlock() {
+  const f = path.join(codexHome(), 'AGENTS.md');
+  const cur = fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '';
+  const base = withoutAgentsBlock(cur).trim();
+  return writeIfChanged(f, (base ? base + '\n\n' : '') + agentsBlock() + '\n');
+}
+function removeAgentsBlock(dryRun) {
+  const f = path.join(codexHome(), 'AGENTS.md');
+  if (!fs.existsSync(f)) return 'absent';
+  const cur = fs.readFileSync(f, 'utf8');
+  if (!cur.includes(AGENTS_BEGIN)) return 'absent';
+  if (!dryRun) { const rest = withoutAgentsBlock(cur); if (rest.trim()) fs.writeFileSync(f, rest); else fs.rmSync(f, { force: true }); }
+  return 'removed';
+}
+
 function installPrompts(core) {
   const f = path.join(codexHome(), 'prompts', 'kenaz.md');
   const skill = path.join(codexHome(), 'skills', 'kenaz', 'SKILL.md');
   const a = writeIfChanged(f, promptText(core));
   const b = writeIfChanged(skill, skillText(core));
-  return { file: f, skill, action: a === 'unchanged' && b === 'unchanged' ? 'unchanged' : 'written' };
+  const c = installAgentsBlock();
+  return { file: f, skill, action: [a, b, c].every((x) => x === 'unchanged') ? 'unchanged' : 'written' };
 }
 
 // Per event: is our shim registered, and does codex hold a trusted_hash for it (hooks.state)?
@@ -95,7 +130,7 @@ function diagnose() {
   return { trust, delivery_mode: deliveryMode(trust), ok: notes.length === 0, notes };
 }
 
-module.exports = { promptText, skillText, installPrompts, hookTrust, deliveryMode, diagnose, SHIM_REL, EVENTS };
+module.exports = { promptText, skillText, installPrompts, installAgentsBlock, removeAgentsBlock, agentsBlock, hookTrust, deliveryMode, diagnose, SHIM_REL, EVENTS };
 
 if (require.main === module) {
   if (process.argv.includes('--install-prompts')) console.log(JSON.stringify(installPrompts()));

package/core/.formation/bifrost/codex-doctor.test.js

@@ -49,3 +49,21 @@ test('shim honours Kenaz mode: off silent, full control still runs', () => {
   assert.strictEqual(off.stderr.includes('event='), false);
   assert.ok(full.stderr.includes('event=SessionStart')); // control: hook does run when not off
 });
+
+test('global AGENTS.md gets one managed Kenaz block (wish / field report guidance); user text kept; removal leaves the rest', () => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cx-agents-'));
+  process.env.CODEX_HOME = home;
+  const f = path.join(home, 'AGENTS.md');
+  fs.writeFileSync(f, '# My own Codex rules\nAlways be terse.\n');
+  D.installAgentsBlock();
+  D.installAgentsBlock(); // idempotent: still one block
+  const t = fs.readFileSync(f, 'utf8');
+  assert.match(t, /Always be terse\./);
+  assert.strictEqual(t.split('kenaz:begin').length - 1, 1);
+  assert.match(t, /kenaz_wish_create/);
+  assert.strictEqual(D.removeAgentsBlock(false), 'removed');
+  const after = fs.readFileSync(f, 'utf8');
+  assert.match(after, /Always be terse\./);
+  assert.doesNotMatch(after, /kenaz:begin|kenaz_wish_create/);
+  delete process.env.CODEX_HOME;
+});

package/core/.formation/bifrost/launch.js

@@ -305,7 +305,7 @@ function writeOverride(prompt, bootContext) {
 
   fs.writeFileSync(OVERRIDE_PATH, content, 'utf8');
 
-  // Write adapter signal file so headless.js knows to route through Bifröst
+  // Write adapter signal file (read by session.js and the Dashboard bifrost-active route)
   const signalPath = path.join(ROOT, '.formation', '.bifrost-active');
   fs.writeFileSync(signalPath, JSON.stringify({ adapter: 'openai', specialist: SPECIALIST, pid: process.pid, started: new Date().toISOString() }));
 

package/core/.formation/bifrost/openai/codex-hook-shim.js

@@ -123,6 +123,11 @@ async function main() {
   try { mode = require(path.resolve(ROOT, 'plugins/kenaz/hooks/mode.js')).resolveMode(p.cwd || process.cwd()); } catch {}
   if (mode === 'off') process.exit(0);
   console.error('[codex-hook-shim] event=' + ev);
+  // Register this project with kenaz-server (idempotent, no-op when known): Codex sessions never run
+  // the Claude turn-context hook, so a Codex-only machine stayed out of its room (field report).
+  const registering = (ev === 'SessionStart' || ev === 'UserPromptSubmit')
+    ? (() => { try { const r = resolvePeerProjectRoot(p.cwd || process.cwd()); return r ? peerRequest('POST', '/api/projects/register', { projectPath: r }) : null; } catch { return null; } })()
+    : null;
   const payload = normalizeHookPayload(p);
   if (ev === 'UserPromptSubmit') {
     payload.specialist = p.specialist || payload.specialist;
@@ -164,6 +169,7 @@ async function main() {
     }).catch(() => {}).finally(() => process.exit(0));
     return; // exit handled by finally above
   }
+  if (registering) await registering; // bounded by PEER_TIMEOUT_MS; fail-open
   process.exit(0);
 }
 

package/core/.formation/bifrost/openai/codex-hook-shim.test.js

@@ -33,7 +33,17 @@ async function fixture({ project, cwd = path.resolve('hook-cwd'), reject = false
         readFileSync: () => { throw new Error('no real state reads'); },
       };
       // TASK_2299 peer pull deps; no KENAZ_PEER_PULL in these fixtures, so no request is expected.
-      if (id === 'http') return { request: () => { effects.http.push('request'); assert.fail('unexpected peer request'); } };
+      // The only request allowed here is the idempotent project registration (SessionStart /
+      // UserPromptSubmit); the fake fails it at once, like a server that is down (fail-open).
+      if (id === 'http') return { request: (opts) => {
+        if (opts && opts.method === 'POST' && opts.path === '/api/projects/register') {
+          effects.http.push('register');
+          const handlers = {};
+          const req = { on: (ev, fn) => { handlers[ev] = fn; return req; }, destroy: () => {}, end: () => { if (handlers.error) handlers.error(new Error('down')); } };
+          return req;
+        }
+        effects.http.push('request'); assert.fail('unexpected peer request');
+      } };
       if (id.endsWith('_peer-project-root.js')) return { resolvePeerProjectRoot: dir => dir };
       if (id === 'child_process') return { execFileSync: () => assert.fail('unexpected child') };
       effects.modules.push(id);

package/core/.formation/bifrost/setup-codex.js

@@ -231,6 +231,9 @@ function uninstall(options = {}) {
   if (res.hooks === 'removed' && !dryRun) fs.writeFileSync(cfg, out.join('\n').replace(/\n{3,}/g, '\n\n'), 'utf8');
   const prompt = path.join(getCodexHome(), 'prompts', 'kenaz.md');
   if (fs.existsSync(prompt)) { res.prompt = 'removed'; if (!dryRun) fs.rmSync(prompt, { force: true }); }
+  const skillDir = path.join(getCodexHome(), 'skills', 'kenaz');
+  if (fs.existsSync(skillDir)) { res.skill = 'removed'; if (!dryRun) fs.rmSync(skillDir, { recursive: true, force: true }); }
+  try { res.agents_md = require('./codex-doctor').removeAgentsBlock(dryRun); } catch (_) { /* doctor optional */ }
   log((dryRun ? 'dry-run: ' : '') + 'codex uninstall ' + JSON.stringify(res));
   return { success: true, ...res };
 }

package/core/.formation/spec/task_operations.parity.test.js

@@ -28,7 +28,6 @@ const PROJECT_ROOT = path.resolve(SPEC_DIR, '../..');
 const FILES = {
   taskApi:     path.join(PROJECT_ROOT, '.collaboration/core/task-api.js'),
   postComplete: path.join(PROJECT_ROOT, '.formation/tools/post-complete/staging.js'),
-  headless:    path.join(PROJECT_ROOT, '.formation/tools/headless.js'),
   kenazRs:     path.join(PROJECT_ROOT, 'dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/kenaz.rs'),
   spec:        path.join(SPEC_DIR, 'task_operations.yaml'),
 };

package/core/.formation/tools/dashboard-models-chain.test.js

@@ -52,9 +52,3 @@ test('control: no project path / absent project file', () => {
     assert.equal(t.utils.loadDashboardModels(t.proj).dispatchModel, 'c'); // project file absent -> core
   } finally { fs.rmSync(t.base, { recursive: true, force: true }); }
 });
-
-test('headless.js derives dispatchModel and agent models from one loadDashboardModels object', () => {
-  const src = fs.readFileSync(path.join(__dirname, 'headless.js'), 'utf8');
-  assert.ok(!src.includes("'dashboard-models.json')"), 'no inline path loops left');
-  assert.match(src, /const _dashboardModels = loadDashboardModels\(projectPath\)/);
-});

package/core/.formation/tools/dispatch-detail/cross-project-worktree.md

@@ -24,17 +24,9 @@ sub-project's shared main tree, which this dispatch must not touch. The
 pre-built worktree path given directly in this prefix is the only correct
 edit target; treat the Project Context path as informational only.
 
-## Why Synapse calls use the main repo path, not the worktree path
-
-Synapse's index is keyed to the project's main repo path. Passing the
-worktree path as `projectPath` would either miss the existing index entirely
-or fragment it across a path that will not exist after the worktree is
-cleaned up. Always pass the main repo path shown in this prefix.
-
 ## Shared rules
 
 Every rule in `.formation/tools/dispatch-detail/worktree-subagent-mode.md`
 (commit-first with telemetry excludes, no long builds, no sleep polling, no
 taskkill by image name, single-task only, no task-api complete) applies here
-identically — the only difference is which absolute path is the edit target
-and which path Synapse calls use.
+identically — the only difference is which absolute path is the edit target.

package/core/.formation/tools/dispatch-detail/worktree-subagent-mode.md

@@ -27,8 +27,8 @@ that worktree hangs waiting for a lock nothing will ever release.
 
 ## Why no long builds / full test suites
 
-Bash foreground calls cap at 10 minutes; a cold Rust build (kuzu's CMake
-alone can run 10+ minutes) gets killed mid-compile. Running it backgrounded
+Bash foreground calls cap at 10 minutes; a cold Rust build
+(can run 10+ minutes) gets killed mid-compile. Running it backgrounded
 instead just produces the orphan-lock problem above, because the previous
 rule (no resuming later) means you have nothing to do but end the turn while
 it's still running. The main thread (Ansuz) has a warm cache, can poll