@alfacapital-tech/c4builder 0.9.0-rc.3 → 0.9.0

package/README.MD

@@ -31,6 +31,9 @@ than a hundred diagrams, so we continue it as a maintained fork, adapted to work
   and lays it out with horizontal pools and lanes.
 - **Mermaid** `.mmd` files and ```` ```mermaid ```` blocks are rendered at build time by real mermaid,
   without a browser: images in every output instead of client-side rendering.
+- **Review from the page.** In `c4builder --site -w` a selection becomes a question in the source
+  `.md` or feedback for the agent; `c4builder feedback --wait --as <name>` hands the batch to the
+  agent, and the page reloads with its edits.
 - **Maintained.** TypeScript, golden rendering snapshots, CI on every pull request, releases to
   npm and GHCR. The PDF output of the original was removed.
 

package/dist/cli/commands/feedback.js

@@ -1,11 +1,20 @@
 import chalk from 'chalk';
 import fs from 'node:fs';
 import { parseConfig } from "../../config/options.js";
+import { LISTENER_NAME } from "../../core/feedback.js";
 import { FEEDBACK_HEADER, FEEDBACK_PATH } from "./site.comments.js";
 // `c4builder feedback` (change site-agent-feedback, design D9): забирает пачку замечаний у `site -w`.
 // Конфиг читается как JSON без Configstore — тот создал бы `.c4builder` в любом каталоге. Ошибки —
 // через exitCode, а не process.exit: напечатанная в pipe пачка должна успеть уйти целиком.
 export default async (configPath, opts) => {
+    // Имя обязательно и без умолчания (change feedback-mailboxes, D2): с ним два агента со старой
+    // инструкцией молча делили бы один ящик. Код 2, а не 1: код 1 инструкции агентов читают как
+    // «нет сервера, перезапусти сайт».
+    if (!opts.as || !LISTENER_NAME.test(opts.as)) {
+        console.error(chalk.red('--as <name> is required: name this listener after your change or task (1-64 letters, digits, ".", "_" or "-"), e.g. "c4builder feedback --wait --as add-dark-mode"; use the same name after each batch'));
+        process.exitCode = 2;
+        return;
+    }
     let raw;
     try {
         raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
@@ -20,7 +29,7 @@ export default async (configPath, opts) => {
     };
     // 127.0.0.1, а не localhost: сервер слушает только IPv4, а `localhost` → `::1` на части машин
     // подвешивает соединение.
-    const url = `http://127.0.0.1:${port}${FEEDBACK_PATH}/next${opts.wait ? '' : '?wait=0'}`;
+    const url = `http://127.0.0.1:${port}${FEEDBACK_PATH}/next?as=${opts.as}${opts.wait ? '' : '&wait=0'}`;
     for (;;) {
         let res;
         try {
@@ -40,6 +49,7 @@ export default async (configPath, opts) => {
         }
         if (res.status === 404)
             return fail(`agent feedback is disabled on ${shown} — the server runs without -w or with --no-agent`);
-        return fail(`unexpected response ${res.status} from ${shown}`);
+        const error = await res.json().then((body) => body?.error, () => undefined);
+        return fail(`unexpected response ${res.status} from ${shown}${typeof error === 'string' ? `: ${error}` : ''}`);
     }
 };

package/dist/cli/commands/site.comments.js

@@ -22,6 +22,10 @@ const CSS = [
     '.c4b-review{position:fixed;left:50%;bottom:16px;transform:translateX(-50%);z-index:1000;width:520px;max-width:calc(100vw - 32px);box-sizing:border-box;padding:8px 12px;border:1px solid #3b82f6;border-radius:6px;background:#fff;color:#2c3e50;font:13px/1.4 sans-serif;box-shadow:0 2px 8px rgba(0,0,0,.2)}',
     '.c4b-review .c4b-row{display:flex;flex-wrap:wrap;align-items:center;gap:6px}',
     '.c4b-review .c4b-row small{flex:1;color:#888;white-space:nowrap}',
+    // Выбор адресата сжимается вместе с select: длинные имена не выталкивают кнопки из строки.
+    '.c4b-review .c4b-to{flex:1;min-width:0;display:flex;align-items:center;gap:4px;color:#888;white-space:nowrap}',
+    '.c4b-review .c4b-to[hidden]{display:none}',
+    '.c4b-review select{min-width:0;max-width:100%;padding:2px;border:1px solid #ccc;border-radius:4px;background:#fff;color:#2c3e50;font:13px sans-serif}',
     // Кнопки панели переносятся одной группой: иначе при нехватке места часть уезжает на
     // вторую строку, а Discard остаётся один в первой.
     '.c4b-review .c4b-acts{display:flex;gap:6px;margin-left:auto}',
@@ -49,7 +53,7 @@ const jsValue = (v) => JSON.stringify(v)
 // Начальное состояние агентского режима и ключ проекта вставляет сервер, дальше его обновляют
 // события `c4builder:agent` от сниппета livereload (change site-agent-feedback, design D4, D8).
 // Язык выбирает сам скрипт: при `auto` — по navigator.languages (change site-ui-language, D1).
-export const commentsSnippet = (heading, { agent = false, listening = false, project = '', language = 'auto' } = {}) => `
+export const commentsSnippet = (heading, { agent = false, mailboxes = [], project = '', language = 'auto' } = {}) => `
 <script>
 (function () {
     if (window.__c4builderComments) return;
@@ -59,7 +63,8 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
     var HEADING = ${jsValue(heading)};
     var TOAST_KEY = '__c4builderCommentToast';
     var DRAFT_KEY = '__c4builderReview:' + ${jsValue(project)};
-    var AGENT = { on: ${agent}, listening: ${listening} };
+    var TARGET_KEY = '__c4builderTarget:' + ${jsValue(project)};
+    var AGENT = { on: ${agent}, mailboxes: ${jsValue(mailboxes)} };
     var BLOCKS = 'p,li,td,th,h1,h2,h3,h4,h5,h6,pre,blockquote,dd,dt,div,section,details,summary';
     var style = document.createElement('style');
     style.textContent = ${jsValue(CSS)};
@@ -378,40 +383,65 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
         return function (err) { toast(t(key, { error: err && err.message ? err.message : err }), true); };
     };
 
+    // The tab's recipient lives in sessionStorage: it survives livereload, is per tab and is
+    // copied with a duplicated tab. Recipients are the server's mailboxes plus the tab's own.
+    var target = '';
+    try { target = sessionStorage.getItem(TARGET_KEY) || ''; } catch (e) {}
+    var recipients = function () {
+        var all = AGENT.mailboxes.slice();
+        var known = all.some(function (m) { return m.name === target; });
+        if (target && !known) all.push({ name: target, state: 'reconnecting', queued: 0 });
+        return all;
+    };
+    // Without mailboxes a batch goes to whoever connects first; with several, only to a chosen one.
+    var canSend = function () { return !!target || !AGENT.mailboxes.length; };
+    var named = function (key, name) { return name ? t(key + 'To', { name: name }) : t(key); };
+
     // Feedback to the agent: "Delivered" only after the server handed the batch to
     // "c4builder feedback"; the event may outrun the POST response, hence both maps.
     var delivered = {}, pending = {};
     var sendBatch = function (decision, comments, general) {
-        return send({ decision: decision, comments: comments, general: general }, 'POST', FEEDBACK).then(function (r) {
-            if (delivered[r.id]) return toast(t('delivered'));
+        var body = { decision: decision, comments: comments, general: general, to: target || undefined };
+        return send(body, 'POST', FEEDBACK).then(function (r) {
+            if (r.id in delivered) return toast(named('delivered', delivered[r.id]));
             pending[r.id] = true;
-            toast(t(r.queued ? 'queued' : 'sent'));
+            toast(named(r.queued ? 'queued' : 'sent', r.to));
         });
     };
     window.addEventListener('c4builder:delivered', function (e) {
-        var id = e.detail && e.detail.id;
-        delivered[id] = true;
-        if (pending[id]) { delete pending[id]; toast(t('delivered')); }
+        var d = e.detail || {};
+        delivered[d.id] = d.to || '';
+        if (pending[d.id]) { delete pending[d.id]; toast(named('delivered', d.to)); }
     });
 
-    // Review draft lives in localStorage per project: it survives livereload and a closed tab;
-    // without storage it lives until the page reloads.
-    var memDraft = [];
+    // Review draft lives in localStorage per project and recipient: it survives livereload and a
+    // closed tab, and a tab never sends comments typed for another agent. Without storage it lives
+    // until the page reloads. Without a recipient the rc key is used, so earlier drafts survive.
+    var memDraft = {};
+    var draftKey = function () { return DRAFT_KEY + (target ? ':' + target : ''); };
     var draft = function () {
         try {
-            var v = JSON.parse(localStorage.getItem(DRAFT_KEY) || '[]');
+            var v = JSON.parse(localStorage.getItem(draftKey()) || '[]');
             return Array.isArray(v) ? v : [];
-        } catch (e) { return memDraft; }
+        } catch (e) { return memDraft[draftKey()] || []; }
     };
     var saveDraft = function (items) {
-        memDraft = items;
+        memDraft[draftKey()] = items;
         try {
-            if (items.length) localStorage.setItem(DRAFT_KEY, JSON.stringify(items));
-            else localStorage.removeItem(DRAFT_KEY);
+            if (items.length) localStorage.setItem(draftKey(), JSON.stringify(items));
+            else localStorage.removeItem(draftKey());
         } catch (e) {}
         renderPanel();
         highlightDraft();
     };
+    // A draft started before the tab had a recipient goes to its first recipient.
+    var setTarget = function (name) {
+        var orphan = target ? [] : draft();
+        if (orphan.length) saveDraft([]);
+        target = name;
+        try { sessionStorage.setItem(TARGET_KEY, name); } catch (e) {}
+        saveDraft(draft().concat(orphan));
+    };
     var highlightDraft = function () {
         var root = content();
         if (!root) return;
@@ -436,6 +466,12 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
     var count = button('', function () { expanded = !expanded; renderPanel(); }, 'c4b-link');
     var listen = document.createElement('small');
     listen.className = 'c4b-listen';
+    var sendTo = document.createElement('label');
+    sendTo.className = 'c4b-to';
+    sendTo.textContent = t('sendTo');
+    var select = document.createElement('select');
+    select.addEventListener('change', function () { setTarget(select.value); renderAgent(); });
+    sendTo.appendChild(select);
     var list = document.createElement('ul');
     var general = document.createElement('textarea');
     general.placeholder = t('generalPlaceholder');
@@ -474,7 +510,7 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
     var acts = document.createElement('span');
     acts.className = 'c4b-acts';
     [discard, approve, submit].forEach(function (el) { acts.appendChild(el); });
-    [count, listen, acts].forEach(function (el) { head.appendChild(el); });
+    [count, listen, sendTo, acts].forEach(function (el) { head.appendChild(el); });
     panel.appendChild(head);
     panel.appendChild(list);
     panel.appendChild(general);
@@ -506,28 +542,51 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
         approve.className = empty ? 'c4b-primary' : '';
         discard.hidden = submit.hidden = empty;
         discard.disabled = busy;
-        approve.disabled = busy;
-        submit.disabled = busy || empty;
+        approve.disabled = busy || !canSend();
+        submit.disabled = busy || empty || !canSend();
+    };
+    var label = function (m) {
+        return t(m.state === 'listening' ? 'stateListening' : 'stateReconnecting', { name: m.name }) +
+            (m.queued ? ', ' + t('inQueue', { n: m.queued }) : '');
     };
+    // The popover's send button follows the recipient too; set while the popover is open.
+    var syncPop = null;
     var renderAgent = function () {
+        // A lone mailbox is chosen and remembered: the tab stays with it when a second agent comes.
+        if (!target && AGENT.mailboxes.length === 1) setTarget(AGENT.mailboxes[0].name);
         fbBtn.hidden = !AGENT.on;
-        renderPanel();
-        var text = t(AGENT.listening ? 'listening' : 'notListening');
+        var all = recipients(), current = null;
+        all.forEach(function (m) { if (m.name === target) current = m; });
+        var text = current ? label(current) : t(all.length ? 'chooseAgent' : 'notListening');
         var els = document.querySelectorAll('.c4b-listen');
         for (var i = 0; i < els.length; i++) { els[i].textContent = text; els[i].title = text; }
+        listen.hidden = all.length > 1;
+        sendTo.hidden = !listen.hidden;
+        select.textContent = '';
+        if (!target) all.unshift({ name: '', label: t('chooseAgent') });
+        all.forEach(function (m) {
+            var o = document.createElement('option');
+            o.value = m.name;
+            o.textContent = m.label || label(m);
+            select.appendChild(o);
+        });
+        select.value = target;
+        renderPanel();
+        if (syncPop) syncPop();
     };
     window.addEventListener('c4builder:agent', function (e) {
         var d = e.detail || {};
         AGENT.on = !!d.on;
-        AGENT.listening = !!d.listening;
+        AGENT.mailboxes = Array.isArray(d.mailboxes) ? d.mailboxes : [];
         renderAgent();
     });
     window.addEventListener('storage', function (e) {
-        if (e.key === DRAFT_KEY) { renderPanel(); highlightDraft(); }
+        if (e.key === draftKey()) { renderPanel(); highlightDraft(); }
     });
 
     var close = function () {
         if (pop) { pop.remove(); pop = null; }
+        syncPop = null;
         btns.hidden = true;
     };
     var open = function (data, rect, feedback) {
@@ -545,13 +604,19 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
         else hint.textContent = hint.title = t('questionTo', { target: HEADING + (data.section ? ' / ' + data.section : '') });
         var actions = document.createElement('span');
         var buttons = [button(t('cancel'), close)];
+        var sending = false, now = null;
+        var sync = function () {
+            buttons.forEach(function (b) { b.disabled = sending || (b === now && !canSend()); });
+        };
         var run = function (action) {
             return function () {
                 var comment = ta.value.trim();
                 if (!comment) { ta.focus(); return; }
-                buttons.forEach(function (b) { b.disabled = true; });
+                sending = true;
+                sync();
                 action(comment).then(close, function (err) {
-                    buttons.forEach(function (b) { b.disabled = false; });
+                    sending = false;
+                    sync();
                     failure(feedback ? 'feedbackFailed' : 'questionFailed')(err);
                 });
             };
@@ -567,7 +632,7 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
                 saveDraft(draft().concat([it]));
                 return Promise.resolve();
             }));
-            var now = button(t('sendNow'), run(function (c) { return sendBatch('submitted', [item(c)], ''); }));
+            now = button(t('sendNow'), run(function (c) { return sendBatch('submitted', [item(c)], ''); }));
             buttons.push(add, now);
             // As in a GitLab merge request: once a review is started, comments go into it.
             primary = draft().length ? add : now;
@@ -592,6 +657,7 @@ export const commentsSnippet = (heading, { agent = false, listening = false, pro
         pop.appendChild(ta);
         pop.appendChild(row);
         document.body.appendChild(pop);
+        syncPop = sync;
         renderAgent();
         place(pop, rect);
         ta.focus();

package/dist/cli/commands/site.i18n.js

@@ -15,6 +15,9 @@ export const UI_STRINGS = {
         sent: 'Sent to the agent',
         delivered: 'Delivered to the agent',
         queued: 'Queued — agent is not listening',
+        sentTo: 'Sent to {name}',
+        deliveredTo: 'Delivered to {name}',
+        queuedTo: 'Queued for {name} — not listening',
         reviewFailed: 'Review failed: {error}',
         feedbackFailed: 'Feedback failed: {error}',
         questionFailed: 'Question failed: {error}',
@@ -32,8 +35,12 @@ export const UI_STRINGS = {
         comments: { one: '{n} pending', other: '{n} pending' },
         pages: { one: '{n} page', other: '{n} pages' },
         removeFromReview: 'Remove from the review',
-        listening: 'agent: listening ●',
         notListening: 'agent: not listening ○',
+        stateListening: '{name}: listening ●',
+        stateReconnecting: '{name}: reconnecting ○',
+        inQueue: '{n} queued',
+        sendTo: 'Send to',
+        chooseAgent: 'choose an agent',
         feedbackPlaceholder: 'What should the agent change? (Ctrl+Enter to send, Esc to cancel)',
         questionPlaceholder: 'Your question (Ctrl+Enter to send, Esc to cancel)',
         questionTo: 'To: {target}',
@@ -54,6 +61,9 @@ export const UI_STRINGS = {
         sent: 'Отправлено агенту',
         delivered: 'Доставлено агенту',
         queued: 'В очереди: агент не слушает',
+        sentTo: 'Отправлено агенту {name}',
+        deliveredTo: 'Доставлено агенту {name}',
+        queuedTo: 'В очереди у {name}: агент не слушает',
         reviewFailed: 'Не удалось отправить ревью: {error}',
         feedbackFailed: 'Не удалось отправить замечание: {error}',
         questionFailed: 'Не удалось добавить вопрос: {error}',
@@ -75,8 +85,12 @@ export const UI_STRINGS = {
         comments: { one: '{n} замечание', few: '{n} замечания', many: '{n} замечаний' },
         pages: { one: 'на {n} странице', few: 'на {n} страницах', many: 'на {n} страницах' },
         removeFromReview: 'Убрать из ревью',
-        listening: 'агент: слушает ●',
         notListening: 'агент: не слушает ○',
+        stateListening: '{name}: слушает ●',
+        stateReconnecting: '{name}: переподключается ○',
+        inQueue: 'в очереди: {n}',
+        sendTo: 'Кому',
+        chooseAgent: 'выберите агента',
         feedbackPlaceholder: 'Что должен изменить агент? (Ctrl+Enter — отправить, Esc — отмена)',
         questionPlaceholder: 'Ваш вопрос (Ctrl+Enter — отправить, Esc — отмена)',
         questionTo: 'Куда: {target}',

package/dist/cli/commands/site.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import express from 'express';
 import open from 'open';
-import { batchSchema, formatBatch } from "../../core/feedback.js";
+import { batchSchema, formatBatch, LISTENER_NAME } from "../../core/feedback.js";
 import { deleteQuestion, formatQuestion, pickSource, writeQuestion } from "../../core/questions.js";
 import { packageJson as pkg } from "../../util/paths.js";
 import { pendingUpdate } from "../update.js";
@@ -103,20 +103,51 @@ pages = () => new Map()) => {
     // Кеш index.html — отдаём его из памяти, если на диске его временно нет
     // (в окне build.js → emptyDir(DIST_FOLDER) перед записью).
     let lastIndexHtml = null;
+    let sweeper;
     // reloadEmitter в условии — сужает тип до EventEmitter внутри блока (liveReloadEnabled
     // истинно ⟺ reloadEmitter задан), поэтому дальше без non-null assertions.
     if (liveReloadEnabled && reloadEmitter) {
-        // Состояние слушателя `c4builder feedback` (design D4): подключён, пока открыт long-poll
-        // или с конца последнего прошло меньше idleMs — зазор между повторами команды.
-        let listening = false;
-        const agentState = () => ({ on: agent.on, listening });
-        const setAgent = (on, listen) => {
-            if (on === agent.on && listen === listening)
+        // Ящики слушателей `c4builder feedback --as <name>` (change feedback-mailboxes, D3–D4).
+        // Слушает, пока открыт long-poll или с конца последнего прошло меньше idleMs — зазор между
+        // повторами команды. Пачки без адресата (ящиков ещё не было) достаются любому имени.
+        const { pollMs = 25_000, idleMs = 30_000, mailboxTtlMs = 30 * 60_000 } = program;
+        const mailboxes = new Map();
+        const unaddressed = [];
+        const box = (name) => {
+            const b = mailboxes.get(name) ?? {
+                queue: [],
+                waiters: [],
+                polls: 0,
+                listening: false,
+                lastSeen: Date.now()
+            };
+            mailboxes.set(name, b);
+            return b;
+        };
+        const agentState = () => ({
+            on: agent.on,
+            mailboxes: [...mailboxes].map(([name, b]) => ({
+                name,
+                state: b.listening ? 'listening' : 'reconnecting',
+                queued: b.queue.length
+            }))
+        });
+        // Событие — только когда снимок изменился: publish зовётся после любой смены очередей.
+        let published = JSON.stringify(agentState());
+        const publish = () => {
+            const state = agentState();
+            const json = JSON.stringify(state);
+            if (json === published)
                 return;
-            agent.on = on;
-            listening = listen;
-            reloadEmitter.emit('agent', agentState());
+            published = json;
+            reloadEmitter.emit('agent', state);
         };
+        sweeper = setInterval(() => {
+            for (const [name, b] of mailboxes)
+                if (!b.polls && !b.queue.length && Date.now() - b.lastSeen >= mailboxTtlMs)
+                    mailboxes.delete(name);
+            publish();
+        }, Math.min(mailboxTtlMs, 60_000)).unref();
         app.get(LIVERELOAD_PATH, (req, res) => {
             res.set({
                 'Content-Type': 'text/event-stream',
@@ -153,7 +184,7 @@ pages = () => new Map()) => {
             const snippet = LIVERELOAD_SNIPPET +
                 commentsSnippet(currentConfiguration.QUESTIONS_HEADING, {
                     agent: agent.on,
-                    listening,
+                    mailboxes: agentState().mailboxes,
                     project: projectKey,
                     language: currentConfiguration.UI_LANGUAGE
                 }) +
@@ -260,35 +291,39 @@ pages = () => new Map()) => {
         });
         // Замечания агенту (change site-agent-feedback): FIFO пачек в памяти (design D3), страница
         // шлёт POST, `c4builder feedback` забирает long-poll'ом (D1). Пачка снимается с очереди,
-        // когда ответ записан; обрыв до этого возвращает её в голову очереди.
-        const { pollMs = 25_000, idleMs = 30_000 } = program;
-        const queue = [];
-        const waiters = [];
-        let polls = 0;
-        let idleTimer;
+        // когда ответ записан; обрыв до этого возвращает её в голову очереди, откуда её взяли.
         const disabled = () => agent.explicit && !agent.on;
-        const drop = (res) => {
-            const i = waiters.indexOf(res);
+        const drop = (b, res) => {
+            const i = b.waiters.indexOf(res);
             if (i >= 0)
-                waiters.splice(i, 1);
+                b.waiters.splice(i, 1);
         };
-        const pump = () => {
-            while (queue.length && waiters.length) {
-                const res = waiters.shift();
-                const item = queue.shift();
+        const pump = (name, b) => {
+            for (;;) {
+                const source = b.queue.length ? b.queue : unaddressed;
+                if (!source.length || !b.waiters.length)
+                    return;
+                const res = b.waiters.shift();
+                const item = source.shift();
                 if (res && item)
-                    deliver(res, item);
+                    deliver(name, res, item, source);
             }
         };
-        const deliver = (res, item) => {
+        const pumpAll = () => {
+            for (const [name, b] of mailboxes)
+                pump(name, b);
+        };
+        const deliver = (name, res, item, source) => {
             res.on('close', () => {
                 if (!res.writableFinished) {
-                    queue.unshift(item);
-                    pump();
-                    return;
+                    source.unshift(item);
+                    pumpAll();
                 }
-                console.log(chalk.gray(`feedback: batch delivered to the agent (${item.batch.decision})`));
-                reloadEmitter.emit('delivered', { id: item.id });
+                else {
+                    console.log(chalk.gray(`feedback: batch delivered to ${name} (${item.batch.decision})`));
+                    reloadEmitter.emit('delivered', { id: item.id, to: name });
+                }
+                publish();
             });
             res.type('text/markdown').send(formatBatch(item.batch, pages(), process.cwd()));
         };
@@ -309,17 +344,21 @@ pages = () => new Map()) => {
                 });
                 return;
             }
-            const batch = parsed.data;
+            const { to, ...batch } = parsed.data;
             if (batch.decision === 'submitted' && !batch.comments.length && !batch.general) {
                 res.status(400).json({ error: 'nothing to send' });
                 return;
             }
             const id = randomUUID();
-            const queued = !waiters.length;
-            queue.push({ id, batch });
-            pump();
-            console.log(chalk.gray(`feedback: ${batch.decision}, ${batch.comments.length} comment(s)${queued ? ' — queued, no agent listening' : ''}`));
-            res.json({ id, queued });
+            // Ящик адресата создаётся и здесь: выбранный на вкладке адресат не теряется, даже если
+            // его пустой ящик успели удалить.
+            const target = to === undefined ? undefined : box(to);
+            const queued = !(target ? [target] : [...mailboxes.values()]).some((b) => b.waiters.length);
+            (target?.queue ?? unaddressed).push({ id, batch });
+            pumpAll();
+            publish();
+            console.log(chalk.gray(`feedback for ${to ?? 'any listener'}: ${batch.decision}, ${batch.comments.length} comment(s)${queued ? ' — queued, not listening' : ''}`));
+            res.json({ id, queued, to });
         });
         // Нестандартный заголовок вынуждает браузер к preflight, на который сервер не отвечает:
         // чужая страница не может ни прочитать, ни «съесть» очередь простым запросом (design D6).
@@ -332,27 +371,41 @@ pages = () => new Map()) => {
                 res.status(404).json({ error: 'agent feedback is disabled (--no-agent)' });
                 return;
             }
+            const name = req.query.as;
+            if (typeof name !== 'string' || !LISTENER_NAME.test(name)) {
+                res.status(400).json({
+                    error: '--as <name> is required: 1-64 letters, digits, ".", "_" or "-" (c4builder feedback --wait --as <name>)'
+                });
+                return;
+            }
             if (!agent.on)
-                console.log(chalk.gray('agent mode on: "c4builder feedback" connected'));
-            polls++;
-            clearTimeout(idleTimer);
-            setAgent(true, true);
+                console.log(chalk.gray(`agent mode on: "c4builder feedback --as ${name}" connected`));
+            agent.on = true;
+            const b = box(name);
+            b.polls++;
+            b.listening = true;
+            clearTimeout(b.idle);
+            publish();
             let timer;
             res.on('close', () => {
                 clearTimeout(timer);
-                drop(res);
-                if (--polls === 0)
-                    idleTimer = setTimeout(() => setAgent(agent.on, false), idleMs);
+                drop(b, res);
+                b.lastSeen = Date.now();
+                if (--b.polls === 0)
+                    b.idle = setTimeout(() => {
+                        b.listening = false;
+                        publish();
+                    }, idleMs);
             });
-            waiters.push(res);
-            pump();
-            if (!waiters.includes(res))
+            b.waiters.push(res);
+            pump(name, b);
+            if (!b.waiters.includes(res))
                 return;
             timer = setTimeout(() => {
                 // Пачку успели отдать этому запросу — ответ уже пишется, 204 не нужен.
-                if (!waiters.includes(res))
+                if (!b.waiters.includes(res))
                     return;
-                drop(res);
+                drop(b, res);
                 res.status(204).end();
             }, req.query.wait === '0' ? 0 : pollMs);
         });
@@ -407,12 +460,13 @@ pages = () => new Map()) => {
             if (liveReloadEnabled)
                 console.log(chalk.gray('livereload enabled (browser auto-reload on rebuild)'));
             if (liveReloadEnabled && agent.on)
-                console.log(`agent mode (${agent.name}): page feedback goes to "c4builder feedback --wait${program.port ? ` -p ${port}` : ''}" — run it in the background and again after each batch`);
+                console.log(`agent mode (${agent.name}): page feedback goes to "c4builder feedback --wait --as <name>${program.port ? ` -p ${port}` : ''}" — run it in the background, <name> is your change or task; run it again with the same name after each batch`);
             // --open: открываем браузер один раз при старте; BROWSER=none отключает (CI/headless)
             if (program.open && process.env.BROWSER !== 'none')
                 open(url).catch(() => console.log(chalk.gray('could not open the browser automatically')));
             resolve(server);
         });
+        server.on('close', () => clearInterval(sweeper));
         server.on('error', (err) => {
             if (err.code === 'EADDRINUSE') {
                 console.log(chalk.red(`port ${port} is already in use — pass a different one with -p <port>`));

package/dist/cli/dispatch.js

@@ -127,6 +127,7 @@ export default async () => {
         .option('--agent', 'with --site -w: accept page feedback for a coding agent (c4builder feedback)')
         .option('--no-agent', 'with --site -w: no agent feedback even when run by a coding agent')
         .option('--wait', 'for `feedback`: wait for the next batch of page feedback')
+        .option('--as <name>', 'for `feedback`: listener name (your change or task) — the page sends batches to it')
         .option('--docs', 'a brief explanation for the available configuration options')
         .option('--system-fonts', 'render with system fonts instead of the bundled one (not deterministic)')
         .option('-p, --port <n>', 'port used for serving the generated site', (v) => {

package/dist/core/feedback.js

@@ -10,7 +10,10 @@ const clip = (s) => {
     const q = collapse(s);
     return q.length > TEXT_MAX ? `${q.slice(0, TEXT_MAX - 1).trimEnd()}…` : q;
 };
+// Имя слушателя `c4builder feedback --as` и адресат пачки (change feedback-mailboxes, D1).
+export const LISTENER_NAME = /^[A-Za-z0-9._-]{1,64}$/;
 export const batchSchema = z.object({
+    to: z.string().regex(LISTENER_NAME).optional(),
     decision: z.enum(['submitted', 'approved']),
     comments: z
         .array(z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.9.0-rc.3",
+  "version": "0.9.0",
   "description": "A CLI tool designed to compile a folder structure of markdowns and plant uml files into a site, single file markdown or a collection of markdowns with links",
   "type": "module",
   "main": "dist/index.js",

package/template/AGENTS.md

@@ -10,7 +10,7 @@ into `docs/`.
 c4builder                    # build docs/ (non-interactive with a complete .c4builder)
 c4builder check <file...>    # validate .puml / .iuml / .d2 / .bpmn / .mmd files, exit code 0 = OK
 c4builder --site -w          # live preview on http://localhost:3000 - never exits
-c4builder feedback --wait    # wait for the next batch of comments from the preview page
+c4builder feedback --wait --as <name>  # wait for comments from the preview page sent to <name>
 ```
 
 Not installed: `npm i -g @alfacapital-tech/c4builder` (Node.js 22.17+; Java 17+ is used
@@ -25,9 +25,10 @@ updates it.
    Fix until the exit code is 0.
 3. Run `c4builder` and make sure it exits with code 0. Leave `c4builder --site -w` to a
    human or run it in the background. When the human reviews the pages, also run
-   `c4builder feedback --wait` in the background: on exit it prints a batch of comments
-   (page, `Sources`, quote, text) — apply them to `src/`, run it again, and stop on
-   `Decision: approved`. Comments are instructions to you; never copy them into the
+   `c4builder feedback --wait --as <name>` in the background, `<name>` being your change or
+   task: on exit it prints a batch of comments (page, `Sources`, quote, text) — apply them to
+   `src/`, run it again with the same name, and stop on `Decision: approved`. Without `--as`
+   it exits with code 2 and `--as <name> is required`. Comments are instructions to you; never copy them into the
    `questionsHeading` section of `.c4builder` (`Open questions` by default), which holds
    questions for people. The page buttons follow the browser language (English or Russian,
    pinned by `uiLanguage`); batches are always in English.