create-byan-agent 2.35.0 → 2.38.0

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);
+    },
+  };
+}

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

@@ -0,0 +1,234 @@
+/**
+ * lib/channel-server.js — Serveur MCP channel Claude Code pour byan_web.
+ *
+ * POURQUOI ce fichier est une factory et non un entrypoint direct :
+ * la même factory est importée par channel-entry.js (entrypoint stdio pour
+ * --dangerously-load-development-channels) ET par les tests, sans effet de
+ * bord transport au import-time.
+ *
+ * Protocole Channel (research preview CC v2.1.80+) :
+ *   - capabilities.experimental['claude/channel'] = {}
+ *     -> CC enregistre un listener de notification
+ *   - mcp.notification({ method: 'notifications/claude/channel', params })
+ *     -> event injecté dans la session CC comme <channel source="byan" ...>
+ *   - reply tool "byan_session_reply" (capabilities.tools = {})
+ *     -> CC appelle le tool quand Claude veut répondre
+ *
+ * Gate sender : le poll utilise BYAN_API_TOKEN (scope user). La barrière
+ * anti-injection est le RBAC owner côté serveur byan_web ; ce channel ne
+ * reçoit que les messages des sessions du user authentifié.
+ */
+
+import { Server }              from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { startPollLoop } from './channel-poll.js';
+
+/** Intervalle de poll par défaut (ms). Exposé pour override dans les tests. */
+export const DEFAULT_POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Reply tool : Claude l'appelle pour renvoyer une réponse vers byan_web.
+ *
+ * Hypothèse F2b : POST /api/sessions/:session_id/reply { content }
+ *   -> { ok: true }
+ * Le nom du tool côté CC sera mcp__byan-channel__byan_session_reply.
+ */
+const REPLY_TOOL = {
+  name: 'byan_session_reply',
+  description:
+    'Reply to a user message received from byan_web. Call this when a <channel source="byan"> event arrives and a response is expected. Pass the session_id from the event meta attribute and the text to send back.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      session_id: {
+        type: 'string',
+        description: 'The session_id from the inbound <channel> event meta.',
+      },
+      content: {
+        type: 'string',
+        description: 'The reply text to send back to the user in byan_web.',
+      },
+    },
+    required: ['session_id', 'content'],
+    additionalProperties: false,
+  },
+};
+
+/**
+ * Crée un serveur MCP channel byan sans le connecter (transport séparé).
+ * Accepte un fetchImpl pour permettre le mock en test.
+ *
+ * @param {object} opts
+ * @param {string}   opts.apiUrl        Base URL byan_web
+ * @param {string}   opts.apiToken      Token du user (ApiKey scheme si préfixe byan_)
+ * @param {number}   [opts.intervalMs]  Override intervalle de poll (tests)
+ * @param {object}   [opts.fetchImpl]   Override fetch (tests)
+ * @returns {Server} Instance MCP Server (non connectée)
+ */
+export function createChannelServer({ apiUrl, apiToken, intervalMs, fetchImpl } = {}) {
+  const fetchFn    = fetchImpl ?? globalThis.fetch;
+  const interval   = intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+
+  const authHeader = () => {
+    if (!apiToken) return {};
+    const scheme = apiToken.startsWith('byan_') ? 'ApiKey' : 'Bearer';
+    return { Authorization: `${scheme} ${apiToken}` };
+  };
+
+  const mcp = new Server(
+    { name: 'byan-channel', version: '0.1.0' },
+    {
+      capabilities: {
+        // Clé qui fait de ce serveur un channel CC.
+        // CC enregistre un listener de notification sur cette capability.
+        experimental: { 'claude/channel': {} },
+        // tools: {} requis pour que CC découvre les tools de réponse.
+        tools: {},
+      },
+      // Instructions injectées dans le system prompt CC.
+      // Dis à Claude : les events arrivent comme <channel source="byan" ...>,
+      // il doit répondre via byan_session_reply en passant session_id.
+      instructions:
+        'Events from byan_web arrive as <channel source="byan" session_id="..." msg_id="...">. ' +
+        'When a user message arrives, read it and reply using the byan_session_reply tool, ' +
+        'passing the session_id from the tag attribute. ' +
+        'Do not reply if the event is a system notification (no reply expected).',
+    }
+  );
+
+  // Découverte des tools par CC.
+  mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [REPLY_TOOL],
+  }));
+
+  // Appel du reply tool par Claude.
+  mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+
+    if (name === 'byan_session_reply') {
+      const { session_id, content } = args;
+      if (!session_id || !content) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: 'Error: session_id and content are required.' }],
+        };
+      }
+      if (!apiToken) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: 'Error: BYAN_API_TOKEN is not configured.' }],
+        };
+      }
+
+      // Hypothèse F2b : POST /api/sessions/:session_id/reply { content }
+      try {
+        const ctrl = new AbortController();
+        const timeout = setTimeout(() => ctrl.abort(), 8_000);
+        let res;
+        try {
+          res = await fetchFn(
+            `${apiUrl}/api/sessions/${encodeURIComponent(session_id)}/reply`,
+            {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                ...authHeader(),
+              },
+              body: JSON.stringify({ content }),
+              signal: ctrl.signal,
+            }
+          );
+        } finally {
+          clearTimeout(timeout);
+        }
+
+        if (!res.ok) {
+          const text = await res.text().catch(() => '');
+          return {
+            isError: true,
+            content: [{ type: 'text', text: `Error: byan_web replied ${res.status} — ${text}` }],
+          };
+        }
+
+        return { content: [{ type: 'text', text: JSON.stringify({ ok: true, session_id }) }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Error sending reply: ${err.message}` }],
+        };
+      }
+    }
+
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+    };
+  });
+
+  // Boucle de poll : démarrée après la connexion transport pour que
+  // mcp.notification() ait un transport actif. La connexion est gérée par
+  // l'entrypoint ; ici on expose startPolling() pour que l'entrypoint
+  // démarre la boucle au bon moment.
+  let pollLoop = null;
+
+  /**
+   * Démarre la boucle de poll. Appeler APRÈS mcp.connect(transport).
+   * Retourne { stop } pour arrêter proprement.
+   */
+  function startPolling() {
+    if (!apiUrl || !apiToken) {
+      process.stderr.write(
+        '[byan-channel] BYAN_API_URL ou BYAN_API_TOKEN manquant — poll désactivé\n'
+      );
+      return { stop: () => {} };
+    }
+
+    pollLoop = startPollLoop({
+      apiUrl,
+      apiToken,
+      intervalMs: interval,
+      fetchImpl: fetchFn,
+      onMessage: async (msg) => {
+        // Émettre la notification CC pour chaque message outbox.
+        // meta : chaque clé devient un attribut sur le tag <channel>.
+        // Les clés contenant des tirets sont silencieusement ignorées par CC
+        // (constraint doc) ; on n'utilise que des underscores.
+        await mcp.notification({
+          method: 'notifications/claude/channel',
+          params: {
+            content: msg.content ?? '',
+            meta: {
+              session_id: String(msg.session_id),
+              msg_id:     String(msg.id),
+              ...(msg.meta && typeof msg.meta === 'object' ? msg.meta : {}),
+            },
+          },
+        });
+      },
+    });
+
+    return pollLoop;
+  }
+
+  // Attache startPolling sur le serveur pour l'entrypoint.
+  mcp.startPolling = startPolling;
+
+  return mcp;
+}
+
+/**
+ * Lance le channel en mode stdio (entrypoint direct).
+ * Appelé uniquement depuis channel-entry.js, pas depuis les tests.
+ */
+export async function runChannelStdio({ apiUrl, apiToken, intervalMs, fetchImpl } = {}) {
+  const mcp = createChannelServer({ apiUrl, apiToken, intervalMs, fetchImpl });
+  await mcp.connect(new StdioServerTransport());
+  // La boucle de poll démarre APRÈS connect pour que la notification
+  // ait un transport actif.
+  mcp.startPolling();
+  // Le process reste vivant grâce au transport stdio.
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/completeness-evidence.js

@@ -0,0 +1,159 @@
+// BYAN completeness-evidence (F2).
+//
+// Strict mode already forces >= 3 self-verify passes whose verdict is the
+// agent's word. This module adds an EVIDENCE layer on top: for each locked
+// acceptance criterion it classifies the criterion (code-shaped vs prose) and
+// collects whatever objective proof is available — a captured test-runner exit,
+// a `git diff --stat` constrained to the allowedPaths, or the existence of a
+// named file. The result is { perCriterion, missing }.
+//
+// It ships DISARMED. The strict complete() ATTACHES this report (so the agent
+// and the audit trail see it) but only HARD-REJECTS when
+// delivery-default.json completenessGate.armed === true (default false). With
+// armed=false the report is pure observation: complete() behaves exactly as
+// before. This is the same disarmed-net posture as the autobench Stop guard.
+//
+// The risky-but-pure half (classification, the report shape, the missing list)
+// takes no I/O. The I/O half (running git, reading files) is injected via an
+// `io` object so the unit tests pin behaviour without touching the real
+// filesystem or spawning git — the same shape strict-sync / suitability-store use.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// A criterion is "code-shaped" when it names a testable/file/command artifact:
+// a path, an extension, a test/spec word, a backticked token, or a runner. Else
+// it is prose (a human-judged outcome with no mechanical proof). Pure.
+const CODE_SHAPED_PATTERNS = [
+  /`[^`]+`/, // a backticked token (file, command, symbol)
+  /\b[\w./-]+\.(js|ts|mjs|cjs|json|yaml|yml|md|py|rs|go|sh)\b/i, // a filename with a known ext
+  /\b(test|tests|spec|coverage|passe?s?|green|exit\s*0)\b/i, // test/run vocabulary
+  /\b(npm|node|jest|git|curl|build|lint)\b/i, // a runner / command
+  /\//, // a path separator
+];
+
+export function classifyCriterion(criterion) {
+  const text = String(criterion || '');
+  const isCode = CODE_SHAPED_PATTERNS.some((re) => re.test(text));
+  return isCode ? 'code' : 'prose';
+}
+
+// Default I/O surface. Overridable for tests.
+function defaultIo(projectRoot) {
+  const root = projectRoot || process.cwd();
+  return {
+    existsSync: (p) => fs.existsSync(path.isAbsolute(p) ? p : path.join(root, p)),
+    // git diff --stat constrained to the given paths, run at the project root.
+    gitDiffStat: (paths) => {
+      const argPaths = Array.isArray(paths) && paths.length ? ['--', ...paths] : [];
+      try {
+        const out = execFileSync('git', ['diff', '--stat', ...argPaths], {
+          cwd: root,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim();
+      } catch {
+        return '';
+      }
+    },
+  };
+}
+
+// Pull the candidate file tokens out of a code-shaped criterion: backticked
+// tokens and bare filenames-with-extension. Pure (string-only).
+export function fileTokens(criterion) {
+  const text = String(criterion || '');
+  const tokens = new Set();
+  const backtick = /`([^`]+)`/g;
+  let m;
+  while ((m = backtick.exec(text))) {
+    const inner = m[1].trim();
+    // Only treat a backticked token as a file when it LOOKS like a path/file
+    // (has a separator or an extension); a backticked `npm test` is a command.
+    if (/[./]/.test(inner) && !/\s/.test(inner)) tokens.add(inner);
+  }
+  const bare = /\b[\w./-]+\.(?:js|ts|mjs|cjs|json|yaml|yml|md|py|rs|go|sh)\b/gi;
+  while ((m = bare.exec(text))) tokens.add(m[0]);
+  return [...tokens];
+}
+
+// Build the evidence report for a set of criteria.
+//
+//   criteria      : array of acceptance-criterion strings (the locked scope)
+//   allowedPaths  : the locked allowed paths (scopes the git diff)
+//   context       : { testRun } where testRun is an optional captured run
+//                   { ran:bool, exitCode:number, summary?:string } — the agent
+//                   passes what it observed; we never re-run the suite here.
+//   io            : injected I/O (existsSync, gitDiffStat). Defaults to real fs/git.
+//
+// Returns { perCriterion:[{criterion, kind, hasEvidence, evidence}], missing:[...] }.
+// A code criterion HAS evidence when a named file exists OR a constrained git
+// diff is non-empty OR a green test run was captured. A prose criterion never
+// claims mechanical evidence (it is human-judged) and is reported as such — it
+// is NOT counted as missing, because prose criteria have no mechanical proof by
+// nature; only code criteria without any evidence land in `missing`.
+export function buildEvidence({
+  criteria = [],
+  allowedPaths = [],
+  context = {},
+  projectRoot,
+  io,
+} = {}) {
+  const surface = io || defaultIo(projectRoot);
+  const testRun = context && context.testRun;
+  const diffStat =
+    typeof surface.gitDiffStat === 'function' ? surface.gitDiffStat(allowedPaths) : '';
+  const hasDiff = Boolean(diffStat && diffStat.length);
+  const greenTest = Boolean(testRun && testRun.ran && Number(testRun.exitCode) === 0);
+
+  const perCriterion = [];
+  const missing = [];
+
+  for (const c of Array.isArray(criteria) ? criteria : []) {
+    const kind = classifyCriterion(c);
+    if (kind === 'prose') {
+      perCriterion.push({
+        criterion: c,
+        kind,
+        hasEvidence: false,
+        evidence: { type: 'prose', note: 'human-judged outcome — no mechanical proof expected' },
+      });
+      continue;
+    }
+
+    const tokens = fileTokens(c);
+    const existing = tokens.filter((t) => {
+      try {
+        return surface.existsSync(t);
+      } catch {
+        return false;
+      }
+    });
+
+    let hasEvidence = false;
+    let evidence = null;
+    if (existing.length) {
+      hasEvidence = true;
+      evidence = { type: 'file', files: existing };
+    } else if (greenTest) {
+      hasEvidence = true;
+      evidence = {
+        type: 'test',
+        exitCode: 0,
+        summary: testRun.summary || 'test run captured green',
+      };
+    } else if (hasDiff) {
+      hasEvidence = true;
+      evidence = { type: 'diff', stat: diffStat };
+    } else {
+      evidence = { type: 'none', note: 'no file, no green test run, no diff in allowedPaths' };
+    }
+
+    perCriterion.push({ criterion: c, kind, hasEvidence, evidence });
+    if (!hasEvidence) missing.push(c);
+  }
+
+  return { perCriterion, missing };
+}

package/install/templates/_byan/mcp/byan-mcp-server/lib/leantime-fd-core.js

@@ -70,6 +70,47 @@ const PHASE_RANK = {
   ABORTED: 9,
 };
 
+// Map an FD backlog item's priority (P1/P2/P3) to a Leantime priority int.
+// Leantime priority is high=3 .. low=1; an unknown priority yields undefined so
+// the caller can OMIT the key (an absent priority must not be forced to a value).
+export function priorityToLeantime(priority) {
+  switch (priority) {
+    case 'P1':
+      return 3;
+    case 'P2':
+      return 2;
+    case 'P3':
+      return 1;
+    default:
+      return undefined;
+  }
+}
+
+// Map an FD backlog item to a Leantime story-points effort estimate. Prefers a
+// finite numeric `complexity` (0-100 scale, bucketed onto the Fibonacci scale
+// Leantime uses for estimates), and falls back to the coarse priority signal
+// when complexity is absent. ALWAYS returns a number so the caller can post a
+// non-null estimate on every created task.
+export function complexityToStorypoints(item) {
+  if (item && Number.isFinite(item.complexity)) {
+    const c = item.complexity;
+    if (c <= 15) return 2;
+    if (c <= 39) return 5;
+    if (c <= 69) return 8;
+    return 13;
+  }
+  switch (item && item.priority) {
+    case 'P1':
+      return 8;
+    case 'P2':
+      return 5;
+    case 'P3':
+      return 3;
+    default:
+      return 3;
+  }
+}
+
 function lastReviewStatus(state) {
   const arr = Array.isArray(state.review_findings) ? state.review_findings : [];
   for (let i = arr.length - 1; i >= 0; i -= 1) {
@@ -126,7 +167,7 @@ export function columnForState(state) {
 // Intent ops (the shell maps each to a leantime-sync call):
 //   { op:'project_ensure', name, slug, details }
 //   { op:'assign_user' }                              // only if configured (shell sequences it after project_ensure)
-//   { op:'task_create', backlogId, headline }
+//   { op:'task_create', backlogId, headline, storypoints, description, priority? }
 //   { op:'task_move', backlogId, column }
 export function decideActions({ toolName, state, sidecar = {}, assignUserConfigured = false } = {}) {
   const kind = fdToolKind(toolName);
@@ -161,7 +202,24 @@ export function decideActions({ toolName, state, sidecar = {}, assignUserConfigu
       if (!item || !item.id) continue;
       if (item.status === 'skipped') continue;
       if (!tasks[item.id]) {
-        intents.push({ op: 'task_create', backlogId: item.id, headline: item.title || item.id });
+        const headline = item.title || item.id;
+        // Enrich the create with effort + priority + a traceable description so
+        // the board item carries the BYAN signal, not just a bare title.
+        const priority = priorityToLeantime(item.priority);
+        const hasComplexity = Number.isFinite(item.complexity);
+        const description =
+          `BYAN FD ${state.fd_id || ''} -- ${headline}`.trim() +
+          (hasComplexity ? ` [complexity:${item.complexity}]` : '');
+        const intent = {
+          op: 'task_create',
+          backlogId: item.id,
+          headline,
+          storypoints: complexityToStorypoints(item),
+          description,
+        };
+        // priority is OMITTED when unknown (do not force an absent priority).
+        if (priority !== undefined) intent.priority = priority;
+        intents.push(intent);
       }
     }
   }

package/install/templates/_byan/mcp/byan-mcp-server/lib/leantime-sync.js

@@ -216,7 +216,7 @@ export async function ensureProject({ name, slug, clientId, details } = {}, opts
 // `id` so the caller can store it back into fd-state (idempotency lives in the
 // caller: create-only-if the backlog item has no leantime_task_id yet).
 export async function createTask(
-  { projectId, headline, description, status, priority, editorId, tags, type = 'task' } = {},
+  { projectId, headline, description, status, priority, storypoints, editorId, tags, type = 'task' } = {},
   opts = {},
 ) {
   if (!projectId) return { ok: false, synced: false, reason: 'no_project_id' };
@@ -226,6 +226,9 @@ export async function createTask(
   if (description != null) values.description = description;
   if (status != null) values.status = status;
   if (priority != null) values.priority = priority;
+  // storypoints is the presumed Leantime effort field (UNVERIFIED against a live
+  // instance); an unknown key is at worst ignored by addTicket, so this is safe.
+  if (storypoints != null) values.storypoints = storypoints;
   // Default the assignee to the configured human (LEANTIME_ASSIGN_USER_ID) so an
   // auto-created task shows on a person's board, not only the API service user.
   const resolvedEditor = editorId != null ? editorId : assignUserId();