conductor-remote 1.99.0 → 1.101.0

package/dist-node/src/server.js

@@ -31,14 +31,24 @@ import { readPrefs, writePrefs } from "./prefs.js";
 import { Reads } from "./reads.js";
 import { decodeRoles, RoleStore, resolveRole, roleModelIssues } from "./roles.js";
 import { isRoute, routeParam, routes } from "./routes.js";
+import { attachRunActivity } from "./run-activity.js";
 import { foldHits, queryTokens, SearchIndex } from "./search.js";
 import { SendOnce } from "./sendonce.js";
 import { SessionPoller } from "./session-poller.js";
 import { readSettings, writeSettings } from "./settings.js";
-import { responseErrorMessage, VIEWING_HEADER, withoutWindowEvidence } from "./shared.js";
+import { isOpenAIRealtimeVoice, isVoiceLanguage, OPENAI_REALTIME_VOICES, responseErrorMessage, VIEWING_HEADER, withoutWindowEvidence } from "./shared.js";
 import { discardStagedAttachment, materializeStagedAttachments, pruneStagedAttachments, stageAttachment, stagedAttachments } from "./staged-attachments.js";
 import { driftWarningLines, readExposeMode, tailscaleBin } from "./tailscale.js";
 import { renderTranscript, transcriptMessage, transcriptThrough } from "./transcript.js";
+import { VoiceBriefBoard } from "./voice/brief.js";
+import { VoiceBroker } from "./voice/broker.js";
+import { openAIOriginForSipHost, readVoiceConfig, voicePort } from "./voice/config.js";
+import { createVoiceGateway } from "./voice/gateway.js";
+import { PreviewStore } from "./voice/preview.js";
+import { createVoiceServer } from "./voice/server.js";
+import { mintSipTicket, missingTicketConfig } from "./voice/ticket.js";
+import { createVoiceTools } from "./voice/tools.js";
+import { createWebRtcCall, MAX_SDP_CHARS } from "./voice/webrtc.js";
 import { autoJoinHotspotMode, currentSsid, looksLikeHotspot, preferredNetworks } from "./wifi.js";
 import { prepareWorkflowRoot, WORKFLOW_ROOT_ROLE } from "./workflow.js";
 import { archiveWorkspace, closeChat, continueWorkspace, createWorkspace, describeActuator, EFFORT_LABELS, listAgentModels, lockBlocked, newChat, pickActuator, restartConductorApp, retryWontHelp, screenLocked, sendNeverStarted, setAgentOptions, setDefaultModel, setRestartGuard, setWorkspaceStatus, stopTurn, UiBusyError, uiBusy, uiQueueDepth, WORKSPACE_STATUS_LABELS, withUiPriority } from "./writes.js";
@@ -150,6 +160,83 @@ const mcpTools = createTools(async (route, opts = {}) => {
     }
     return payload;
 });
+// The voice process surface shares this process (and therefore the one UI lock) but not
+// this server's port. Only its three scoped routes are mounted through Funnel.
+const voiceConfig = readVoiceConfig();
+// Stable but useless outside this OpenAI abuse-control header. Hashing the relay
+// bearer means neither that bearer nor a device identifier leaves the Mac.
+const voiceSafetyIdentifier = crypto.createHash('sha256').update(`conductor-remote:${cfg.token}`).digest('hex');
+const voiceBoards = new Map();
+const voicePreviews = new PreviewStore(path.join(stateDir(), 'voice-previews.json'));
+const voiceBroker = voiceConfig.openaiKey
+    ? new VoiceBroker({
+        apiKey: voiceConfig.openaiKey,
+        apiOrigin: openAIOriginForSipHost(voiceConfig.sipHost),
+        model: voiceConfig.model,
+        voice: voiceConfig.voice,
+        mcpUrl: voiceConfig.publicBaseUrl ? `${voiceConfig.publicBaseUrl}/mcp` : null,
+        mcpToken: voiceConfig.mcpToken,
+        stateFile: path.join(stateDir(), 'voice-calls.json'),
+        tools: callId => voiceToolsForCall(callId),
+        onClose: callId => voiceBoards.delete(callId)
+    })
+    : null;
+function voiceBoard(callId) {
+    let board = voiceBoards.get(callId);
+    if (board)
+        return board;
+    board = new VoiceBriefBoard({ reads, locked: async () => (await screenLocked()) === true, readPrefs, writePrefs });
+    voiceBoards.set(callId, board);
+    return board;
+}
+async function dispatchVoicePreview(preview) {
+    const host = !cfg.host || cfg.host === '0.0.0.0' || cfg.host === '::' ? '127.0.0.1' : cfg.host;
+    const timeoutMs = 75_000;
+    const res = await fetch(`http://${host}:${cfg.port}${routes.sendPrompt.path(preview.sessionId)}`, {
+        method: routes.sendPrompt.method,
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: {
+            authorization: `Bearer ${cfg.token}`,
+            'content-type': 'application/json',
+            'x-relay-client': 'voice',
+            'x-client-timeout-ms': String(timeoutMs)
+        },
+        body: JSON.stringify({
+            workspaceId: preview.workspaceId,
+            text: preview.text,
+            clientId: preview.token
+        })
+    });
+    const payload = (await res.json().catch(() => ({})));
+    return {
+        ok: payload.ok === true,
+        parked: payload.parked === true,
+        error: payload.error ?? (!res.ok ? `HTTP ${res.status}` : undefined)
+    };
+}
+function voiceToolsForCall(callId) {
+    return createVoiceTools({
+        callId,
+        board: voiceBoard(callId),
+        previews: voicePreviews,
+        findSession: sessionId => reads.listSessionStates().find(state => state.sessionId === sessionId) ?? null,
+        dispatch: dispatchVoicePreview,
+        announce: spoken => {
+            if (!voiceBroker?.inject(callId, spoken))
+                console.warn(`[voice] ${callId} could not receive a delivery nudge`);
+        }
+    });
+}
+const voiceGateway = createVoiceGateway({
+    config: () => voiceConfig,
+    broker: () => voiceBroker,
+    rpc: (callId, request) => handleRpc(voiceToolsForCall(callId), request)
+});
+const voiceServer = createVoiceServer({
+    routes: voiceGateway,
+    mcpToken: () => voiceConfig.mcpToken,
+    log: line => console.warn(line)
+});
 // A windowless Conductor that ignores reopen *and* a Dock click can only be fixed
 // by restarting it — and quitting takes any agent mid-turn down with it. So the
 // write path may only do that while nothing is working, which is a DB fact, not
@@ -1357,6 +1444,7 @@ const server = http.createServer(async (req, res) => {
                 const workspaces = reads.listWorkspaces();
                 attachChangeStats(workspaces); // serves the cache now; refreshes stale git stats in the background
                 attachPrStatus(workspaces); // colours pr_status from cache; refreshes stale entries in the background
+                attachRunActivity(workspaces); // flags a live Run wrapper from a cached ps snapshot
                 attachDelegationState(workspaces);
                 // An undelivered first prompt rides along with its workspace: the phone renders it
                 // in that chat rather than tracking delivery itself (see src/firstprompt.ts).
@@ -1565,6 +1653,73 @@ const server = http.createServer(async (req, res) => {
                     }
                 });
             }
+            // POST /api/voice/ticket — the native app presents the same relay bearer as
+            // the PWA, and receives only a two-minute SIP URI. The OpenAI key, webhook
+            // secret and marker key never leave this Mac.
+            if (isRoute(routes.voiceTicket, req.method, pathname)) {
+                const missing = missingTicketConfig(voiceConfig);
+                if (missing.length || !voiceBroker) {
+                    return json(req, res, 503, {
+                        error: 'voice calls are not fully configured on this relay',
+                        missing
+                    });
+                }
+                return json(req, res, 200, mintSipTicket(voiceConfig));
+            }
+            // POST /api/voice/calls — the PWA sends its SDP offer to this authenticated
+            // relay. The relay combines it with the global orchestrator session and
+            // keeps OpenAI's permanent key and every function tool on the Mac.
+            if (isRoute(routes.voiceCall, req.method, pathname)) {
+                if (!voiceConfig.openaiKey || !voiceBroker)
+                    return json(req, res, 503, { error: 'voice needs an OpenAI API key on this relay' });
+                const raw = await readBody(req);
+                if (raw.length > MAX_SDP_CHARS * 2)
+                    return json(req, res, 413, { error: 'WebRTC offer is too large' });
+                const body = JSON.parse(raw || '{}');
+                if (typeof body.sdp !== 'string' || !body.sdp.trim())
+                    return json(req, res, 400, { error: 'WebRTC offer is required' });
+                if (body.sdp.length > MAX_SDP_CHARS)
+                    return json(req, res, 413, { error: 'WebRTC offer is too large' });
+                if (!isOpenAIRealtimeVoice(body.voice))
+                    return json(req, res, 400, { error: `voice must be one of ${OPENAI_REALTIME_VOICES.join(', ')}` });
+                if (!isVoiceLanguage(body.language))
+                    return json(req, res, 400, { error: 'unsupported voice language' });
+                try {
+                    const call = await createWebRtcCall(voiceConfig.openaiKey, openAIOriginForSipHost(voiceConfig.sipHost), body.sdp, {
+                        model: voiceConfig.model,
+                        voice: body.voice,
+                        language: body.language
+                    }, voiceSafetyIdentifier);
+                    voiceBroker.registerWebRtc(call.callId);
+                    return json(req, res, 200, call);
+                }
+                catch (err) {
+                    console.warn('[voice] could not create WebRTC orchestrator call:', err);
+                    return json(req, res, 502, { error: err instanceof Error ? err.message : 'voice call failed' });
+                }
+            }
+            const readyVoiceCall = routeParam(routes.voiceCallReady, req.method, pathname);
+            if (readyVoiceCall) {
+                if (!voiceBroker)
+                    return json(req, res, 503, { error: 'voice is not configured on this relay' });
+                if (!voiceBroker.beginWebRtc(readyVoiceCall))
+                    return json(req, res, 404, { error: 'voice call not found' });
+                return json(req, res, 200, { ok: true });
+            }
+            const endedVoiceCall = routeParam(routes.voiceCallEnd, req.method, pathname);
+            if (endedVoiceCall) {
+                if (!voiceBroker)
+                    return json(req, res, 503, { error: 'voice is not configured on this relay' });
+                try {
+                    if (!(await voiceBroker.hangupWebRtc(endedVoiceCall)))
+                        return json(req, res, 404, { error: 'voice call not found' });
+                    return json(req, res, 200, { ok: true });
+                }
+                catch (err) {
+                    console.warn('[voice] could not hang up WebRTC orchestrator call:', err);
+                    return json(req, res, 502, { error: err instanceof Error ? err.message : 'voice hangup failed' });
+                }
+            }
             // GET /api/settings — relay preferences plus what the phone needs to edit them:
             // the SSIDs this Mac already holds credentials for, so the picker offers a choice
             // instead of asking someone to type a network name from memory on a phone keyboard.
@@ -2757,6 +2912,10 @@ const server = http.createServer(async (req, res) => {
     });
 });
 server.listen(cfg.port, cfg.host, () => {
+    voiceServer.listen(voicePort(), '127.0.0.1', () => {
+        console.info(`  voice:      127.0.0.1:${voicePort()}${voiceBroker ? '' : ' (waiting for OpenAI config)'}`);
+        void voiceBroker?.restore();
+    });
     // Under `yarn dev` the app comes from Vite and only /api comes from here, so the URL worth
     // printing is Vite's — carrying the token, which Vite itself has no way to print.
     const dev = cfg.devWebPort !== undefined;

package/dist-node/src/shared.js

@@ -231,6 +231,32 @@ export function responseErrorMessage(error, fallback) {
  */
 export const HIT_OPEN = '\u0001';
 export const HIT_CLOSE = '\u0002';
+/**
+ * OpenAI's built-in Realtime voices, in the order the phone presents them. The
+ * two voices OpenAI recommends for quality lead the list; every value is shared
+ * with the relay so a stale or hand-written client cannot ask it to configure an
+ * arbitrary voice id.
+ */
+export const OPENAI_REALTIME_VOICES = [
+    'marin',
+    'cedar',
+    'alloy',
+    'ash',
+    'ballad',
+    'coral',
+    'echo',
+    'sage',
+    'shimmer',
+    'verse'
+];
+/** The deliberately small language picker for the first voice surface. */
+export const VOICE_LANGUAGES = ['auto', 'no', 'en'];
+export function isOpenAIRealtimeVoice(value) {
+    return typeof value === 'string' && OPENAI_REALTIME_VOICES.includes(value);
+}
+export function isVoiceLanguage(value) {
+    return typeof value === 'string' && VOICE_LANGUAGES.includes(value);
+}
 const ATTACHMENT_PREFIX = '.context/attachments/';
 /**
  * Read Conductor attachment tokens from prompt text.

package/dist-node/src/speech.js

@@ -0,0 +1,68 @@
+/**
+ * Speech bounding — the two helpers that keep a spoken field inside its budget.
+ *
+ * The voice orchestrator's caps are enforced in relay code rather than in the model's
+ * prompt (design ▸ Constraints), because a prompt that asks for brevity is a request and
+ * a cap is a guarantee. Both callers here are budgets someone else set: a push body has
+ * a payload ceiling, and a roll call has an attention ceiling — roughly 600 characters
+ * before a listener stops holding it.
+ *
+ * `clipExact` is named for the property `notify.ts`'s private `clip` did not have: the
+ * ellipsis counts against the cap, so the result is never longer than what was asked for.
+ * The old helper returned `max + 1` characters, which was invisible against a byte budget
+ * carrying eight bytes of slack and would not be invisible against a spoken one.
+ *
+ * Stdlib-free on purpose, so a fixture test needs nothing but the function.
+ */
+/** Cut back to the last word boundary when one is close enough to the cut to be worth it. */
+const WORD_LOOKBACK = 0.2;
+/**
+ * At most `max` characters, ellipsis included. Prefers a word boundary near the cut, so a
+ * clipped sentence ends on a word rather than mid-syllable, which matters when it is read
+ * aloud rather than shown.
+ */
+export function clipExact(text, max) {
+    if (max <= 0)
+        return '';
+    if (text.length <= max)
+        return text;
+    if (max === 1)
+        return '…';
+    const hard = text.slice(0, max - 1);
+    // Only back off when the cut actually lands inside a word. A cut that already falls on a
+    // space has nothing to repair, and backing off anyway throws away a whole word for free.
+    const splitsWord = !/\s/.test(text.charAt(max - 1));
+    const space = hard.lastIndexOf(' ');
+    const body = splitsWord && space >= Math.floor((max - 1) * (1 - WORD_LOOKBACK)) ? hard.slice(0, space) : hard;
+    return `${body.trimEnd()}…`;
+}
+/**
+ * One spoken line: code fences become an ellipsis, every run of whitespace becomes one
+ * space, then the whole thing is clipped. A transcript entry is written to be read on a
+ * screen, so its newlines and fences are layout that speech has no use for.
+ */
+export function oneLine(text, max) {
+    return clipExact(text
+        .replace(/```[\s\S]*?```/g, '…')
+        .replace(/\s+/g, ' ')
+        .trim(), max);
+}
+/**
+ * Turn the Markdown that is useful on screen into prose that is useful in an
+ * ear. The visible transcript remains untouched and canonical: this only drops
+ * things that a speech engine would otherwise pronounce literally (URLs,
+ * backticks, heading marks, and fenced source code).
+ */
+export function speechText(text, max) {
+    return clipExact(text
+        .replace(/```[\s\S]*?```/g, '…')
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+        .replace(/`([^`\n]+)`/g, '$1')
+        .replace(/https?:\/\/\S+/g, 'link')
+        .replace(/^\s{0,3}(?:#{1,6}|>|[-*+])\s+/gm, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim(), max);
+}

package/dist-node/src/voice/brief.js

@@ -0,0 +1,260 @@
+import { clipExact, oneLine, speechText } from "../speech.js";
+const DORMANT_MS = 7 * 24 * 60 * 60 * 1000;
+const DORMANT_LABELS = new Set(['backlog', 'done', 'canceled', 'cancelled']);
+const OVERVIEW_PAGE_SIZE = 3;
+function clean(text) {
+    return text
+        .replace(/[*_`#]+/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function lastParagraph(text) {
+    return (text
+        .trim()
+        .split(/\n\s*\n/)
+        .map(clean)
+        .filter(Boolean)
+        .at(-1) ?? '');
+}
+/** Parse `D<N> —`, lettered choices, `(recommended)`, and `Recommendation:` briefs. */
+export function parseProseDecision(text) {
+    const lines = text.split('\n');
+    const heading = lines.findIndex(line => /^\s*#{0,6}\s*\**D\d+\s*[—:-]\s*/i.test(line));
+    if (heading < 0)
+        return null;
+    const question = clean(lines[heading].replace(/^\s*#{0,6}\s*\**D\d+\s*[—:-]\s*/i, ''));
+    if (!question)
+        return null;
+    const options = [];
+    let consequence = '';
+    for (let i = heading + 1; i < lines.length; i++) {
+        const line = clean(lines[i]);
+        if (/^[A-Z][.)]\s+/.test(line))
+            options.push(line);
+        else if (/^Recommendation\s*:/i.test(line))
+            consequence = line.replace(/^Recommendation\s*:\s*/i, '');
+    }
+    if (!options.length)
+        return null;
+    const before = lines.slice(0, heading).join('\n');
+    return { situation: lastParagraph(before), question, options, consequence };
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Parse the input shape used by AskUserQuestion without depending on a provider SDK. */
+export function parseStructuredQuestion(input) {
+    const root = object(input);
+    const first = Array.isArray(root?.questions) ? object(root.questions[0]) : null;
+    if (!first || typeof first.question !== 'string' || !first.question.trim())
+        return null;
+    const rawOptions = Array.isArray(first.options) ? first.options : [];
+    const options = rawOptions.flatMap((raw, index) => {
+        const option = object(raw);
+        if (!option || typeof option.label !== 'string' || !option.label.trim())
+            return [];
+        const letter = String.fromCharCode(65 + index);
+        const description = typeof option.description === 'string' ? clean(option.description) : '';
+        return [`${letter}. ${clean(option.label)}${description ? ` — ${description}` : ''}`];
+    });
+    if (!options.length)
+        return null;
+    return { situation: '', question: clean(first.question), options, consequence: '' };
+}
+function parseDate(value) {
+    if (!value)
+        return 0;
+    // SQLite values have no zone marker but are UTC in Conductor's DB.
+    const normalized = value.includes('T') || /Z$/.test(value) ? value : `${value.replace(' ', 'T')}Z`;
+    const parsed = Date.parse(normalized);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function statusLabel(workspace) {
+    return workspace.manual_status ?? workspace.derived_status;
+}
+function isDormant(state, workspace, now) {
+    if (state.status !== 'idle' && state.status)
+        return false;
+    const old = now - parseDate(state.updatedAt) > DORMANT_MS;
+    const labelled = DORMANT_LABELS.has((statusLabel(workspace) ?? '').toLowerCase());
+    return old || labelled;
+}
+function overviewRank(state) {
+    if (state.status === 'error')
+        return 0;
+    if (state.status === 'needs_user_input' || state.status === 'needs_plan_response')
+        return 1;
+    if (state.status === 'working')
+        return 2;
+    return 3;
+}
+function overviewStatus(state, workspace) {
+    if (state.status === 'error')
+        return 'has an error';
+    if (state.status === 'needs_user_input' || state.status === 'needs_plan_response')
+        return 'needs you';
+    if (state.status === 'working')
+        return 'is working';
+    if (workspace.unread_sessions.some(session => session.id === state.sessionId))
+        return 'has an unread update';
+    return 'is recently active';
+}
+function fallbackDecision(state, said) {
+    const last = lastParagraph(said) || `${state.workspaceTitle} needs attention.`;
+    return {
+        situation: last,
+        question: state.status === 'error' ? 'What should the agent try next?' : 'What should this agent do next?',
+        options: ['A. Send a focused instruction.', 'B. Skip this item for now.'],
+        consequence: 'Sending unblocks the owning workspace; skipping leaves it in the queue.'
+    };
+}
+function spokenDecision(item) {
+    const d = item.decision;
+    const fields = [
+        `Situation: ${item.title}. ${d.situation}`,
+        `Decision needed: ${d.question}`,
+        `Safe options: ${d.options.join(' ')}`,
+        d.consequence ? `Consequence: ${d.consequence}` : ''
+    ]
+        .filter(Boolean)
+        .map(field => oneLine(field, 180));
+    return clipExact(fields.join(' '), 400);
+}
+export class VoiceBriefBoard {
+    deps;
+    now;
+    cached = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+    }
+    build() {
+        const workspaces = new Map(this.deps.reads.listWorkspaces().map(ws => [ws.id, ws]));
+        const marks = this.deps.readPrefs().readMarks;
+        let working = 0;
+        let dormant = 0;
+        const queue = [];
+        for (const state of this.deps.reads.listSessionStates()) {
+            const workspace = workspaces.get(state.workspaceId);
+            if (!workspace)
+                continue;
+            if (state.status === 'working') {
+                working++;
+                continue;
+            }
+            if (isDormant(state, workspace, this.now())) {
+                dormant++;
+                continue;
+            }
+            if ((marks[state.sessionId] ?? '') >= state.updatedAt)
+                continue;
+            const said = this.deps.reads.lastAssistantText(state.sessionId) ?? '';
+            const prose = parseProseDecision(said);
+            const structured = prose ? null : parseStructuredQuestion(this.deps.reads.lastQuestionInput(state.sessionId));
+            const hasQuestion = Boolean(prose ?? structured) || /\?\s*$/.test(said.trim());
+            const unread = workspace.unread_sessions.some(s => s.id === state.sessionId);
+            const priority = state.status === 'error'
+                ? 0
+                : state.status === 'needs_user_input' || state.status === 'needs_plan_response'
+                    ? 1
+                    : hasQuestion
+                        ? 2
+                        : unread
+                            ? 3
+                            : 4;
+            queue.push({
+                workspaceId: state.workspaceId,
+                sessionId: state.sessionId,
+                title: state.sessionTitle ? `${state.workspaceTitle}, ${state.sessionTitle}` : state.workspaceTitle,
+                updatedAt: state.updatedAt,
+                priority,
+                decision: prose ?? structured ?? fallbackDecision(state, said)
+            });
+        }
+        queue.sort((a, b) => a.priority - b.priority || b.updatedAt.localeCompare(a.updatedAt));
+        return { queue, working, dormant };
+    }
+    items() {
+        if (!this.cached)
+            this.cached = this.build().queue;
+        return this.cached;
+    }
+    /** A deliberately uncached read: a new overview must not replay the call-opening tally. */
+    async workspaceOverview(cursor = 0) {
+        const workspaces = new Map(this.deps.reads.listWorkspaces().map(workspace => [workspace.id, workspace]));
+        const grouped = new Map();
+        for (const state of this.deps.reads.listSessionStates()) {
+            if (!workspaces.has(state.workspaceId))
+                continue;
+            const states = grouped.get(state.workspaceId) ?? [];
+            states.push(state);
+            grouped.set(state.workspaceId, states);
+        }
+        let dormant = 0;
+        const items = [];
+        for (const [workspaceId, workspace] of workspaces) {
+            const current = (grouped.get(workspaceId) ?? []).filter(state => !isDormant(state, workspace, this.now()));
+            if (!current.length) {
+                dormant++;
+                continue;
+            }
+            current.sort((a, b) => overviewRank(a) - overviewRank(b) || parseDate(b.updatedAt) - parseDate(a.updatedAt));
+            const state = current[0];
+            const said = this.deps.reads.lastAssistantText(state.sessionId) ?? '';
+            items.push({
+                workspaceId,
+                sessionId: state.sessionId,
+                title: state.sessionTitle ? `${state.workspaceTitle}, ${state.sessionTitle}` : state.workspaceTitle,
+                status: overviewStatus(state, workspace),
+                updatedAt: state.updatedAt,
+                update: oneLine(speechText(said, 150), 150),
+                rank: overviewRank(state)
+            });
+        }
+        items.sort((a, b) => a.rank - b.rank || parseDate(b.updatedAt) - parseDate(a.updatedAt));
+        const offset = Number.isFinite(cursor) ? Math.max(0, Math.floor(cursor)) : 0;
+        const rankedPage = items.slice(offset, offset + OVERVIEW_PAGE_SIZE);
+        const page = rankedPage.map(({ rank: _rank, ...item }) => item);
+        const next = offset + page.length < items.length ? offset + page.length : null;
+        const noun = items.length === 1 ? 'workspace' : 'workspaces';
+        const lines = page.map(item => `${item.title} ${item.status}.${item.update ? ` ${item.update}` : ' No agent update yet.'}`);
+        const more = next === null ? '' : ` ${items.length - next} more current; ask me to continue.`;
+        const none = items.length ? '' : ' Nothing is active right now.';
+        return {
+            spoken: clipExact(`Fresh overview: ${items.length} current ${noun}, ${dormant} dormant. ${lines.join(' ')}${more}${none}`.trim(), 700),
+            current: items.length,
+            dormant,
+            cursor: next,
+            workspaces: page
+        };
+    }
+    async rollCall() {
+        const built = this.build();
+        this.cached = built.queue;
+        const locked = await this.deps.locked();
+        const needsYou = built.queue.filter(item => item.priority < 4).length;
+        const heads = built.queue.slice(0, 3).map(item => item.title);
+        const spoken = clipExact(`${locked ? 'Mac is locked; sends will park.' : 'Mac is unlocked; sends can land.'} ${built.working} working, ${needsYou} need you, ${built.dormant} dormant.${heads.length ? ` Queue starts with ${heads.join(', ')}.` : ''}`, 600);
+        return { spoken, working: built.working, needsYou, dormant: built.dormant, queue: built.queue };
+    }
+    async nextDecision(cursor = 0) {
+        const item = this.items()[Math.max(0, Math.floor(cursor))];
+        if (!item)
+            return null;
+        return {
+            spoken: spokenDecision(item),
+            cursor: Math.max(0, Math.floor(cursor)) + 1,
+            workspaceId: item.workspaceId,
+            sessionId: item.sessionId
+        };
+    }
+    /** A dispatch or an explicit spoken skip is handled; merely hearing the item is not. */
+    markHandled(sessionId) {
+        const item = this.items().find(candidate => candidate.sessionId === sessionId);
+        if (!item)
+            return;
+        this.deps.writePrefs({ readMarks: { [sessionId]: item.updatedAt } });
+    }
+}