@sienklogic/plan-build-run 2.61.0 → 2.62.0

package/plugins/pbr/scripts/check-subagent-output.js

@@ -549,5 +549,93 @@ async function main() {
   process.exit(0);
 }
 
-module.exports = { AGENT_OUTPUTS, SKILL_CHECKS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent, getCurrentPhase, checkRoadmapStaleness };
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, cache }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {Promise<{ additionalContext: string }|null>}
+ */
+async function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  const agentType = data.agent_type || data.tool_input?.subagent_type || data.subagent_type || '';
+  const outputSpec = AGENT_OUTPUTS[agentType];
+  if (!outputSpec) {
+    const shortName = agentType.startsWith('pbr:') ? agentType.slice(4) : agentType;
+    if (KNOWN_AGENTS && KNOWN_AGENTS.includes && KNOWN_AGENTS.includes(shortName)) {
+      logHook('check-subagent-output', 'PostToolUse', 'missing-output-spec', {
+        agent_type: agentType,
+        message: `Agent ${agentType} is in KNOWN_AGENTS but has no AGENT_OUTPUTS entry. Add one to check-subagent-output.js.`
+      });
+    }
+    return null;
+  }
+
+  let activeSkill = sessionLoad(planningDir).activeSkill || '';
+  if (!activeSkill) {
+    try { activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
+  }
+
+  const found = outputSpec.check(planningDir);
+  const genericMissing = found.length === 0 && !outputSpec.noFileExpected;
+  const skillWarnings = [];
+
+  if (!activeSkill && agentType !== 'pbr:general' && agentType !== 'pbr:plan-checker' && agentType !== 'pbr:integration-checker') {
+    skillWarnings.push('.active-skill file is missing — the orchestrating skill never wrote it. This means skill-workflow guards were inactive for this entire operation. CRITICAL: Write the skill name to .planning/.active-skill BEFORE spawning agents.');
+  }
+
+  if (agentType === 'pbr:executor' || agentType === 'pbr:verifier') {
+    const roadmapWarning = checkRoadmapStaleness(planningDir);
+    if (roadmapWarning) skillWarnings.push(roadmapWarning);
+  }
+
+  if (found._stale && (agentType === 'pbr:researcher' || agentType === 'pbr:synthesizer')) {
+    const label = agentType === 'pbr:researcher' ? 'Researcher' : 'Synthesizer';
+    skillWarnings.push(`${label} output may be stale — no recent output files detected.`);
+  }
+
+  const skillCheckKey = `${activeSkill}:${agentType}`;
+  const skillCheck = SKILL_CHECKS[skillCheckKey];
+  if (skillCheck) skillCheck.check(planningDir, found, skillWarnings);
+
+  // LLM classification helper (advisory, never throws)
+  async function getLlmNote() {
+    try {
+      const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+      const llmConfig = loadLocalLlmConfig(cwd);
+      const errorText = (data.tool_output || '').substring(0, 500);
+      if (!errorText) return '';
+      const llmResult = await classifyError(llmConfig, planningDir, errorText, agentType, data.session_id);
+      if (llmResult && llmResult.category) {
+        return `\nLLM error category: ${llmResult.category} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+      }
+    } catch (_e) { /* never propagate */ }
+    return '';
+  }
+
+  if (genericMissing && skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', { skill: activeSkill, agent_type: agentType, warnings: skillWarnings });
+    const llmCategoryNote = await getLlmNote();
+    const msg = `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found.\nSkill-specific warnings:\n` +
+      skillWarnings.map(w => `- ${w}`).join('\n') + llmCategoryNote;
+    return { additionalContext: msg };
+  } else if (genericMissing) {
+    logHook('check-subagent-output', 'PostToolUse', 'warning', { agent_type: agentType, expected: outputSpec.description, found: 'none' });
+    const llmCategoryNote = await getLlmNote();
+    return {
+      additionalContext: `[WARN] Agent ${agentType} completed but no ${outputSpec.description} was found. Likely causes: (1) agent hit an error mid-run, (2) wrong working directory. To fix: re-run the parent skill — the executor gate will block until the output is present. Check the Task() output above for error details.` + llmCategoryNote
+    };
+  } else if (skillWarnings.length > 0) {
+    logHook('check-subagent-output', 'PostToolUse', 'skill-warning', { skill: activeSkill, agent_type: agentType, warnings: skillWarnings });
+    return { additionalContext: 'Skill-specific warnings:\n' + skillWarnings.map(w => `- ${w}`).join('\n') };
+  } else {
+    logHook('check-subagent-output', 'PostToolUse', 'verified', { agent_type: agentType, found: found });
+    return null;
+  }
+}
+
+module.exports = { AGENT_OUTPUTS, SKILL_CHECKS, findInPhaseDir, findInQuickDir, checkSummaryCommits, isRecent, getCurrentPhase, checkRoadmapStaleness, handleHttp };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/config-schema.json

@@ -311,6 +311,30 @@
       },
       "additionalProperties": false
     },
+    "hook_server": {
+      "type": "object",
+      "description": "Persistent HTTP hook server settings. When enabled, hooks POST to the server instead of spawning per-hook processes.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, hook-server-client.js routes hook events to the persistent hook-server.js process."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 65535,
+          "default": 19836,
+          "description": "TCP port the hook server listens on (127.0.0.1 only)."
+        },
+        "event_log": {
+          "type": "boolean",
+          "default": true,
+          "description": "When true, all hook events are appended to .planning/.hook-events.jsonl."
+        }
+      },
+      "additionalProperties": false
+    },
     "local_llm": {
       "type": "object",
       "properties": {

package/plugins/pbr/scripts/context-bridge.js

@@ -239,6 +239,21 @@ function main() {
           source: 'bridge'
         });
         process.stdout.write(JSON.stringify(output));
+        process.exit(0);
+      }
+
+      // For Write|Edit tools, also run suggest-compact check in-process
+      // (eliminates a separate Node process spawn per Write/Edit).
+      // Detect Write|Edit by presence of file_path in tool_input.
+      const toolInput = data.tool_input || {};
+      if (toolInput.file_path || toolInput.path) {
+        try {
+          const { checkCompaction } = require('./suggest-compact');
+          const compactResult = checkCompaction(planningDir, cwd);
+          if (compactResult) {
+            process.stdout.write(JSON.stringify(compactResult));
+          }
+        } catch (_e) { /* best-effort — never block on compact check */ }
       }
 
       process.exit(0);
@@ -249,6 +264,49 @@ function main() {
   });
 }
 
+/**
+ * HTTP handler for hook-server.js.
+ * Called directly instead of spawning a subprocess.
+ *
+ * @param {Object} reqBody - Full hook request body { event, tool, data, planningDir, cache }
+ * @param {Object} _cache - Server in-memory cache (unused by this handler)
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody, _cache) {
+  try {
+    const planningDir = reqBody.planningDir;
+    const data = reqBody.data || {};
+    if (!planningDir || !fs.existsSync(planningDir)) {
+      return null;
+    }
+
+    const { output } = updateBridge(planningDir, data);
+
+    if (output) {
+      logHook('context-bridge', 'PostToolUse', 'warn', {
+        percent: output.additionalContext.match(/(\d+)%/)?.[1],
+        source: 'bridge'
+      });
+    }
+
+    // For Write|Edit tools, also run suggest-compact check in-process
+    const toolInput = data.tool_input || {};
+    if (!output && (toolInput.file_path || toolInput.path)) {
+      try {
+        const { checkCompaction } = require('./suggest-compact');
+        const compactResult = checkCompaction(planningDir, reqBody.planningDir ? reqBody.planningDir.replace(/[/\\]\.planning$/, '') : process.cwd());
+        if (compactResult) {
+          return compactResult;
+        }
+      } catch (_e) { /* best-effort — never block on compact check */ }
+    }
+
+    return output || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
 module.exports = {
   getTier,
   loadBridge,
@@ -256,6 +314,7 @@ module.exports = {
   estimateFromHeuristic,
   shouldWarn,
   updateBridge,
+  handleHttp,
   TIERS,
   TIER_MESSAGES,
   DEBOUNCE_INTERVAL,

package/plugins/pbr/scripts/context-budget-check.js

@@ -298,5 +298,69 @@ function buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighl
   return parts.length > 2 ? parts.join('\n') : '';
 }
 
-module.exports = { readRoadmapSummary, readCurrentPlan, readConfigHighlights, buildRecoveryContext, readRecentErrors, readRecentAgents };
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  const planningDir = reqBody && reqBody.planningDir;
+  const stateFile = planningDir && path.join(planningDir, 'STATE.md');
+
+  if (!stateFile || !fs.existsSync(stateFile)) return null;
+
+  try {
+    let content = fs.readFileSync(stateFile, 'utf8');
+    const timestamp = new Date().toISOString();
+
+    const activeOp = readActiveOperation(planningDir);
+    const roadmapSummary = readRoadmapSummary(planningDir);
+    const currentPlan = readCurrentPlan(planningDir, content);
+    const configHighlights = readConfigHighlights(planningDir);
+    const recentErrors = readRecentErrors(planningDir, 3);
+    const recentAgents = readRecentAgents(planningDir, 5);
+
+    const continuityParts = [
+      `Last session: ${timestamp}`,
+      'Compaction occurred: context was auto-compacted at this point'
+    ];
+    if (activeOp) continuityParts.push(`Active operation at compaction: ${activeOp}`);
+    if (roadmapSummary) continuityParts.push(`Roadmap progress:\n${roadmapSummary}`);
+    if (currentPlan) continuityParts.push(`Current plan: ${currentPlan}`);
+    if (configHighlights) continuityParts.push(`Config: ${configHighlights}`);
+    if (recentErrors.length > 0) continuityParts.push(`Recent errors:\n${recentErrors.map(e => '  - ' + e).join('\n')}`);
+    if (recentAgents.length > 0) continuityParts.push(`Recent agents: ${recentAgents.join(', ')}`);
+    continuityParts.push('Note: Some conversation context may have been lost. Check STATE.md and SUMMARY.md files for ground truth.');
+
+    const continuityHeader = '## Session Continuity';
+    const continuityContent = continuityParts.join('\n');
+
+    if (content.includes(continuityHeader)) {
+      content = content.replace(
+        /## Session Continuity[\s\S]*?(?=\n## |\n---|\s*$)/,
+        () => `${continuityHeader}\n${continuityContent}\n`
+      );
+    } else {
+      content = content.trimEnd() + `\n\n${continuityHeader}\n${continuityContent}\n`;
+    }
+
+    lockedFileUpdate(stateFile, () => content);
+
+    const recoveryContext = buildRecoveryContext(activeOp, roadmapSummary, currentPlan, configHighlights, recentErrors, recentAgents);
+    if (recoveryContext) {
+      logHook('context-budget-check', 'PreCompact', 'saved', {
+        stateFile: 'STATE.md',
+        hasRoadmap: !!roadmapSummary,
+        hasPlan: !!currentPlan,
+        hasConfig: !!configHighlights
+      });
+      return { additionalContext: recoveryContext };
+    }
+  } catch (e) {
+    logHook('context-budget-check', 'PreCompact', 'error', { error: e.message });
+  }
+  return null;
+}
+
+module.exports = { readRoadmapSummary, readCurrentPlan, readConfigHighlights, buildRecoveryContext, readRecentErrors, readRecentAgents, handleHttp };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/enforce-pbr-workflow.js

@@ -21,7 +21,6 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
-const { sessionLoad } = require('./pbr-tools');
 
 /**
  * Load the enforcement configuration from .planning/config.json.
@@ -75,6 +74,7 @@ function checkUnmanagedSourceWrite(data) {
   if (!fs.existsSync(planningDir)) return null;
 
   // Skip if a PBR skill is active — try .session.json first, fall back to legacy .active-skill
+  const { sessionLoad } = require('./pbr-tools');
   let activeSkill = sessionLoad(planningDir).activeSkill || '';
   if (!activeSkill) {
     try { activeSkill = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }
@@ -240,6 +240,7 @@ function checkUnmanagedCommit(data) {
   if (!fs.existsSync(planningDir)) return null;
 
   // Skip if a PBR skill is active — try .session.json first, fall back to legacy .active-skill
+  const { sessionLoad } = require('./pbr-tools');
   let activeSkillCommit = sessionLoad(planningDir).activeSkill || '';
   if (!activeSkillCommit) {
     try { activeSkillCommit = fs.readFileSync(path.join(planningDir, '.active-skill'), 'utf8').trim(); } catch (_) { /* legacy file missing */ }

package/plugins/pbr/scripts/event-handler.js

@@ -158,5 +158,53 @@ function main() {
   process.exit(0);
 }
 
-module.exports = { isExecutorAgent, shouldAutoVerify, getPhaseFromState };
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, ... }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {{ additionalContext: string }|null}
+ */
+function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+
+  if (!isExecutorAgent(data)) return null;
+
+  const agentType = data.agent_type || data.subagent_type;
+  logHook('event-handler', 'SubagentStop', 'executor-complete', { agent_type: agentType });
+  logEvent('workflow', 'executor-complete', { agent_type: agentType });
+
+  const planningDir = reqBody.planningDir;
+  if (!planningDir || !fs.existsSync(planningDir)) return null;
+
+  if (!shouldAutoVerify(planningDir)) {
+    logHook('event-handler', 'SubagentStop', 'skip-verify', { reason: 'config/depth' });
+    return null;
+  }
+
+  const stateInfo = getPhaseFromState(planningDir);
+  if (!stateInfo || stateInfo.status !== 'building') {
+    logHook('event-handler', 'SubagentStop', 'skip-verify', {
+      reason: stateInfo ? `status=${stateInfo.status}` : 'no-state'
+    });
+    return null;
+  }
+
+  writeAutoVerifySignal(planningDir, stateInfo.phase);
+
+  const lastMsg = data.last_assistant_message || '';
+  let verifyHint = '';
+  if (lastMsg) {
+    const lowerMsg = lastMsg.toLowerCase();
+    if (lowerMsg.includes('error') || lowerMsg.includes('failed') || lowerMsg.includes('warning')) {
+      verifyHint = ' Note: executor output mentions errors/warnings — verification should pay close attention.';
+    }
+  }
+
+  return {
+    additionalContext: `Executor complete. Auto-verification queued for Phase ${stateInfo.phase}.${verifyHint}`
+  };
+}
+
+module.exports = { isExecutorAgent, shouldAutoVerify, getPhaseFromState, handleHttp };
 if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/hook-server-client.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+/**
+ * hook-server-client.js — Thin HTTP client for the PBR hook server.
+ *
+ * Reads hook input from stdin (JSON), POSTs it to the local hook server,
+ * and relays the server response to stdout.
+ *
+ * Fail-open by design: if the server is not reachable or any error occurs,
+ * the client exits 0 (allowing the hook to pass through silently).
+ *
+ * Usage (called by hooks.json commands):
+ *   node hook-server-client.js <hook-name> [port]
+ *
+ * Arguments:
+ *   argv[2]  Hook name (e.g. "track-context-budget")
+ *   argv[3]  Server port (default: 19836)
+ */
+
+'use strict';
+
+const http = require('http');
+const net = require('net');
+
+const DEFAULT_PORT = 19836;
+
+// ---------------------------------------------------------------------------
+// HOOK_EVENT_MAP: maps hook script names to { event, tool } pairs
+// ---------------------------------------------------------------------------
+
+const HOOK_EVENT_MAP = {
+  'track-context-budget': { event: 'PostToolUse',        tool: 'Read'  },
+  'context-bridge':       { event: 'PostToolUse',        tool: 'Write' },
+  'post-write-dispatch':  { event: 'PostToolUse',        tool: 'Write' },
+  'post-bash-triage':     { event: 'PostToolUse',        tool: 'Bash'  },
+  'check-subagent-output':{ event: 'PostToolUse',        tool: 'Task'  },
+  'log-tool-failure':     { event: 'PostToolUseFailure', tool: '*'     },
+  'log-subagent-start':   { event: 'SubagentStart',      tool: '*'     },
+  'log-subagent':         { event: 'SubagentStop',       tool: '*'     },
+  'event-handler':        { event: 'SubagentStop',       tool: '*'     },
+  'task-completed':       { event: 'TaskCompleted',      tool: '*'     },
+  'context-budget-check': { event: 'PreCompact',         tool: '*'     },
+  'instructions-loaded':  { event: 'InstructionsLoaded', tool: '*'     },
+  'check-config-change':  { event: 'ConfigChange',       tool: '*'     },
+  'session-cleanup':      { event: 'SessionEnd',         tool: '*'     },
+  'worktree-create':      { event: 'WorktreeCreate',     tool: '*'     },
+  'worktree-remove':      { event: 'WorktreeRemove',     tool: '*'     }
+};
+
+// ---------------------------------------------------------------------------
+// TCP probe — check if server port is open before committing to an HTTP call
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe whether the given port is accepting connections on 127.0.0.1.
+ * @param {number} port
+ * @param {number} [timeoutMs=200]
+ * @returns {Promise<boolean>}
+ */
+function probePort(port, timeoutMs) {
+  timeoutMs = timeoutMs || 200;
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    function done(result) {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    }
+
+    socket.setTimeout(timeoutMs);
+    socket.connect(port, '127.0.0.1', () => done(true));
+    socket.on('error', () => done(false));
+    socket.on('timeout', () => done(false));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP POST to hook server
+// ---------------------------------------------------------------------------
+
+/**
+ * POST payload to http://127.0.0.1:{port}/hook
+ * @param {number} port
+ * @param {string} body - JSON string
+ * @param {number} [timeoutMs=200]
+ * @returns {Promise<string>} Response body text
+ */
+function postHook(port, body, timeoutMs) {
+  timeoutMs = timeoutMs || 200;
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: '127.0.0.1',
+      port,
+      path: '/hook',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body)
+      }
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => resolve(data));
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error('request timeout'));
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const hookName = process.argv[2] || '';
+  const port = parseInt(process.argv[3], 10) || DEFAULT_PORT;
+
+  // Read stdin
+  let stdinData = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    stdinData += chunk;
+  }
+
+  // Parse stdin as JSON (fail-open on bad input)
+  let inputData;
+  try {
+    inputData = JSON.parse(stdinData);
+  } catch (_e) {
+    process.exit(0);
+    return;
+  }
+
+  // Resolve event/tool from hook name
+  const mapping = HOOK_EVENT_MAP[hookName];
+  if (!mapping) {
+    // Unknown hook — pass through silently
+    process.exit(0);
+    return;
+  }
+
+  // Probe port before attempting HTTP call
+  let reachable = false;
+  try {
+    reachable = await probePort(port, 200);
+  } catch (_e) {
+    reachable = false;
+  }
+
+  if (!reachable) {
+    // Server not running — fail-open
+    process.exit(0);
+    return;
+  }
+
+  // Build request payload
+  const payload = JSON.stringify({
+    event: mapping.event,
+    tool: mapping.tool,
+    data: inputData
+  });
+
+  // POST to hook server
+  let responseText = '';
+  try {
+    responseText = await postHook(port, payload, 200);
+  } catch (_e) {
+    process.exit(0);
+    return;
+  }
+
+  // Parse and relay response
+  let response;
+  try {
+    response = JSON.parse(responseText);
+  } catch (_e) {
+    process.exit(0);
+    return;
+  }
+
+  // Relay additionalContext or decision/reason to Claude Code via stdout
+  if (response.additionalContext || response.decision !== undefined) {
+    const out = {};
+    if (response.additionalContext) out.additionalContext = response.additionalContext;
+    if (response.decision !== undefined) {
+      out.decision = response.decision;
+      if (response.reason !== undefined) out.reason = response.reason;
+    }
+    process.stdout.write(JSON.stringify(out));
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => {
+  // Fail-open on any unhandled error
+  process.exit(0);
+});
+
+module.exports = { probePort, postHook, HOOK_EVENT_MAP, DEFAULT_PORT };