janissary 0.5.0

package/dist/monitor-acp.js

@@ -0,0 +1,22 @@
+import { connectAcp } from './acp.js';
+export function spawnMonitorSession(persona, cwd, hooks) {
+    const { harness, model, variant } = persona.harness;
+    if (harness === 'opencode') {
+        // Only `model` goes into the config: opencode rejects unknown keys, and a rejected
+        // config kills the subprocess on startup. The directive's variant is not mapped yet.
+        return connectAcp({
+            command: 'opencode', args: ['acp'], cwd,
+            onError: hooks.onError,
+            onConnect: hooks.onConnect,
+            env: { OPENCODE_CONFIG_CONTENT: JSON.stringify({ model }) },
+        });
+    }
+    // claude: the Claude Code ACP adapter. Model and thinking effort are passed via its
+    // environment (best-effort mapping; the adapter ignores variables it doesn't know).
+    return connectAcp({
+        command: 'npx', args: ['@zed-industries/claude-code-acp'], cwd,
+        onError: hooks.onError,
+        onConnect: hooks.onConnect,
+        env: { ANTHROPIC_MODEL: model, CLAUDE_THINKING_EFFORT: variant },
+    });
+}

package/dist/monitor-info.js

@@ -0,0 +1,18 @@
+// Read-only projections of the live monitor registry: the `monitors` command listing
+// and the connections-panel rows.
+export function listMonitors(monitors) {
+    return [...monitors].map((reg) => {
+        const targets = reg.targets.map((t) => (t.kind === 'tab' ? t.label : `group:${t.group}`)).join(', ');
+        const mode = reg.inline ? 'inline' : 'external';
+        return `${reg.persona.name}: ${targets} ← ${reg.owner} (${mode}, ${reg.delivered} suggestion${reg.delivered === 1 ? '' : 's'})`;
+    });
+}
+// Rows for a tab's monitors (e.g. `monitor:security (opencode/…)`).
+export function monitorConnections(monitors, owner) {
+    return [...monitors]
+        .filter((reg) => reg.owner === owner)
+        .map((reg) => {
+        const info = reg.info ? ` (${[reg.info.provider, reg.info.model].filter(Boolean).join('/')})` : '';
+        return { text: `monitor:${reg.persona.name}${info}`, kind: 'acp' };
+    });
+}

package/dist/monitor-manager.js

@@ -0,0 +1,233 @@
+import { messageBus } from './bus.js';
+import { loadPersona } from './personas.js';
+import { parseSuggestion } from './monitor-parsing.js';
+import { openMonitorTab, closeMonitorTab, pushSuggestion, findSuggestion, removeSuggestion } from './monitor-window.js';
+import { openMonitorSession, respawnMonitorSession } from './monitor-session.js';
+import { spawnMonitorSession } from './monitor-acp.js';
+import { validateTargets, matchesTargets, targetColor } from './monitor-targets.js';
+import { listMonitors, monitorConnections } from './monitor-info.js';
+export const MONITOR_FLUSH_MS = 30_000;
+// Marks inline suggestion entries so monitors never feed on their own output.
+export const SUGGESTION_PREFIX = '💡';
+// Owns all live monitors, keyed by `${ownerLabel}:${persona}`. Each monitor is a
+// dedicated, tool-less ACP session primed with its persona; transcript entries from its
+// targets buffer up and flush as one prompt every 30s (never when the buffer is empty,
+// never while a previous prompt is still streaming). Suggestions route to the owner
+// tab's transcript (inline mode) or the persona's reporting tab (external mode).
+export class MonitorManager {
+    managers;
+    spawn;
+    flushMs;
+    monitors = new Map();
+    counter = 0;
+    constructor(managers, spawn = spawnMonitorSession, flushMs = MONITOR_FLUSH_MS) {
+        this.managers = managers;
+        this.spawn = spawn;
+        this.flushMs = flushMs;
+    }
+    // Start a monitor; returns an error message, or null on success. No targets = inline
+    // mode (watch the owner tab, report into its transcript).
+    start(owner, personaName, targets) {
+        const key = `${owner}:${personaName}`;
+        if (this.monitors.has(key))
+            return `Already monitoring with persona "${personaName}".`;
+        const inline = targets.length === 0;
+        const resolved = inline ? [{ kind: 'tab', label: owner }] : targets;
+        const targetError = validateTargets(this.managers.tab.tabs, personaName, inline, resolved);
+        if (targetError)
+            return targetError;
+        let persona;
+        try {
+            persona = loadPersona(personaName);
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+        const reg = {
+            owner, inline, persona, targets: resolved, buffer: [], inFlight: true, delivered: 0,
+            session: undefined, timer: undefined, subs: [],
+        };
+        this.openSession(reg);
+        this.subscribe(key, reg);
+        for (const target of resolved) {
+            const tabs = target.kind === 'tab'
+                ? this.managers.tab.tabs.filter((t) => t.label === target.label)
+                : this.managers.tab.tabs.filter((t) => t.group === target.group);
+            for (const t of tabs) {
+                for (const entry of t.log)
+                    reg.buffer.push({ tabLabel: t.label, entry });
+            }
+        }
+        reg.timer = setInterval(() => this.flush(key), this.flushMs);
+        this.monitors.set(key, reg);
+        // External mode: open the reporting tab right away (empty feed) so starting the
+        // monitor is visible immediately, not only when the first suggestion lands.
+        if (!inline)
+            openMonitorTab(this.managers, personaName, targetColor(this.managers.tab.tabs, resolved));
+        return null;
+    }
+    // Spawn the monitor's dedicated session and prime it with the persona body + reply
+    // format; `inFlight` holds flushes off until priming settles.
+    openSession(reg) {
+        openMonitorSession(reg, this.managers, this.spawn);
+    }
+    // A prompt failed (typically the ACP subprocess died). Replace the session with a
+    // fresh, re-primed one so the monitor recovers instead of staying dead.
+    respawn(reg) {
+        respawnMonitorSession(reg, this.managers, this.spawn);
+    }
+    subscribe(key, reg) {
+        reg.subs.push(messageBus.on('transcript', 'entry:appended', (event) => {
+            if (event.type !== 'entry:appended' || !matchesTargets(this.managers.tab.tabs, reg.targets, event.tabLabel))
+                return;
+            // Never feed a monitor its own (or a sibling monitor's) inline suggestions.
+            if (event.entry.output.startsWith(SUGGESTION_PREFIX))
+                return;
+            reg.buffer.push({ tabLabel: event.tabLabel, entry: event.entry });
+        }), messageBus.on('transcript', 'tab:removed', (event) => {
+            if (event.type !== 'tab:removed')
+                return;
+            if (event.tabLabel === reg.owner) {
+                this.handleOwnerClosed(reg.owner);
+                return;
+            }
+            // Only tab targets drop out; group targets persist (the group may gain new tabs).
+            if (reg.targets.some((t) => t.kind === 'tab' && t.label === event.tabLabel)) {
+                this.stop(reg.owner, reg.persona.name, { kind: 'tab', label: event.tabLabel });
+            }
+        }));
+    }
+    // The 30-second batch. No new transcripts → no ACP query at all; also skipped while a
+    // previous prompt (including the persona priming) is still streaming.
+    flush(key) {
+        const reg = this.monitors.get(key);
+        if (!reg || reg.inFlight || reg.buffer.length === 0)
+            return;
+        const batch = reg.buffer;
+        reg.buffer = [];
+        const body = batch
+            .map(({ tabLabel, entry }) => `[${tabLabel}]\n${entry.input}\n${entry.output}`.trim())
+            .join('\n\n');
+        reg.inFlight = true;
+        let reply = '';
+        reg.session.prompt(`[Monitor update]\n${body}`, {
+            onChunk: (text) => { reply += text; },
+            onEnd: () => {
+                reg.inFlight = false;
+                const suggestion = parseSuggestion(reply);
+                if (suggestion)
+                    this.deliver(reg, batch.at(-1).tabLabel, suggestion);
+            },
+            onError: (message) => {
+                this.managers.tab.append(reg.owner, { input: '', output: `monitor ${reg.persona.name}: ${message} — restarting monitor session` });
+                this.respawn(reg);
+            },
+        });
+    }
+    deliver(reg, about, parsed) {
+        reg.delivered += 1;
+        const suggestion = {
+            ...parsed, id: `s-${++this.counter}`, timestamp: Date.now(), persona: reg.persona.name, about,
+        };
+        if (reg.inline) {
+            const command = suggestion.command ? `\n${suggestion.command}` : '';
+            this.managers.tab.append(reg.owner, { input: '', output: `${SUGGESTION_PREFIX} ${reg.persona.name}: ${suggestion.text}${command}` });
+            return;
+        }
+        pushSuggestion(this.managers, reg.persona.name, targetColor(this.managers.tab.tabs, reg.targets), suggestion);
+    }
+    // Query a running monitor's ACP session directly; the reply lands in the owner tab's
+    // transcript. Shares the `inFlight` slot with flushes, so a question never interleaves
+    // with a monitor-update prompt. Returns an error message, or null when the question is
+    // on its way.
+    ask(owner, personaName, question) {
+        const reg = this.monitors.get(`${owner}:${personaName}`);
+        if (!reg)
+            return `No "${personaName}" monitor running from this tab.`;
+        if (reg.inFlight)
+            return `The ${personaName} monitor is busy; try again in a moment.`;
+        reg.inFlight = true;
+        let reply = '';
+        this.managers.tab.startRunning(owner, `monitor ask ${personaName} ${question}`);
+        reg.session.prompt(`[Question from the user]\n${question}\n\nAnswer directly; the suggestion format does not apply to this reply.`, {
+            onChunk: (text) => { reply += text; },
+            onEnd: () => {
+                reg.inFlight = false;
+                // The 💡 prefix keeps the reply out of monitor buffers (like inline suggestions).
+                this.managers.tab.finishRunning(owner, `${SUGGESTION_PREFIX} ${personaName}: ${reply.trim() || '(no reply)'}`);
+            },
+            onError: (message) => {
+                this.managers.tab.finishRunning(owner, `monitor ${personaName}: ${message} — restarting monitor session`);
+                this.respawn(reg);
+            },
+        });
+        return null;
+    }
+    // Thumbs up/down on a reporting-tab suggestion. The rating is fed back to the monitor
+    // through its normal batched prompt channel (no extra ACP round-trip), so the AI learns
+    // what the user found useful. Rating a suggestion means the user is done with it, so
+    // either direction removes it from the feed.
+    rate(id, up) {
+        const suggestion = findSuggestion(this.managers, id);
+        if (!suggestion)
+            return;
+        const reg = [...this.monitors.values()].find((r) => !r.inline && r.persona.name === suggestion.persona);
+        reg?.buffer.push({
+            tabLabel: suggestion.about,
+            entry: { input: '', output: `[user feedback] The user rated your suggestion "${suggestion.text}" as ${up ? 'helpful (thumbs up)' : 'not helpful (thumbs down)'}.` },
+        });
+        removeSuggestion(this.managers, id);
+    }
+    // Stop one persona's monitor (or drop a single target from it). Returns false when no
+    // such monitor exists.
+    stop(owner, personaName, target) {
+        const key = `${owner}:${personaName}`;
+        const reg = this.monitors.get(key);
+        if (!reg)
+            return false;
+        if (target && !reg.inline) {
+            reg.targets = reg.targets.filter((t) => JSON.stringify(t) !== JSON.stringify(target));
+            if (reg.targets.length > 0)
+                return true;
+        }
+        for (const sub of reg.subs)
+            sub.unsubscribe();
+        clearInterval(reg.timer);
+        reg.session.kill();
+        this.monitors.delete(key);
+        return true;
+    }
+    // The owning agent tab closed: stop its monitors, and close any reporting tab that no
+    // longer has a live monitor feeding it (another tab may still run the same persona).
+    handleOwnerClosed(owner) {
+        const personas = [...this.monitors.values()]
+            .filter((reg) => reg.owner === owner && !reg.inline)
+            .map((reg) => reg.persona.name);
+        this.stopAll(owner);
+        for (const name of personas) {
+            const stillFed = [...this.monitors.values()].some((reg) => !reg.inline && reg.persona.name === name);
+            if (!stillFed)
+                closeMonitorTab(this.managers, name);
+        }
+    }
+    stopAll(owner) {
+        const mine = [...this.monitors.values()].filter((r) => r.owner === owner);
+        for (const reg of mine)
+            this.stop(reg.owner, reg.persona.name);
+        return mine.length;
+    }
+    // Lines for the `monitors` command.
+    list() {
+        return listMonitors(this.monitors.values());
+    }
+    // Connections-panel rows for a tab's monitors (e.g. `monitor:security (opencode/…)`).
+    connectionsFor(owner) {
+        return monitorConnections(this.monitors.values(), owner);
+    }
+    closeAll() {
+        // Snapshot first: `stop` mutates the map while we iterate.
+        const all = [...this.monitors.values()];
+        for (const reg of all)
+            this.stop(reg.owner, reg.persona.name);
+    }
+}

package/dist/monitor-parsing.js

@@ -0,0 +1,68 @@
+// A target argument: `group:<n>` or a tab label.
+function parseTarget(word) {
+    const group = /^group:(\d+)$/i.exec(word);
+    if (group)
+        return { kind: 'group', group: Number(group[1]) };
+    if (word.includes(':'))
+        return { error: `Bad target "${word}" (expected a tab label or group:<n>).` };
+    return { kind: 'tab', label: word };
+}
+// `monitor <persona> [target...]` — no targets means inline mode (watch the current tab).
+// `monitor ask <persona> <question>` — query the running monitor's ACP directly.
+export function parseMonitorCommand(input) {
+    const words = input.trim().split(/\s+/).slice(1);
+    if (words[0] === 'ask') {
+        const persona = words[1];
+        const question = words.slice(2).join(' ');
+        if (!persona || !question)
+            return { error: 'Usage: monitor ask <persona> <question>' };
+        return { ask: true, persona, question };
+    }
+    const persona = words[0];
+    if (!persona)
+        return { error: 'Usage: monitor <persona> [tab|group:<n> ...]' };
+    if (words[1] === 'ask')
+        return { error: `Did you mean: monitor ask ${persona} <question>?` };
+    const targets = [];
+    for (const word of words.slice(1)) {
+        const target = parseTarget(word);
+        if ('error' in target)
+            return target;
+        targets.push(target);
+    }
+    return { persona, targets };
+}
+// `unmonitor --all` | `unmonitor <persona> [target]`
+export function parseUnmonitorCommand(input) {
+    const words = input.trim().split(/\s+/).slice(1);
+    if (words[0] === '--all')
+        return { all: true };
+    const persona = words[0];
+    if (!persona)
+        return { error: 'Usage: unmonitor <persona> [tab|group:<n>] | unmonitor --all' };
+    if (words.length === 1)
+        return { persona };
+    const target = parseTarget(words[1]);
+    if ('error' in target)
+        return target;
+    return { persona, target };
+}
+// Extract a suggestion from the monitoring AI's reply. The reply may contain anything;
+// only the marker lines count:
+//   [SUGGESTION]: <text>
+//   [COMMAND]: <optional command>
+// No marker → no suggestion (the persona is told silence is fine).
+export function parseSuggestion(reply) {
+    const text = /^\[SUGGESTION]:\s*(.+)$/m.exec(reply)?.[1]?.trim();
+    if (!text)
+        return null;
+    const command = /^\[COMMAND]:\s*(.+)$/m.exec(reply)?.[1]?.trim();
+    return command ? { text, command } : { text };
+}
+// The output-format instructions appended to every persona's startup prompt.
+export const SUGGESTION_FORMAT = [
+    'When you have a suggestion, reply with exactly this format:',
+    '[SUGGESTION]: <one short sentence>',
+    '[COMMAND]: <a single command the user could run, only if one clearly applies>',
+    'When you have nothing useful to say, reply with the single word: OK',
+].join('\n');

package/dist/monitor-session.js

@@ -0,0 +1,19 @@
+import { messageBus } from './bus.js';
+import { spawnMonitorSession } from './monitor-acp.js';
+import { SUGGESTION_FORMAT } from './monitor-parsing.js';
+export function openMonitorSession(reg, managers, spawn = spawnMonitorSession) {
+    reg.inFlight = true;
+    reg.session = spawn(reg.persona, managers.tab.cwdOf(reg.owner) ?? process.cwd(), {
+        onError: (message) => managers.tab.append(reg.owner, { input: '', output: `monitor ${reg.persona.name}: ${message}` }),
+        onConnect: (info) => { reg.info = info; messageBus.emit('state', { type: 'dirty' }); },
+    });
+    reg.session.prompt(`${reg.persona.body}\n\n${SUGGESTION_FORMAT}`, {
+        onChunk: () => { },
+        onEnd: () => { reg.inFlight = false; },
+        onError: () => { reg.inFlight = false; },
+    });
+}
+export function respawnMonitorSession(reg, managers, spawn = spawnMonitorSession) {
+    reg.session.kill();
+    openMonitorSession(reg, managers, spawn);
+}

package/dist/monitor-targets.js

@@ -0,0 +1,37 @@
+// Target helpers for the monitor manager: validation, live matching, and the color a
+// reporting tab inherits. All operate on the current tab list — group targets are
+// resolved at event time, so group membership stays dynamic.
+export function validateTargets(tabs, personaName, inline, targets) {
+    for (const target of targets) {
+        if (target.kind === 'tab' && tabs.every((t) => t.label !== target.label || t.view === 'monitor')) {
+            return `No tab named "${target.label}".`;
+        }
+        if (target.kind === 'group' && tabs.every((t) => t.group !== target.group)) {
+            return `No group ${target.group}.`;
+        }
+    }
+    // The reporting tab reuses the persona name as its label; an action tab holding that
+    // label would collide with by-label lookups (e.g. runSuggestion's dispatch).
+    if (!inline && tabs.some((t) => t.label === personaName && t.view !== 'monitor')) {
+        return `A tab named "${personaName}" already exists; rename it or pick another persona.`;
+    }
+    return null;
+}
+export function matchesTargets(tabs, targets, tabLabel) {
+    const tab = tabs.find((t) => t.label === tabLabel);
+    if (!tab || tab.view === 'monitor')
+        return false;
+    return targets.some((t) => (t.kind === 'tab' ? t.label === tabLabel : t.group === tab.group));
+}
+// Reporting tabs carry the monitored tab's color: the first tab target's dot color, or
+// the first member of the first group target.
+export function targetColor(tabs, targets) {
+    for (const target of targets) {
+        const tab = target.kind === 'tab'
+            ? tabs.find((t) => t.label === target.label)
+            : tabs.find((t) => t.group === target.group);
+        if (tab)
+            return target.kind === 'group' ? tab.groupColor : tab.dotColor;
+    }
+    return '#5b9cff';
+}

package/dist/monitor-window.js

@@ -0,0 +1,81 @@
+import { makeTab } from './tab.js';
+import { messageBus } from './bus.js';
+// Monitor reporting tabs: each external-mode monitor gets its own view-only tab
+// (`view: 'monitor'`) named after its persona (e.g. `security`, `quality`) and colored
+// after the tab it monitors — the reporting strip and body left-border carry that color.
+// Reporting tabs render in the reporting section below the command bar, never in the
+// action strip, and accept no commands; their only interactions are the per-suggestion
+// Run/Dismiss buttons (RPCs handled here).
+const makeMonitorTab = (name, dotColor, number) => ({
+    // Group 0: reporting tabs sit outside the action-tab group system.
+    ...makeTab(name, dotColor, number, [], [], undefined, 0, dotColor),
+    view: 'monitor',
+    title: name,
+    monitor: { suggestions: [] },
+});
+// A unique label for a new monitor's reporting tab: the persona name, suffixed
+// (`assistant-2`, …) when that label is already taken by any tab. Each monitor instance
+// gets its own window, so the same persona can watch different targets side by side.
+export function allocateMonitorLabel(managers, persona) {
+    const used = new Set(managers.tab.tabs.map((t) => t.label));
+    if (!used.has(persona))
+        return persona;
+    let n = 2;
+    while (used.has(`${persona}-${n}`))
+        n++;
+    return `${persona}-${n}`;
+}
+// All monitor reporting tabs currently open.
+export function monitorTabs(managers) {
+    return managers.tab.tabs.filter((t) => t.view === 'monitor');
+}
+// Open the named monitor's reporting tab or reuse the existing one. Reporting tabs are
+// appended at the end of the tab list so action-tab indices (including `activeTab`)
+// never shift, and the active tab is left untouched.
+export function openMonitorTab(managers, name, dotColor) {
+    const existing = monitorTabs(managers).find((t) => t.label === name);
+    if (existing)
+        return existing;
+    const tabs = managers.tab.tabs;
+    const tab = makeMonitorTab(name, dotColor, tabs.length + 1);
+    managers.tab.tabs = [...tabs, tab];
+    messageBus.emit('state', { type: 'dirty' });
+    return tab;
+}
+// Append a suggestion to the named monitor's feed (opening its tab if needed).
+export function pushSuggestion(managers, name, dotColor, suggestion) {
+    const tab = openMonitorTab(managers, name, dotColor);
+    tab.monitor.suggestions.push(suggestion);
+    messageBus.emit('state', { type: 'dirty' });
+}
+// Close a persona's reporting tab (used when the last monitor feeding it goes away
+// with its owning agent tab).
+export function closeMonitorTab(managers, name) {
+    const index = managers.tab.tabs.findIndex((t) => t.view === 'monitor' && t.label === name);
+    if (index !== -1)
+        managers.tab.closeTab(index);
+}
+// Find a suggestion anywhere in the monitor feeds by id.
+export function findSuggestion(managers, id) {
+    return monitorTabs(managers)
+        .flatMap((t) => t.monitor.suggestions)
+        .find((s) => s.id === id);
+}
+// Remove a suggestion from whichever feed holds it (thumbs-down).
+export function removeSuggestion(managers, id) {
+    for (const tab of monitorTabs(managers)) {
+        const before = tab.monitor.suggestions.length;
+        tab.monitor.suggestions = tab.monitor.suggestions.filter((s) => s.id !== id);
+        if (tab.monitor.suggestions.length !== before)
+            messageBus.emit('state', { type: 'dirty' });
+    }
+}
+// Run a suggestion's command in the tab the suggestion is about (a clicked command
+// line). The suggestion stays in the feed — the history of what was suggested (and run)
+// is part of the record. Monitor tabs themselves never execute commands.
+export function runSuggestion(managers, id) {
+    const suggestion = findSuggestion(managers, id);
+    if (!suggestion?.command)
+        return;
+    managers.command.dispatchTo(suggestion.about, suggestion.command);
+}

package/dist/notifications-tab.js

@@ -0,0 +1,32 @@
+// The notifications tab is a singleton, view-only feed (`view: 'notifications'`) that receives
+// notification-worthy background events as ordinary transcript entries. It mirrors the file tree
+// tab's open-or-reuse, dockable shape (see `file-tree-manager.ts`), but its body is a plain
+// transcript and it accepts no typed input. It is created only by the `notifications` command,
+// never by the event path, and events fired while it is closed are dropped (never buffered).
+export const NOTIFICATIONS_LABEL = 'notifications';
+// The open notifications tab, or undefined when none is open.
+export function notificationsTab(managers) {
+    return managers.tab.tabs.find((t) => t.view === 'notifications');
+}
+// Open the notifications tab or reuse the existing one, optionally docking it into a sidebar.
+// Called only from the `notifications` command. With no `dock`, an existing docked tab is undocked
+// back to the center strip and made active (bare `notifications` always makes the feed visible).
+export function openNotificationsTab(managers, dock) {
+    const existing = notificationsTab(managers);
+    if (existing) {
+        managers.tab.setDock(managers.tab.findIndex(existing.label), dock ?? null);
+        return existing;
+    }
+    managers.tab.openNotificationsTab();
+    if (dock)
+        managers.tab.setDock(managers.tab.findIndex(NOTIFICATIONS_LABEL), dock);
+    return notificationsTab(managers);
+}
+// Append a line to the notifications feed — but only if the tab is already open. When it is closed
+// this is a no-op: the event is dropped, not buffered, and the tab is never created. When open it
+// reuses the standard `append` funnel (unread badge, `entry:appended`, `bufferLines` sync).
+export function appendNotification(managers, entry) {
+    if (!notificationsTab(managers))
+        return;
+    managers.tab.append(NOTIFICATIONS_LABEL, entry);
+}

package/dist/notifications.js

@@ -0,0 +1,87 @@
+import { getConfig } from './config.js';
+import { NOTIFICATIONS_LABEL, notificationsTab, appendNotification } from './notifications-tab.js';
+// Whether an event should be recorded, given the config and the active tab. Defensive against the
+// tab feeding itself. For the five ambient events, both the per-event opt-in toggle and focus
+// suppression (the active tab never notifies about its own activity) apply; the `manual` event
+// bypasses both — an explicit trigger always fires (subject only to the tab being open, enforced
+// in `notify`).
+export function shouldNotify(config, event, tabLabel, activeLabel) {
+    if (tabLabel === NOTIFICATIONS_LABEL)
+        return false;
+    if (event === 'manual' || event === 'auto-approve')
+        return true;
+    if (tabLabel === activeLabel)
+        return false;
+    if (!config)
+        return false;
+    switch (event) {
+        case 'state-change': {
+            return config.events.stateChange;
+        }
+        case 'incoming-message': {
+            return config.events.incomingMessage;
+        }
+        case 'schedule-fire': {
+            return config.events.scheduleFire;
+        }
+        case 'agent-start': {
+            return config.events.agentStart;
+        }
+        case 'rate-limited': {
+            return config.events.rateLimited;
+        }
+    }
+}
+// A compact 12-hour clock time (e.g. `8:32pm`) — hour without a leading zero, two-digit minutes,
+// lowercase am/pm, no seconds. Leads each notification line's provenance header.
+export function formatTimestamp(date) {
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const period = date.getHours() < 12 ? 'am' : 'pm';
+    const hour12 = date.getHours() % 12 === 0 ? 12 : date.getHours() % 12;
+    return `${hour12}:${minutes}${period}`;
+}
+// The message body for an event, rendered after the `<time> <tabLabel>:` header. `detail` carries
+// the event-specific extra: the command for `schedule-fire`, the sender label for
+// `incoming-message`, the user's message for `manual`, and the approver's message for
+// `auto-approve`. The `manual` and `auto-approve` bodies are the message alone — the tab label
+// already leads the line via the header, so repeating it here would double it.
+export function notificationText(event, tabLabel, detail) {
+    switch (event) {
+        case 'state-change': {
+            return `Agent '${tabLabel}' finished`;
+        }
+        case 'agent-start': {
+            return `Agent '${tabLabel}' started`;
+        }
+        case 'rate-limited': {
+            return `Agent '${tabLabel}' is being rate limited`;
+        }
+        case 'schedule-fire': {
+            return `Scheduled: ${detail} in ${tabLabel}`;
+        }
+        case 'incoming-message': {
+            return `Message from ${detail} in ${tabLabel}`;
+        }
+        case 'manual':
+        case 'auto-approve': {
+            return detail ?? '';
+        }
+    }
+}
+// Record a notification for an event on `tabLabel`. Returns immediately (costing nothing, and
+// never creating the tab) while the notifications tab is closed, so the event path is free when the
+// feed is not open. Otherwise it consults the config + focus rules via `shouldNotify` and, on pass,
+// appends the derived line. `message` is the event-specific detail (see `notificationText`).
+export function notify(managers, event, tabLabel, message) {
+    if (!notificationsTab(managers))
+        return;
+    const activeLabel = managers.tab.cur().label;
+    if (!shouldNotify(getConfig().notifications, event, tabLabel, activeLabel))
+        return;
+    const fromColor = managers.tab.tabs.find((t) => t.label === tabLabel)?.dotColor;
+    // The dot label is the notification's provenance header — when, then who — so the line reads
+    // `● 8:32pm janus: <message>`. `fromColor` (looked up from tabLabel) still colors the dot.
+    const from = `${formatTimestamp(new Date())} ${tabLabel}`;
+    const output = notificationText(event, tabLabel, message);
+    appendNotification(managers, { input: '', output, from, fromColor });
+}