create-byan-agent 2.15.0 → 2.17.0

package/install/packages/platform-config/lib/mcp-config.js

@@ -3,7 +3,21 @@
  *
  * READ-MERGE-WRITE semantics : preserves all existing mcpServers.* entries
  * and, if byan entry already exists, preserves its command/args. Only the
- * env.BYAN_API_URL and env.BYAN_API_TOKEN are authoritative from caller.
+ * env.BYAN_API_URL is authoritative from caller.
+ *
+ * Security: BYAN_API_TOKEN is NEVER written into .mcp.json (which is
+ * checked into git). The token lives exclusively in:
+ *   - .env (gitignored, for shell tools and Codex CLI)
+ *   - .claude/settings.local.json (gitignored, for Claude Code MCP injection)
+ *
+ * Claude Code reads .claude/settings.local.json's "env" block at startup and
+ * injects those vars into every MCP server it spawns. So the token reaches
+ * the byan MCP server via that channel — no need to declare it in .mcp.json.
+ *
+ * The `token` parameter on this module's API is kept for backward-compat
+ * but is intentionally discarded (with a one-line audit trail in the
+ * returned result). Callers that supply a token should instead use
+ * envConfig.updateDotenv + envConfig.updateSettingsLocal.
  */
 
 const path = require('path');
@@ -11,6 +25,7 @@ const fs = require('fs-extra');
 const { stripApiSuffix } = require('./url-utils');
 
 const MCP_SERVER_REL_PATH = '_byan/mcp/byan-mcp-server/server.js';
+const TOKEN_PLACEHOLDER = '${BYAN_API_TOKEN}';
 
 async function readJsonOrEmpty(filePath) {
   if (await fs.pathExists(filePath)) {
@@ -43,11 +58,14 @@ async function readMcpConfig(projectRoot) {
  * Pure merge — no I/O. Returns a new config object with byan entry merged.
  * Useful for migrations that inspect the diff before writing.
  *
+ * BYAN_API_TOKEN is intentionally stripped from env (never written into
+ * .mcp.json). See module header for the rationale and the persistence path.
+ *
  * @param {object} existingConfig — current parsed config (may be {} or {mcpServers:{...}})
- * @param {{ apiUrl: string, token?: string }} opts
+ * @param {{ apiUrl: string, token?: string }} opts — `token` is accepted but discarded
  * @returns {object} new merged config
  */
-function mergeByanEntry(existingConfig, { apiUrl, token } = {}) {
+function mergeByanEntry(existingConfig, { apiUrl } = {}) {
   const cfg = existingConfig && typeof existingConfig === 'object' ? { ...existingConfig } : {};
   cfg.mcpServers = { ...(cfg.mcpServers || {}) };
 
@@ -56,11 +74,7 @@ function mergeByanEntry(existingConfig, { apiUrl, token } = {}) {
 
   const env = { ...(existing.env || {}) };
   env.BYAN_API_URL = cleanUrl;
-  if (token && typeof token === 'string' && token.length > 0) {
-    env.BYAN_API_TOKEN = token;
-  } else {
-    delete env.BYAN_API_TOKEN;
-  }
+  delete env.BYAN_API_TOKEN;
 
   cfg.mcpServers.byan = {
     command: 'node',
@@ -87,9 +101,94 @@ async function ensureMcpConfig(projectRoot, { apiUrl, token } = {}) {
   return { path: filePath };
 }
 
+/**
+ * Adds (or replaces) an arbitrary MCP server entry under mcpServers.<name>.
+ * Used by mcp-extensions to register third-party MCPs (gdrive, etc.) without
+ * touching the byan entry. Other entries are preserved.
+ *
+ * Security guard : refuses to write any value matching common token shapes
+ * directly into .mcp.json. Callers must put secrets in .env / settings.local
+ * and reference env-var names elsewhere.
+ *
+ * @param {string} projectRoot
+ * @param {string} name — server identifier (becomes the mcpServers key)
+ * @param {object} entry — { command, args?, env?, ... }
+ * @returns {Promise<{ path: string }>}
+ */
+async function addMcpEntry(projectRoot, name, entry) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('addMcpEntry: name must be a non-empty string');
+  }
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('addMcpEntry: entry must be an object');
+  }
+  assertNoSecretInEntry(entry);
+
+  const filePath = path.join(projectRoot, '.mcp.json');
+  const current = await readJsonOrEmpty(filePath);
+  const cfg = current && typeof current === 'object' ? { ...current } : {};
+  cfg.mcpServers = { ...(cfg.mcpServers || {}) };
+  cfg.mcpServers[name] = entry;
+  await fs.writeJson(filePath, cfg, { spaces: 2 });
+  return { path: filePath };
+}
+
+/**
+ * Removes an MCP server entry. No-op if the entry does not exist.
+ *
+ * @param {string} projectRoot
+ * @param {string} name
+ * @returns {Promise<{ path: string, removed: boolean }>}
+ */
+async function removeMcpEntry(projectRoot, name) {
+  const filePath = path.join(projectRoot, '.mcp.json');
+  const current = await readJsonOrEmpty(filePath);
+  if (!current || !current.mcpServers || !(name in current.mcpServers)) {
+    return { path: filePath, removed: false };
+  }
+  const cfg = { ...current, mcpServers: { ...current.mcpServers } };
+  delete cfg.mcpServers[name];
+  await fs.writeJson(filePath, cfg, { spaces: 2 });
+  return { path: filePath, removed: true };
+}
+
+const SECRET_SHAPES = [
+  /^byan_[a-f0-9]{20,}$/i,                  // byan tokens
+  /^ghp_[A-Za-z0-9]{30,}$/,                 // GitHub PAT
+  /^gho_[A-Za-z0-9]{30,}$/,                 // GitHub OAuth
+  /^github_pat_[A-Za-z0-9_]{60,}$/,         // GitHub PAT (new format)
+  /^sk-ant-[A-Za-z0-9_-]{20,}$/,            // Anthropic
+  /^sk-proj-[A-Za-z0-9_-]{20,}$/,           // OpenAI project
+  /^AIza[0-9A-Za-z_-]{30,}$/,               // Google API key
+  /^xox[bpao]-[0-9]+-[0-9]+-/,              // Slack
+  /^AKIA[0-9A-Z]{16}$/,                     // AWS
+];
+
+function looksLikeSecret(value) {
+  if (typeof value !== 'string') return false;
+  return SECRET_SHAPES.some((re) => re.test(value));
+}
+
+function assertNoSecretInEntry(entry) {
+  const env = (entry && entry.env) || {};
+  for (const [key, val] of Object.entries(env)) {
+    if (looksLikeSecret(val)) {
+      throw new Error(
+        `addMcpEntry: env.${key} looks like a secret. Refusing to write it into .mcp.json. ` +
+          `Put the value in .env (gitignored) and reference it via .claude/settings.local.json env, ` +
+          `or use \${VAR_NAME} if your MCP client supports env-var expansion.`
+      );
+    }
+  }
+}
+
 module.exports = {
   ensureMcpConfig,
   readMcpConfig,
   mergeByanEntry,
+  addMcpEntry,
+  removeMcpEntry,
+  looksLikeSecret,
   MCP_SERVER_REL_PATH,
+  TOKEN_PLACEHOLDER,
 };

package/install/packages/platform-config/lib/validate.js

@@ -24,20 +24,6 @@ async function validateByanWebReachability({ apiUrl, token, timeoutMs = 5000 })
     const latencyMs = Date.now() - t0;
     clearTimeout(timer);
 
-    const ct = (res.headers && typeof res.headers.get === 'function'
-      ? res.headers.get('content-type')
-      : '') || '';
-    const lowerCt = ct.toLowerCase();
-
-    if (lowerCt.includes('text/html')) {
-      return {
-        reachable: false,
-        status: res.status,
-        latencyMs,
-        error: 'Response is HTML — BYAN_API_URL likely points at the WebUI (behind SSO) instead of the API backend. Try byan-api.<domain> without /api suffix.',
-      };
-    }
-
     if (res.status >= 200 && res.status < 400) {
       return { reachable: true, status: res.status, latencyMs };
     }

package/install/src/webui/api.js

@@ -84,6 +84,12 @@ function detectPlatforms(projectRoot) {
 }
 
 const routes = {
+  // Lightweight health-check — used by Electron LocalServer health-ping every 5s.
+  'GET health': async (req, res) => {
+    res.writeHead(200);
+    res.end(JSON.stringify({ ok: true }));
+  },
+
   'GET status': async (req, res, server) => {
     const projectRoot = server.projectRoot;
     const version = readPackageVersion();

package/install/src/webui/server.js

@@ -51,8 +51,15 @@ class ByanWebUI {
 
     return new Promise((resolve) => {
       this.server.listen(this.port, () => {
-        const url = `http://localhost:${this.port}`;
+        const addr = this.server.address();
+        const assignedPort = (addr && typeof addr === 'object') ? addr.port : this.port;
+        const url = `http://localhost:${assignedPort}`;
         console.log(`BYAN WebUI running at ${url}`);
+        // Notify parent Electron process (F3 LocalServer) of the assigned port.
+        // process.send exists only when forked via child_process.fork().
+        if (typeof process.send === 'function') {
+          process.send({ type: 'ready', port: assignedPort });
+        }
         this.openBrowser(url);
         resolve(this);
       });

package/install/templates/.claude/CLAUDE.md

@@ -44,6 +44,7 @@ Voir @.claude/rules/hermes-dispatcher.md pour les commandes Hermes.
 - Methodologie: voir @.claude/rules/merise-agile.md
 - Systeme de confiance epistemique: voir @.claude/rules/elo-trust.md
 - Protocol fact-check scientifique: voir @.claude/rules/fact-check.md
+- Mode strict anti-downgrade: voir @.claude/rules/strict-mode.md
 - Systeme API byan_web: voir @.claude/rules/byan-api.md
 
 ## API byan_web
@@ -73,3 +74,20 @@ Domaines stricts : security/performance/compliance → LEVEL-2 minimum sinon BLO
 
 Agent dédié: `@fact-checker` — analyse assertions, audits de documents, chaines de raisonnement.
 Dans BYAN: tapez `[FC]` pour le sous-menu fact-check.
+
+## BYAN Strict Mode
+
+Mode d'enforcement anti-downgrade : empeche l'agent de livrer moins que demande
+(MVP au lieu de prod, stub au lieu de feature, template bacle). Fonctionne sur
+les 3 plateformes (Claude Code, Codex, Copilot).
+
+Protocole : lock du scope -> build complet -> self-verify >= 3 passes -> complete
+(jeton d'audit). Le commit est bloque tant que la verification n'est pas acquise.
+
+- Source de verite : `_byan/_config/strict-mode.yaml` (regenerer via `byan-sync-rules`)
+- Outils MCP : `byan_strict_lock_scope`, `byan_strict_self_verify`, `byan_strict_complete`, `byan_strict_status`, `byan_strict_abort`, `byan_strict_suggest`
+- Activation : `byan_fd_start strict:true`, skill `byan-strict`, ou mots-cles (prod, client, livrable...)
+- Filet final : `.githooks/pre-commit` bloque le commit si une session strict est engagee mais non completee
+- Persistance : sessions poussees vers l'API byan_web (autorite ; local = miroir/fallback offline)
+
+Detail complet : voir @.claude/rules/strict-mode.md

package/install/templates/.claude/hooks/lib/strict-config.json

@@ -0,0 +1,46 @@
+{
+  "_generated_by": "byan-sync-rules",
+  "version": 1,
+  "min_passes": 3,
+  "last_verdict_must_be": "ok",
+  "min_score": 95,
+  "auto_keywords": [
+    "prod",
+    "production",
+    "client",
+    "contrat",
+    "template officiel",
+    "livrable",
+    "deliverable",
+    "mise en production",
+    "release"
+  ],
+  "completion_claim_markers": [
+    "done",
+    "finished",
+    "complete",
+    "delivered",
+    "ready",
+    "shipped",
+    "terminé",
+    "fini",
+    "livré",
+    "prêt",
+    "c'est bon",
+    "voilà"
+  ],
+  "scope_guard": {
+    "enforce_paths": true,
+    "exempt_globs": [
+      ".byan-strict/",
+      "_byan-output/",
+      ".git/"
+    ]
+  },
+  "freshness_window_seconds": 600,
+  "banners": {
+    "context": "[STRICT MODE ACTIVE]\nYou are under BYAN Strict Mode. Before building:\n  1. Lock the scope (byan_strict_lock_scope) with testable acceptance criteria.\nWhile building:\n  2. Do not downgrade the scope. Surface any gap, do not cut silently.\nBefore delivering:\n  3. Run >= 3 self-verify passes (byan_strict_self_verify), re-reading the\n     original request each time. The last pass must report verdict \"ok\".\n  4. Call byan_strict_complete to earn the audit token.\nHard claims (security/performance/compliance) require LEVEL-1 sourcing (95%).\nA commit without a fresh, matching audit token is blocked by the pre-commit gate.\n",
+    "stop_block": "Strict mode: the turn cannot end. The locked scope has not passed three self-verify passes with a final \"ok\" verdict. Run byan_strict_self_verify until the scope is satisfied, then byan_strict_complete.",
+    "scope_deny": "Strict mode: this write targets a path outside the locked scope. Either it belongs to the scope (re-lock with the corrected paths) or it does not (do not write it)."
+  }
+}

package/install/templates/.claude/hooks/lib/strict-runtime.js

@@ -0,0 +1,82 @@
+// Shared runtime helpers for the BYAN Strict Mode hooks.
+//
+// Reads two files :
+//   - .claude/hooks/lib/strict-config.json : generated from strict-mode.yaml
+//     by byan-sync-rules (static config : thresholds, keywords, banners).
+//   - .byan-strict/state.json : the live session state written by the
+//     byan_strict_* MCP tools (lib/strict-mode.js).
+//
+// Hooks only READ here. The authoritative writes live in the MCP tools.
+
+const fs = require('fs');
+const path = require('path');
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function readJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function loadConfig() {
+  const p = path.join(projectRoot(), '.claude', 'hooks', 'lib', 'strict-config.json');
+  return readJson(p);
+}
+
+function loadState() {
+  const p = path.join(projectRoot(), '.byan-strict', 'state.json');
+  return readJson(p);
+}
+
+// A strict session is "engaged" when it is active, has a locked scope, and
+// has not been completed yet. This is the window where enforcement applies.
+function isEngaged(state) {
+  return Boolean(state && state.active && state.scope_lock && !state.completed);
+}
+
+function passCount(state) {
+  return state && Array.isArray(state.self_verify_passes)
+    ? state.self_verify_passes.length
+    : 0;
+}
+
+function lastVerdict(state) {
+  const passes = state && state.self_verify_passes;
+  if (!Array.isArray(passes) || passes.length === 0) return null;
+  return passes[passes.length - 1].verdict;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+module.exports = {
+  projectRoot,
+  loadConfig,
+  loadState,
+  isEngaged,
+  passCount,
+  lastVerdict,
+  readStdin,
+  parseJson,
+};

package/install/templates/.claude/hooks/strict-context-inject.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — BYAN Strict Mode context injector.
+ *
+ * Two behaviors :
+ *   - When a strict session is engaged, inject the strict banner plus a live
+ *     status line (passes done / required, locked scope hash) so the agent
+ *     stays anchored to the contract on every turn.
+ *   - When no session is engaged but the user's prompt contains an activation
+ *     keyword (prod, production, client, contrat, ...), inject a suggestion to
+ *     lock strict mode before building. It suggests, it does not auto-lock.
+ *
+ * Emits empty context on any error.
+ */
+
+const {
+  loadConfig,
+  loadState,
+  isEngaged,
+  passCount,
+  lastVerdict,
+  readStdin,
+  parseJson,
+} = require('./lib/strict-runtime');
+
+function findKeyword(prompt, keywords) {
+  if (!prompt || !Array.isArray(keywords)) return null;
+  const lower = prompt.toLowerCase();
+  for (const k of keywords) {
+    const kw = String(k).toLowerCase();
+    if (/^[a-z]+$/.test(kw)) {
+      if (new RegExp(`\\b${kw}\\b`).test(lower)) return k;
+    } else if (lower.includes(kw)) {
+      return k;
+    }
+  }
+  return null;
+}
+
+// Pure : returns the additionalContext string (possibly empty).
+function buildContext({ state, config, prompt }) {
+  if (isEngaged(state)) {
+    const minPasses = (config && config.min_passes) || 3;
+    const banner = (config && config.banners && config.banners.context) || '[STRICT MODE ACTIVE]';
+    const done = passCount(state);
+    const hash = state.scope_lock ? state.scope_lock.scope_hash : 'unknown';
+    return (
+      `${banner}\n` +
+      `Locked scope: ${hash} | self-verify ${done}/${minPasses} | last verdict ${lastVerdict(state) || 'none'}.\n` +
+      `Stay inside the locked scope. Do not declare done before byan_strict_complete returns an audit token.`
+    );
+  }
+
+  const keyword = findKeyword(prompt, config && config.auto_keywords);
+  if (keyword) {
+    return (
+      `[STRICT MODE SUGGESTED]\n` +
+      `The request mentions "${keyword}", which signals a production-grade deliverable. ` +
+      `Before building, consider locking strict mode with byan_strict_lock_scope ` +
+      `(verbatim scope + testable acceptance criteria). Strict mode enforces ` +
+      `>= ${(config && config.min_passes) || 3} self-verify passes and a 95% confidence floor on hard claims. ` +
+      `Confirm with the user, then lock.`
+    );
+  }
+
+  return '';
+}
+
+if (require.main === module) {
+  (async () => {
+    const state = loadState();
+    const config = loadConfig();
+    const payload = parseJson(await readStdin());
+    const prompt = payload.prompt || payload.user_prompt || payload.userPrompt || '';
+
+    const additionalContext = buildContext({ state, config, prompt });
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext },
+      })
+    );
+    process.exit(0);
+  })();
+}
+
+module.exports = { buildContext, findKeyword };

package/install/templates/.claude/hooks/strict-scope-guard.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook — BYAN Strict Mode scope guard.
+ *
+ * When a strict session is engaged and the locked scope declares allowed
+ * paths, deny Write/Edit calls that target a file outside those paths. This
+ * keeps the agent inside the contract it locked : it cannot silently spread
+ * changes across the repo under the cover of the locked task.
+ *
+ * Exempt paths (the strict bookkeeping, build output, git) are always
+ * allowed. If enforce_paths is off or no allowed paths were declared, every
+ * write is allowed.
+ *
+ * Non-blocking on parse error.
+ */
+
+const path = require('path');
+const { loadConfig, loadState, isEngaged, projectRoot, readStdin, parseJson } =
+  require('./lib/strict-runtime');
+
+function toRelative(filePath, root) {
+  if (!filePath) return '';
+  const abs = path.isAbsolute(filePath) ? filePath : path.join(root, filePath);
+  const rel = path.relative(root, abs);
+  return rel.split(path.sep).join('/');
+}
+
+function matchesPrefix(rel, prefix) {
+  const p = String(prefix).replace(/\/+$/, '');
+  return rel === p || rel.startsWith(p + '/');
+}
+
+// Pure decision : returns { deny, reason }.
+function decideScope({ state, config, toolName, filePath }) {
+  if (!['Write', 'Edit'].includes(toolName)) return { deny: false };
+  if (!isEngaged(state)) return { deny: false };
+
+  const guard = (config && config.scope_guard) || {};
+  if (!guard.enforce_paths) return { deny: false };
+
+  const allowed = (state.scope_lock && state.scope_lock.allowed_paths) || [];
+  if (!Array.isArray(allowed) || allowed.length === 0) return { deny: false };
+
+  const root = projectRoot();
+  const rel = toRelative(filePath, root);
+  if (!rel) return { deny: false };
+
+  const exempt = guard.exempt_globs || [];
+  if (exempt.some((g) => matchesPrefix(rel, g))) return { deny: false };
+
+  if (allowed.some((a) => matchesPrefix(rel, a))) return { deny: false };
+
+  const base =
+    (config && config.banners && config.banners.scope_deny) ||
+    'Strict mode: this write targets a path outside the locked scope.';
+  const reason =
+    `${base}\n` +
+    `Target: ${rel}\n` +
+    `Locked paths: ${allowed.join(', ')}\n` +
+    `Either this file belongs to the scope (re-lock with byan_strict_lock_scope ` +
+    `including the corrected paths) or it does not (do not write it).`;
+
+  return { deny: true, reason };
+}
+
+function allow() {
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } };
+}
+
+if (require.main === module) {
+  (async () => {
+    const state = loadState();
+    if (!isEngaged(state)) {
+      process.stdout.write(JSON.stringify(allow()));
+      process.exit(0);
+    }
+    const config = loadConfig();
+    const payload = parseJson(await readStdin());
+    const toolName = payload.tool_name || payload.toolName || '';
+    const input = payload.tool_input || payload.toolInput || {};
+    const filePath = input.file_path || '';
+
+    const decision = decideScope({ state, config, toolName, filePath });
+    if (!decision.deny) {
+      process.stdout.write(JSON.stringify(allow()));
+      process.exit(0);
+    }
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: decision.reason,
+        },
+      })
+    );
+    process.exit(0);
+  })();
+}
+
+module.exports = { decideScope, toRelative, matchesPrefix };

package/install/templates/.claude/hooks/strict-stop-guard.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — BYAN Strict Mode end-of-turn guard.
+ *
+ * When a strict session is engaged (active + scope locked + not completed),
+ * block the turn from ending IF the assistant's last message claims the work
+ * is done. Completion must be earned through byan_strict_complete (3 passes,
+ * last verdict "ok"), which flips state.completed and disengages this guard.
+ *
+ * A mid-task yield (asking the user a question, reporting progress without a
+ * completion claim) is allowed — the guard only fires on a premature "done".
+ *
+ * Non-blocking on any IO/parse error : the hook never traps a turn when it
+ * cannot read the state.
+ */
+
+const { loadConfig, loadState, isEngaged, passCount, lastVerdict, readStdin, parseJson } =
+  require('./lib/strict-runtime');
+
+const DEFAULT_MARKERS = ['done', 'finished', 'complete', 'delivered', 'ready'];
+
+function claimsCompletion(text, markers) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return (markers || DEFAULT_MARKERS).some((m) => {
+    const marker = String(m).toLowerCase();
+    if (/^[a-z]+$/.test(marker)) {
+      return new RegExp(`\\b${marker}\\b`).test(lower);
+    }
+    return lower.includes(marker);
+  });
+}
+
+function extractLastAssistantText(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  const tx = payload.transcript || payload.messages || [];
+  if (!Array.isArray(tx)) return '';
+  for (let i = tx.length - 1; i >= 0; i--) {
+    const m = tx[i];
+    if (m && m.role === 'assistant') {
+      if (typeof m.content === 'string') return m.content;
+      if (Array.isArray(m.content)) {
+        return m.content.map((c) => (c && c.text ? c.text : '')).join(' ');
+      }
+    }
+  }
+  return '';
+}
+
+// Pure decision : returns { block, reason }.
+function decideStop({ state, config, lastAssistantText }) {
+  if (!isEngaged(state)) return { block: false };
+
+  const markers = config && config.completion_claim_markers;
+  if (!claimsCompletion(lastAssistantText, markers)) return { block: false };
+
+  const minPasses = (config && config.min_passes) || 3;
+  const done = passCount(state);
+  const verdict = lastVerdict(state);
+
+  // Defensive : if somehow 3 ok passes are recorded but complete() was not
+  // called, still block and tell the agent to call complete.
+  const base =
+    (config && config.banners && config.banners.stop_block) ||
+    'Strict mode: the turn cannot end. The locked scope has not been completed.';
+
+  const reason =
+    `${base}\n` +
+    `Progress: ${done}/${minPasses} self-verify passes, last verdict=${verdict || 'none'}.\n` +
+    `You claimed completion but byan_strict_complete has not produced an audit token. ` +
+    `Run byan_strict_self_verify until the scope is satisfied (last pass verdict "ok"), ` +
+    `then call byan_strict_complete. If the scope changed, re-lock it.`;
+
+  return { block: true, reason };
+}
+
+if (require.main === module) {
+  (async () => {
+    const state = loadState();
+    if (!isEngaged(state)) {
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    }
+    const config = loadConfig();
+    const payload = parseJson(await readStdin());
+    const lastAssistantText = extractLastAssistantText(payload);
+
+    const decision = decideStop({ state, config, lastAssistantText });
+    if (!decision.block) {
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    }
+    process.stdout.write(
+      JSON.stringify({ decision: 'block', reason: decision.reason, systemMessage: decision.reason })
+    );
+    process.exit(2);
+  })();
+}
+
+module.exports = { decideStop, claimsCompletion, extractLastAssistantText };