create-byan-agent 2.29.2 → 2.38.0

package/install/templates/.claude/hooks/punt-guard.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — BYAN punt-guard (F3).
+ *
+ * Goal : catch the laziness pattern where the agent ends its turn by telling the
+ * user to run a command and paste the output back, when the agent could have run
+ * it itself (a Bash tool-call) this turn. The pure detection lives in
+ * lib/punt-detect.js; this hook wires it to the real Stop payload and the arm
+ * flag.
+ *
+ * Ships DISARMED (puntGuard.armed=false in _byan/_config/delivery-default.json),
+ * same posture as the autobench Stop guard. Arming a Stop blocker without first
+ * measuring false positives breaks the flow. So by default the hook only
+ * OBSERVES: it appends one line to _byan-output/punt-ledger.jsonl
+ * (observed-disarmed / observed-disarmed-punt) and exits 0. Only when armed does
+ * it block (exit 2) on a detected punt.
+ *
+ * Carve-out (in punt-detect): git push / npm publish are never flagged — the
+ * server has no creds, so delegating those to the user is legitimate.
+ *
+ * Non-blocking on any IO/parse error : the hook never traps a turn it cannot read.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { decide } = require('./lib/punt-detect');
+const { loadConfig } = require('./lib/delivery-contract');
+// transcript-read is the canonical Stop-payload reader (text + raw content); it
+// does NOT carry stdin helpers, so readStdin/parseJson come from strict-runtime
+// like the other Stop/prompt hooks.
+const { extractLastAssistantText, extractLastAssistantContent } = require('./lib/transcript-read');
+const { readStdin, parseJson } = require('./lib/strict-runtime');
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function isArmed(config) {
+  const pg = config && config.puntGuard;
+  return !!(pg && pg.armed === true);
+}
+
+// Pull the Bash tool-calls out of the finished assistant turn's RAW content.
+// transcript-read gives the block array; a Bash tool_use is
+// { type:'tool_use', name:'Bash', input:{ command } }. Returns [{ name, command }].
+function bashToolCalls(content) {
+  if (!Array.isArray(content)) return [];
+  const out = [];
+  for (const b of content) {
+    if (b && b.type === 'tool_use' && typeof b.name === 'string') {
+      const command = b.input && typeof b.input.command === 'string' ? b.input.command : '';
+      out.push({ name: b.name, command });
+    }
+  }
+  return out;
+}
+
+function ledgerPath() {
+  return path.join(projectRoot(), '_byan-output', 'punt-ledger.jsonl');
+}
+
+function appendLedger(entry) {
+  try {
+    const p = ledgerPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (require.main === module) {
+  (async () => {
+    // Wrap everything : the hook must NEVER trap a turn it cannot read.
+    try {
+      const config = loadConfig(projectRoot());
+      const payload = parseJson(await readStdin());
+      const lastAssistantText = extractLastAssistantText(payload);
+      const toolCallsThisTurn = bashToolCalls(extractLastAssistantContent(payload));
+
+      const result = decide({ lastAssistantText, toolCallsThisTurn });
+      const armed = isArmed(config);
+
+      const event = armed
+        ? result.punt
+          ? 'fired-block'
+          : 'no-punt'
+        : result.punt
+          ? 'observed-disarmed-punt'
+          : 'observed-disarmed';
+
+      appendLedger({
+        event,
+        punt: result.punt,
+        cmd: result.cmd || undefined,
+        reason: result.reason,
+        armed,
+        ts: process.env.BYAN_HOOK_TS || undefined,
+        session: process.env.CLAUDE_SESSION_ID || undefined,
+      });
+
+      if (armed && result.punt) {
+        const reason =
+          `Punt-guard: you asked the user to run "${result.cmd}" and paste the output, ` +
+          `but you did not run it via Bash this turn. Run it yourself, then report the result. ` +
+          `(git push / npm publish are exempt — the server has no creds for those.)`;
+        process.stdout.write(
+          JSON.stringify({ decision: 'block', reason, systemMessage: reason })
+        );
+        process.exit(2);
+      }
+
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    } catch {
+      // Last-resort net : on any unexpected failure, let the turn end.
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    }
+  })();
+}
+
+module.exports = { bashToolCalls, isArmed, ledgerPath, appendLedger };

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

@@ -23,15 +23,38 @@ const { extractLastAssistantText } = require('./lib/transcript-read');
 
 const DEFAULT_MARKERS = ['done', 'finished', 'complete', 'delivered', 'ready'];
 
+// Strip the contexts where a completion marker is a MENTION, not a CLAIM:
+// fenced + inline code, HTML comments (the BYAN-BENCH:done marker lives there),
+// and snake_case / namespaced identifiers (byan_strict_complete, BENCH:done). A
+// marker that survives this strip is prose -- the only place a real "it is done"
+// claim lives. Exported so the regression cases are unit-testable.
+function denoiseForClaim(text) {
+  return String(text)
+    .replace(/```[\s\S]*?```/g, ' ') // fenced code blocks
+    .replace(/`[^`]*`/g, ' ') // inline code spans
+    .replace(/<!--[\s\S]*?-->/g, ' ') // HTML comments (e.g. <!-- BYAN-BENCH:done -->)
+    .replace(/[A-Za-z0-9]+(?:[_:][A-Za-z0-9]+)+/g, ' '); // snake_case / ns identifiers
+}
+
+// A completion marker counts only as a STANDALONE claim, bounded by non-letters
+// (Unicode-aware via the u flag, so "indefini" does not embed "fini" and
+// "determine" does not embed "termine"), with a permissive trailing inflection
+// (livre -> livree / livres). Bias: a false negative is caught by the pre-commit
+// gate (the hard net), while a false positive traps a legitimate turn -- so a
+// marker that is only mentioned is NOT read as a claim.
 function claimsCompletion(text, markers) {
   if (!text) return false;
-  const lower = text.toLowerCase();
+  const clean = denoiseForClaim(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);
+    const marker = String(m).toLowerCase().trim();
+    if (!marker) return false;
+    const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    try {
+      return new RegExp(`(?<![\\p{L}])${escaped}(?:s|e|es|ée|ées|és)?(?![\\p{L}])`, 'iu').test(clean);
+    } catch {
+      // Older runtimes without lookbehind/\p{L} -> fall back to a plain include.
+      return clean.includes(marker);
     }
-    return lower.includes(marker);
   });
 }
 
@@ -85,4 +108,4 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { decideStop, claimsCompletion, extractLastAssistantText };
+module.exports = { decideStop, claimsCompletion, denoiseForClaim, extractLastAssistantText };

package/install/templates/.claude/rules/portable-core.md

@@ -0,0 +1,81 @@
+# BYAN Portable Core — Noyau portable, projection native
+
+> BYAN est livre via npm et tourne sur deux plateformes (Claude Code, Codex).
+> Son identite et son etat doivent survivre a l'absence de toute feature native.
+> Les features natives sont un accelerateur opportuniste, pas une bequille.
+
+## Principe (hexagonal / ports-and-adapters)
+
+Le noyau de BYAN — identite (soul, tao, soul-memory), etat (FD, strict, ELO),
+connaissance — vit dans des artefacts **portables, in-repo**, sous `_byan/` et
+`_byan-output/`, plus l'API `byan_web` quand le reseau est la. Ce noyau est la
+**source de verite**. Il est shippe, il marche offline, il marche sur une machine
+neuve, il marche sur Codex.
+
+Les fonctionnalites natives de la plateforme (Claude Code) sont une **couche
+d'acceleration en write-through** : BYAN ecrit *vers* elles pour en tirer le
+benefice (cache, recall, isolation), mais ne les lit pas comme autorite. Si la
+couche native est absente ou videe, BYAN se reconstruit depuis le noyau portable
+sans rien perdre de son identite ni de son etat.
+
+```
+        +---------------------- noyau portable (source de verite) ----------------------+
+        |  _byan/agent/byan/{soul,tao,soul-memory}.md   _byan-output/fd-state.json       |
+        |  _byan/memoire/{elo,fact-graph}.json          byan_web API (autorite reseau)   |
+        +-------------------------------------------------------------------------------+
+                 |  (write-through, pas une dependance)            ^  (reconstruction)
+                 v                                                |
+        +---------------------- adaptateurs natifs (accelerateurs) ---------------------+
+        |  injection prefix-cache   @-import memory files   hooks   subagent isolation   |
+        +-------------------------------------------------------------------------------+
+```
+
+## Les trois frontieres
+
+1. **Source de verite portable.** Toute chose dont BYAN a besoin pour etre
+   lui-meme est un fichier sous `_byan/` (ou une entree `byan_web`). Rien
+   d'essentiel ne vit uniquement dans une couche native.
+2. **Le natif est un accelerateur write-through.** On projette l'etat portable
+   *vers* le natif pour la vitesse / le cache / le recall. On ne doit pas dependre
+   du natif en lecture pour une fonction essentielle. La projection est derivee et
+   regenerable depuis le noyau.
+3. **L'AutoMem est hors-perimetre.** Le repertoire AutoMem natif de Claude Code
+   (`~/.claude/projects/<hash>/memory/`) est local a l'assistant, par-machine,
+   indexe par un hash du chemin projet — **non shippable** via npm. Il n'est pas
+   une source de verite BYAN, et aucun chemin de lecture critique n'en depend. Ce
+   qui doit etre portable vit dans `soul-memory` / `_byan/`.
+
+## Table : feature native -> adaptateur -> chemin degrade
+
+| Feature native Claude | Adaptateur BYAN (write-through) | Chemin degrade (natif absent / Codex) |
+|-----------------------|--------------------------------|----------------------------------------|
+| Prompt caching (prefixe stable) | `inject-soul.js` / `inject-tao.js` injectent soul+tao depuis `_byan/` au SessionStart | la voix reste lue depuis `_byan/` ; `inject-voice-anchor` re-pose l'ancre par tour |
+| Memory files (`@-import`) | fichiers in-repo (`_byan/`, `.claude/rules/`) charges nativement par Claude | sur Codex, le bloc `AGENTS.md` porte l'equivalent ; les regles restent des fichiers lisibles |
+| Hooks (SessionStart / PreCompact / Stop) | `.claude/hooks/*.js` | sur Codex (pas de hook), le contexte est porte par `AGENTS.md` ; le filet pre-commit reste actif |
+| Subagent isolation | `byan-hermes-dispatch` delegue et ne ramene qu'un distillat | si pas de subagent, execution inline main-thread (meme resultat, plus de tokens) |
+| Compaction | `pre-compact-save.js` ecrit un snapshot sous `_byan-output/` | l'etat FD vit dans `_byan-output/fd-state.json`, relisible sans la couche native |
+
+L'AutoMem n'a **pas** de ligne : ce n'est pas un adaptateur, il est hors-perimetre.
+
+## Le test de degradation (litmus)
+
+L'independance n'est pas une promesse, c'est un test. Wipe la couche native
+(hooks off, `~/.claude/` absent, Codex) : l'identite (soul/tao/soul-memory) et
+l'etat FD doivent se reconstruire depuis les artefacts portables `_byan/` seuls.
+Rebranche le natif : BYAN tourne plus lean (cache, distillat). **Les deux doivent
+tenir.** Garde-fou mecanique : `.claude/__tests__/portable-core.test.js` echoue
+si un chemin critique se met a dependre de l'AutoMem natif.
+
+## Mantras
+
+- `PORTABLE-1` Source de verite in-repo. Le noyau vit sous `_byan/`, pas dans le natif.
+- `PORTABLE-2` Natif = accelerateur, pas une dependance. On ecrit vers, on ne lit pas comme autorite.
+- `PORTABLE-3` AutoMem hors-perimetre. `~/.claude/projects/.../memory/` n'est pas une source BYAN.
+- `PORTABLE-4` Projection derivee. Toute copie native est regenerable depuis le noyau.
+- `PORTABLE-5` Degradation testee. L'independance passe un test, elle ne se decrete pas.
+
+## References
+
+- Doctrine token (pourquoi un pointeur sans `@-import`) : CLAUDE.md, section `## Compact instructions` (chantier context-engineering).
+- Isolation subagent (levier "plus avec moins") : `.claude/skills/byan-hermes-dispatch/SKILL.md`.
+- Etat FD portable : `_byan/mcp/byan-mcp-server/lib/fd-state.js` -> `_byan-output/fd-state.json`.

package/install/templates/.claude/settings.json

@@ -8,6 +8,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-soul.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-tao.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/soul-memory-check.js"
@@ -21,7 +25,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-tao.js"
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-voice-anchor.js"
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-delivery-default.js"
           },
           {
             "type": "command",
@@ -66,6 +74,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/autobench-stop-guard.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/punt-guard.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/drain-advisory.js"

package/install/templates/.claude/skills/byan-hermes-dispatch/SKILL.md

@@ -73,10 +73,12 @@ prompt: |
   Load persona first : read <specialist stub path>.
   Task : <full goal>
   Deliverables : <list>
-  When done, write a concise report (< 200 words).
+  When done, return ONLY a distilled summary (< 200 words, ~1-2k tokens) :
+  the verbose tool output, file contents and intermediate reasoning stay in
+  YOUR context and do not cross back -- only the distillate returns.
 ```
 
-**`mcp-worker`** : same Agent tool call but without `isolation`. Set the Agent's `model` to the returned `model` — `haiku` for exploration nature, otherwise omit `model` to inherit the session model. The tier follows the task nature, not its size.
+**`mcp-worker`** : same Agent tool call but without `isolation` — including the SAME distilled-summary cap in the prompt (the subagent returns only the distillate, not its verbose work). Set the Agent's `model` to the returned `model` — `haiku` for exploration nature, otherwise omit `model` to inherit the session model. The tier follows the task nature, not its size.
 
 For any spawned strategy : pass `model` to the Agent tool when it is non-null; omit it when null so the subagent inherits the session model.
 
@@ -110,9 +112,21 @@ If the user (or calling agent) provides N independent subtasks and `parallelizab
 2. Dispatch all N Agent tool calls **in one message**.
 3. Aggregate via `coordination.aggregate` and `writeSummary`.
 
+## Subagent isolation (token leverage)
+
+A subagent runs in its OWN context window — use that. Let it explore verbosely
+(read files, run tools, reason at length) inside its own context, and have it
+return ONLY a distilled summary (< 200 words, ~1-2k tokens) to the main thread.
+The verbose work does not land in the lead context : this is the Anthropic
+context-isolation principle (a subagent may burn ~9k tokens internally yet return
+~1-2k). It applies to BOTH spawn paths (worktree and mcp-worker), and it is why
+heavy, verbose or exploratory work is worth delegating even when the lead could
+do it inline — the delegation keeps the lead context lean ("plus avec moins").
+
 ## Hard rules
 
 - **Never ask for confirmation** before spawning. User opted into autonomous mode (Q1.b).
 - **Never execute the specialist's work yourself** unless strategy says `main-thread*`. You dispatch, you do not become the specialist.
 - **Never spawn with `isolation: "worktree"` for tasks < score 15** — the boot cost exceeds the gain.
 - **Never fabricate a specialist name**. If no match, say so and use `general-purpose`.
+- **Cap every subagent return.** Both spawn paths (worktree AND mcp-worker) instruct the subagent to return only a distilled summary (< 200 words / ~1-2k tokens) — the raw exploration stays in the subagent's context.

package/install/templates/_byan/_config/delivery-default.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "name": "BYAN Delivery Default",
+  "description": "Makes prod-grade + maximal scope the mechanical default. F1 (the delivery-contract anchor) ships LIVE: it is pure injected context, no risk. F2 (completeness reject) and F3 (punt-guard) ship DISARMED behind armed flags: arming a turn/commit blocker without first measuring false positives would break the flow and could lock an in-progress strict session.",
+  "optOutWords": [
+    "mvp",
+    "quick",
+    "brouillon",
+    "jette",
+    "prototype",
+    "vite fait",
+    "pas besoin que ce soit parfait",
+    "poc",
+    "draft"
+  ],
+  "completenessGate": {
+    "armed": false
+  },
+  "puntGuard": {
+    "armed": false
+  }
+}

package/install/templates/_byan/mcp/byan-mcp-server/channel-entry.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * channel-entry.js — Entrypoint stdio du channel MCP byan pour Claude Code.
+ *
+ * POURQUOI un fichier séparé de server.js : le channel est un serveur MCP
+ * distinct du serveur principal byan-mcp. Claude Code le spawne comme un
+ * subprocess indépendant via --dangerously-load-development-channels.
+ * server.js ne doit pas acquérir le transport channel comme effet de bord.
+ *
+ * Commande de lancement (research preview) :
+ *   claude --dangerously-load-development-channels server:byan-channel
+ *
+ * Enregistrement dans .mcp.json (section mcpServers) — exactement ce que pose
+ * l'installeur : chemin RELATIF au projectRoot (portable, jamais absolu) et env
+ * VIDE (la config est resolue au boot via resolveConfig ci-dessous ; aucun secret
+ * n'est ecrit dans .mcp.json qui est tracke par git) :
+ *   "byan-channel": {
+ *     "command": "node",
+ *     "args": ["_byan/mcp/byan-mcp-server/channel-entry.js"],
+ *     "env": {}
+ *   }
+ *
+ * Voie plugin (Phase 2, non implémentée ici) :
+ *   Wrapper le channel-entry.js dans un plugin Claude Code et l'enregistrer
+ *   dans la marketplace pour qu'il soit accessible via
+ *   --channels plugin:byan-channel@byan-marketplace.
+ *   Nécessite que le channel soit sur l'allowlist Anthropic ou sur la liste
+ *   allowedChannelPlugins de l'organisation (Enterprise).
+ */
+
+import { resolveConfig } from './lib/resolve-config.js';
+import { runChannelStdio } from './lib/channel-server.js';
+
+// Config : même resolver que server.js (env -> ~/.byan/credentials.json -> défauts).
+const config = resolveConfig();
+const apiUrl   = config.BYAN_API_URL   || process.env.BYAN_API_URL;
+const apiToken = config.BYAN_API_TOKEN || process.env.BYAN_API_TOKEN;
+
+if (!apiUrl) {
+  process.stderr.write('[byan-channel] BYAN_API_URL manquant — le poll sera désactivé\n');
+}
+if (!apiToken) {
+  process.stderr.write('[byan-channel] BYAN_API_TOKEN manquant — le poll et les replies seront désactivés\n');
+}
+
+await runChannelStdio({ apiUrl, apiToken });

package/install/templates/_byan/mcp/byan-mcp-server/lib/channel-poll.js

@@ -0,0 +1,128 @@
+/**
+ * lib/channel-poll.js — Boucle de poll outbox byan_web pour le channel CC.
+ *
+ * POURQUOI ce module est séparé de channel-server.js : isoler le réseau
+ * permet de le mocker proprement dans les tests sans toucher au serveur MCP.
+ *
+ * Contrat API (réconcilié avec les routes F2b dans api/routes/sessions-cli.js) :
+ *   GET  /api/sessions/outbox
+ *        -> { data: [{ id, session_id, content, meta? }] }
+ *        Les messages sont scoped au user via le token (RBAC serveur).
+ *   POST /api/sessions/:session_id/outbox/:msg_id/ack
+ *        -> { ok: true }
+ *        Marque le message comme livré ; l'API doit être idempotente.
+ *
+ * Sécurité / gate sender : le poll utilise le token byan_web du user (scope
+ * user). La barrière anti-injection réelle est le RBAC owner côté serveur :
+ * seuls les messages des sessions appartenant à ce user sont dans l'outbox.
+ * Ce module ne filtre pas davantage : le gate est la vraie barrière.
+ */
+
+const DEFAULT_POLL_INTERVAL_MS = 5_000; // 5 s — équilibre réactivité / charge API
+const DEFAULT_TIMEOUT_MS = 8_000;        // abort si l'API ne répond pas
+
+/**
+ * Crée et démarre une boucle de poll vers l'outbox byan_web.
+ *
+ * @param {object} opts
+ * @param {string}   opts.apiUrl          Base URL byan_web (sans /api final)
+ * @param {string}   opts.apiToken        Token byan_web du user (ApiKey scheme)
+ * @param {Function} opts.onMessage       Callback async (msg) => void, appelé pour chaque message pending
+ * @param {number}   [opts.intervalMs]    Intervalle entre polls (défaut 5 s)
+ * @param {object}   [opts.fetchImpl]     Override fetch pour les tests
+ * @returns {{ stop: Function }}          Stopper la boucle
+ */
+export function startPollLoop({ apiUrl, apiToken, onMessage, intervalMs, fetchImpl }) {
+  const interval = intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const fetchFn  = fetchImpl ?? globalThis.fetch;
+
+  let active = true;
+  let timer = null;
+
+  const authHeaders = () => {
+    // byan_web exige ApiKey pour les tokens préfixés byan_, Bearer sinon.
+    const scheme = apiToken && apiToken.startsWith('byan_') ? 'ApiKey' : 'Bearer';
+    return { Authorization: `${scheme} ${apiToken}` };
+  };
+
+  async function poll() {
+    if (!active) return;
+    try {
+      const ctrl = new AbortController();
+      const timeout = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+      let res;
+      try {
+        res = await fetchFn(`${apiUrl}/api/sessions/outbox`, {
+          headers: { ...authHeaders(), 'Content-Type': 'application/json' },
+          signal: ctrl.signal,
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+
+      if (!res.ok) {
+        // Best-effort : ne pas interrompre la boucle sur une erreur transitoire.
+        // 401/403 sont loggés mais pas relancés (le token est fixe dans cette session).
+        if (res.status === 401 || res.status === 403) {
+          process.stderr.write(`[byan-channel] outbox auth error ${res.status} — vérifier BYAN_API_TOKEN\n`);
+        }
+        return;
+      }
+
+      const body = await res.json();
+      const messages = Array.isArray(body?.data) ? body.data : [];
+
+      for (const msg of messages) {
+        if (!msg || !msg.id || !msg.session_id) continue;
+
+        // Livrer le message au channel (notification MCP).
+        try {
+          await onMessage(msg);
+        } catch (err) {
+          process.stderr.write(`[byan-channel] onMessage error: ${err.message}\n`);
+        }
+
+        // Acquitter le message : marque "livré" côté serveur.
+        // Contrat F2b : POST /api/sessions/:session_id/outbox/:msg_id/ack
+        // Idempotent — si l'ack échoue on retente au prochain poll (le message
+        // réapparaît dans l'outbox, ce qui entraîne une double notification).
+        // La double notification est préférable à un message perdu.
+        try {
+          const ackCtrl = new AbortController();
+          const ackTimeout = setTimeout(() => ackCtrl.abort(), DEFAULT_TIMEOUT_MS);
+          try {
+            await fetchFn(
+              `${apiUrl}/api/sessions/${encodeURIComponent(msg.session_id)}/outbox/${encodeURIComponent(msg.id)}/ack`,
+              { method: 'POST', headers: authHeaders(), signal: ackCtrl.signal }
+            );
+          } finally {
+            clearTimeout(ackTimeout);
+          }
+        } catch (ackErr) {
+          // Ack raté = best-effort ; on ne bloque pas la livraison.
+          process.stderr.write(`[byan-channel] ack failed for msg ${msg.id}: ${ackErr.message}\n`);
+        }
+      }
+    } catch (err) {
+      // Réseau injoignable : best-effort, on retente au prochain tick.
+      if (err.name !== 'AbortError') {
+        process.stderr.write(`[byan-channel] poll error: ${err.message}\n`);
+      }
+    } finally {
+      if (active) {
+        // Programmer le prochain poll seulement si la boucle est encore active.
+        timer = setTimeout(poll, interval);
+      }
+    }
+  }
+
+  // Démarrage immédiat puis périodique.
+  timer = setTimeout(poll, 0);
+
+  return {
+    stop() {
+      active = false;
+      if (timer) clearTimeout(timer);
+    },
+  };
+}