@vascend/talos 0.1.0

package/dist/vascend/kingdom-run.js

@@ -0,0 +1,506 @@
+// Kingdoms Mode per host NON testuali.
+//
+// La TUI disegna la sua board a caratteri e sa tutto quello che succede; ogni
+// altro host (la chat di Horizon, l'RPC) vedeva invece una sola tool call
+// ferma per minuti, senza sapere quanti vassalli fossero vivi ne' cosa
+// stessero facendo. Qui l'orchestrazione emette gli stessi fatti come EVENTI
+// strutturati, e chi disegna decide come.
+//
+// Il testo di ritorno e' quello che l'agente riceve come risultato del tool:
+// report per castello, indice delle stanze del regno, nota git e rami in
+// sospeso.
+import { isAbsolute, resolve } from "node:path";
+import { RoomMemory } from "./room-memory.js";
+import { kingdomBus } from "./kingdom-bus.js";
+import { kingdomLive } from "./kingdom-live.js";
+import { resolveKingdomBus } from "./kingdom-channel.js";
+import { collectConflicts, formatConflictList, runKingdomWarm, warmConcurrency, } from "./kingdom.js";
+import { registerTeam, updateTeamMember } from "./team-session.js";
+import { worktreeMode } from "./worktree.js";
+const LABEL_MAX = 60;
+const SUMMARY_MAX = 300;
+// Cosa dice un vassallo arriva a delta di pochi caratteri. Mandarli cosi' come
+// sono farebbe un evento per token; accorpiamo fino a un paragrafo o al primo
+// confine del turno.
+const SAY_FLUSH_CHARS = 480;
+const SAY_MAX = 4000;
+const TOOL_OUTPUT_MAX = 900;
+// Un comando di shell puo' essere una pipeline lunga: si tiene per intero fin
+// dove resta leggibile, non lo si riduce a una riga.
+const SHELL_COMMAND_MAX = 1200;
+let kingdomRunSequence = 0;
+export async function runKingdomForHost(input) {
+    const { harness, castles, signal, sink, confirm } = input;
+    const env = input.env ?? process.env;
+    // La sessione dura quanto la conversazione, uno swarm no. Un id riusato
+    // faceva fondere nella UI il regno concluso con quello successivo.
+    kingdomRunSequence = (kingdomRunSequence + 1) % 0xfffff;
+    const kingdomId = `kw-${harness.session.id}-${Date.now().toString(36)}-${kingdomRunSequence.toString(36)}`;
+    const concurrency = warmConcurrency(env);
+    const worktree = worktreeMode(env);
+    // Bus pulito per il nuovo regno (in memoria e sul canale persistente).
+    kingdomBus.clear(kingdomId);
+    kingdomLive.clear(kingdomId);
+    try {
+        resolveKingdomBus(env, harness.config.sessionDir).clear(kingdomId);
+    }
+    catch {
+        // canale file-based non disponibile: il regno gira lo stesso
+    }
+    const info = castles.map((c) => ({
+        slug: c.slug,
+        goal: c.goal,
+        after: [...(c.after ?? [])],
+        ...(c.parent ? { parent: c.parent } : {}),
+        ...(c.role ? { role: c.role } : {}),
+        ...(c.castle ? { castle: c.castle } : {}),
+        ...(c.tasks?.length ? { tasks: [...c.tasks] } : {}),
+        ...(c.model ? { model: c.model } : {}),
+        ...(c.effort ? { effort: c.effort } : {}),
+        ...(c.tools ? { tools: c.tools } : {}),
+    }));
+    sink({ type: "kingdom", phase: "start", kingdomId, concurrency, worktree, castles: info });
+    for (const castle of castles) {
+        sink({
+            type: "kingdom",
+            phase: "message",
+            kind: "assignment",
+            from: castle.parent?.trim() || "orchestratore",
+            to: castle.slug,
+            text: `Task assegnato: ${clamp(castle.goal, 900)}`,
+            ...(castle.castle ? { workstreamId: castle.castle } : {}),
+            ...(castle.tasks?.[0] ? { taskRef: String(castle.tasks[0]) } : {}),
+        });
+    }
+    const started = new Set();
+    const nestedCalls = new Map();
+    const nestedCallKey = (slug, id) => `${slug}\u0000${id}`;
+    // Testo in attesa di essere accorpato, per collaboratore.
+    const saying = new Map();
+    // Quanto ha consumato ognuno, cumulato. Il conto della sessione principale
+    // non vede le sessioni figlie: senza questo, con cinque agenti al lavoro il
+    // costo mostrato in chat e' quello di uno solo.
+    const spesa = new Map();
+    const flushSay = (slug) => {
+        const buffered = (saying.get(slug) ?? "").trim();
+        saying.delete(slug);
+        if (!buffered)
+            return;
+        sink({ type: "kingdom", phase: "say", slug, text: buffered.slice(0, SAY_MAX), at: Date.now() });
+    };
+    const onEvent = (slug, event) => {
+        if (event.type === "usage") {
+            sink({ ...event, record: { ...event.record, actor: event.record.actor ?? slug } });
+            return;
+        }
+        // Gli swarm annidati emettono gia' fatti Kingdom completi. Li inoltriamo
+        // senza attribuirli per errore al padre che li ha generati.
+        if (event.type === "kingdom") {
+            if (event.phase !== "start" && event.phase !== "end")
+                sink(event);
+            return;
+        }
+        const slash = slug.lastIndexOf("/");
+        const parent = slash > 0 ? slug.slice(0, slash) : "";
+        const route = slug.split("/").filter(Boolean);
+        const assignment = {
+            ...(route[0] && route.length > 1 ? { workstreamId: route[0] } : {}),
+            ...(route[1] ? { taskRefs: [route[1]], parentTaskRef: route[1] } : {}),
+        };
+        if (!started.has(slug)) {
+            started.add(slug);
+            sink({
+                type: "kingdom", phase: "vassal", slug, state: "start", ...(parent ? { parent } : {}), ...assignment,
+            });
+        }
+        // Il DISCORSO del collaboratore. Prima si fermava alla sua sessione: l'host
+        // vedeva la sequenza dei comandi ma non il perche', e una scheda piena di
+        // tool call non e' una conversazione. Il testo esce accorpato, mai a delta.
+        if (event.type === "text") {
+            const buffered = (saying.get(slug) ?? "") + event.delta;
+            // Si taglia dove finisce un pensiero (riga vuota), non a meta' frase.
+            const cut = buffered.length >= SAY_FLUSH_CHARS ? buffered.lastIndexOf("\n\n") : -1;
+            if (cut > 0) {
+                saying.set(slug, buffered.slice(cut + 2));
+                const chunk = buffered.slice(0, cut).trim();
+                if (chunk)
+                    sink({ type: "kingdom", phase: "say", slug, text: chunk.slice(0, SAY_MAX), at: Date.now() });
+            }
+            else if (buffered.length >= SAY_MAX) {
+                saying.set(slug, "");
+                sink({ type: "kingdom", phase: "say", slug, text: buffered.slice(0, SAY_MAX), at: Date.now() });
+            }
+            else {
+                saying.set(slug, buffered);
+            }
+            return;
+        }
+        // Un messaggio dell'utente e' appena entrato nel contesto DI QUESTO
+        // collaboratore: la sua scheda puo' segnarlo come letto, con l'istante.
+        if (event.type === "user_message") {
+            sink({
+                type: "kingdom",
+                phase: "inbox",
+                slug,
+                messageId: event.id,
+                text: clamp(event.text, 900),
+                state: "read",
+                at: Number(event.at) || Date.now(),
+            });
+            return;
+        }
+        // Prima di qualunque altro fatto il discorso in sospeso va chiuso, o
+        // finirebbe in coda a cose successe dopo.
+        if (event.type === "tool_call" || event.type === "turn_end" || event.type === "done" || event.type === "error") {
+            flushSay(slug);
+        }
+        if (event.type === "turn_end" && event.usage) {
+            const corrente = spesa.get(slug) ?? { input: 0, output: 0, cost: 0, turns: 0 };
+            const prossimo = {
+                input: corrente.input + (Number(event.usage.inputTokens) || 0),
+                output: corrente.output + (Number(event.usage.outputTokens) || 0),
+                cost: corrente.cost + (Number(event.usage.costUsd) || 0),
+                turns: corrente.turns + 1,
+            };
+            spesa.set(slug, prossimo);
+            sink({
+                type: "kingdom",
+                phase: "usage",
+                slug,
+                inputTokens: prossimo.input,
+                outputTokens: prossimo.output,
+                totalTokens: prossimo.input + prossimo.output,
+                ...(prossimo.cost > 0 ? { costUsd: prossimo.cost } : {}),
+                turns: prossimo.turns,
+                at: Date.now(),
+            });
+        }
+        if (event.type === "tool_call") {
+            const arg = firstArg(event.call.input);
+            const command = shellCommand(event.call.name, event.call.input);
+            sink({
+                type: "kingdom",
+                phase: "tool",
+                slug,
+                callId: event.call.id,
+                tool: event.call.name,
+                ...(arg ? { args: clamp(arg, 240) } : {}),
+                ...(command ? { command } : {}),
+                state: "start",
+                at: Date.now(),
+            });
+        }
+        if (event.type === "tool_result") {
+            // L'esito e' la meta' che mancava: senza, la scheda mostra dieci comandi
+            // partiti e nessuno concluso, e chi guarda non sa se stia avanzando.
+            const call = nestedCalls.get(nestedCallKey(slug, event.result.callId));
+            sink({
+                type: "kingdom",
+                phase: "tool",
+                slug,
+                callId: event.result.callId,
+                tool: call?.name ?? "",
+                state: event.result.isError ? "error" : "ok",
+                output: clamp(String(event.result.output ?? ""), TOOL_OUTPUT_MAX),
+                at: Date.now(),
+            });
+        }
+        const mapped = vassalActivity(event);
+        if (mapped)
+            sink({
+                type: "kingdom",
+                phase: "vassal",
+                slug,
+                state: mapped.state,
+                ...(mapped.label ? { label: mapped.label } : {}),
+                ...(parent ? { parent } : {}),
+                ...assignment,
+            });
+        // I messaggi fra vassalli sono il grafo di cooperazione: vanno estratti
+        // dalla tool call, non dedotti dal testo.
+        if (event.type === "tool_call" && event.call.name === "team_say") {
+            const rawTo = typeof event.call.input["to"] === "string" && event.call.input["to"]
+                ? String(event.call.input["to"]) : "tutti";
+            const to = parent
+                && rawTo !== "tutti"
+                && rawTo !== "orchestratore"
+                && !rawTo.includes("/")
+                && rawTo !== route[0]
+                ? `${parent}/${rawTo}`
+                : rawTo;
+            sink({
+                type: "kingdom",
+                phase: "message",
+                from: slug,
+                to,
+                kind: "message",
+                text: clamp(String(event.call.input["text"] ?? ""), 900),
+                ...(slug.includes("/") ? {
+                    workstreamId: slug.split("/")[0],
+                    taskRef: slug.split("/")[1] ?? "",
+                } : {}),
+            });
+        }
+        // Il piano e i file modificati dentro i collaboratori devono attraversare
+        // il confine del regno. Prima restavano nelle sessioni figlie: il JSON del
+        // piano avanzava, mentre la board Horizon rimaneva a 0/N.
+        if (event.type === "tool_call") {
+            nestedCalls.set(nestedCallKey(slug, event.call.id), {
+                name: event.call.name,
+                input: event.call.input,
+            });
+        }
+        if (event.type === "tool_result") {
+            const key = nestedCallKey(slug, event.result.callId);
+            const call = nestedCalls.get(key);
+            nestedCalls.delete(key);
+            if (!call || event.result.isError)
+                return;
+            const output = String(event.result.output ?? "");
+            const workstreamId = String(call.input["castle"] ?? route[0] ?? "master").trim() || "master";
+            const taskRef = String(call.input["task"] ?? route[1] ?? "").trim();
+            if (call.name === "vascend_mark" && taskRef && /^\[[^\]]+\]\s+T\d+/i.test(output)) {
+                const rawStatus = String(call.input["status"] ?? "completed");
+                const status = rawStatus === "pending" || rawStatus === "running" || rawStatus === "failed" ? rawStatus : "completed";
+                sink({
+                    type: "kingdom",
+                    phase: "task",
+                    slug,
+                    workstreamId,
+                    taskRef,
+                    status,
+                    at: Date.now(),
+                });
+            }
+            else if (call.name === "vascend_note" && /^nota aggiunta a /i.test(output)) {
+                const text = clamp(String(call.input["note"] ?? ""), 900);
+                if (text) {
+                    sink({
+                        type: "kingdom",
+                        phase: "note",
+                        slug,
+                        workstreamId,
+                        ...(taskRef ? { taskRef } : {}),
+                        text,
+                        at: Date.now(),
+                    });
+                }
+            }
+            else if ((call.name === "write_file" || call.name === "edit_file")
+                && /^(?:scritto|accodato|modificato):/i.test(output)) {
+                const rawPath = String(call.input["path"] ?? "").trim();
+                if (rawPath) {
+                    const target = isAbsolute(rawPath) ? rawPath : resolve(harness.config.cwd, rawPath);
+                    sink({
+                        type: "kingdom",
+                        phase: "file",
+                        slug,
+                        path: target,
+                        operation: call.name === "write_file" ? "write" : "edit",
+                        ...(workstreamId ? { workstreamId } : {}),
+                        ...(taskRef ? { taskRef } : {}),
+                        edit: editPayload(call.name, call.input),
+                    });
+                }
+            }
+        }
+    };
+    const lavoro = (async () => runKingdomWarm({
+        harness,
+        kingdomId,
+        castles,
+        signal,
+        confirm,
+        ask: input.ask,
+        concurrency,
+        onEvent,
+        onMemberState: (slug, status, report) => {
+            updateTeamMember(kingdomId, slug, { status, ...(report ? { summary: report.summary, error: report.error, artifacts: report.artifacts } : {}) });
+            if (status === "failed")
+                sink({ type: "kingdom", phase: "vassal", slug, state: "error", label: clamp(report?.error ?? "incarico fallito", SUMMARY_MAX) });
+            if (report) {
+                try {
+                    resolveKingdomBus(env, harness.config.sessionDir).post(kingdomId, slug, null, report.ok ? `Completato: ${report.summary.slice(0, 3000)}` : `Fallito: ${report.error ?? report.summary}`, Date.now());
+                }
+                catch { /* reports remain available even if the message store is unavailable */ }
+            }
+        },
+        worktree,
+        ...(input.fileCoordination ? { fileCoordination: input.fileCoordination } : {}),
+        ...(input.baseBranch ? { baseBranch: input.baseBranch } : {}),
+        onNotice: (text) => sink({ type: "kingdom", phase: "notice", text }),
+    }))();
+    /* Staccato: la squadra parte e il turno prosegue. La promessa non si perde,
+       va nel registro delle squadre vive; chi ha ingaggiato puo' parlarci con
+       team_say, leggerne le risposte e raccogliere i risultati con team_report.
+       Il resto di questa funzione (riepilogo, rami, note) e' cio' che si fa a
+       lavoro FINITO: qui si riattacca alla promessa invece di bloccare. */
+    if (input.detach) {
+        registerTeam({
+            sessionDir: harness.config.sessionDir,
+            id: kingdomId,
+            sessionId: String(harness.session.id || ""),
+            members: castles.map((c) => ({
+                slug: c.slug,
+                role: String(c.role ?? "collaboratore"),
+                mandate: clamp(c.goal ?? "", 300),
+                ...(c.after ? { after: c.after } : {}), ...(c.area ? { area: c.area } : {}),
+                ...(c.castle ? { castle: c.castle } : {}), ...(c.tasks ? { tasks: c.tasks } : {}),
+            })),
+            work: lavoro.then((reports) => chiudi(reports)),
+            at: Date.now(),
+        });
+        const elenco = castles.map((c) => `${c.slug}${c.role ? ` (${c.role})` : ""}`).join(", ");
+        return `Squadra al lavoro: ${elenco}.
+`
+            + `Gli incarichi pronti partono entro il limite di concorrenza; gli altri attendono dipendenze o aree libere. Parlagli con team_say, leggi cosa rispondono con `
+            + `team_inbox, e quando serve raccogli i risultati con team_report. Non aspettarli fermo: `
+            + `se non hai altro da fare usa team_wait.`;
+    }
+    return chiudi(await lavoro);
+    // Cio' che si fa quando la squadra ha finito: riepilogo per collaboratore,
+    // indice delle stanze, nota sui rami. Identico nei due percorsi.
+    function chiudi(reports) {
+        // Ultime parole rimaste nel buffer di chi ha finito senza un confine di turno.
+        for (const slug of [...saying.keys()])
+            flushSay(slug);
+        kingdomLive.clear(kingdomId);
+        for (const report of reports) {
+            updateTeamMember(kingdomId, report.slug, { status: report.ok ? "completed" : "failed", summary: report.summary, error: report.error, artifacts: report.artifacts });
+            sink({
+                type: "kingdom",
+                phase: "message",
+                kind: "result",
+                from: report.slug,
+                to: report.parent?.trim() || "orchestratore",
+                text: report.ok
+                    ? `Risultato: ${clamp(report.summary || "Task completato", 900)}`
+                    : `Errore: ${clamp(report.error || report.summary || "Task non completato", 900)}`,
+                ...(report.workstreamId ? { workstreamId: report.workstreamId } : {}),
+                ...(report.taskRefs?.[0] ? { taskRef: report.taskRefs[0] } : {}),
+            });
+        }
+        sink({ type: "kingdom", phase: "end", reports: reports.map(toSummary) });
+        return formatKingdomOutcome(reports, harness.config.sessionDir, kingdomId);
+    }
+}
+// Frammenti della modifica, tagliati: bastano a disegnare un diff leggibile e
+// non trasformano un evento in un trasferimento di file.
+const EDIT_FRAGMENT_MAX = 8000;
+function editPayload(tool, input) {
+    const cut = (value) => String(value ?? "").slice(0, EDIT_FRAGMENT_MAX);
+    if (tool === "edit_file") {
+        const oldString = cut(input["old_string"]);
+        const newString = cut(input["new_string"]);
+        if (!oldString && !newString)
+            return undefined;
+        return { oldString, newString };
+    }
+    if (tool === "write_file") {
+        const content = cut(input["content"]);
+        if (!content)
+            return undefined;
+        return { content, append: input["append"] === true };
+    }
+    return undefined;
+}
+// Attivita' del vassallo in una riga. Non tutto merita un evento: il testo in
+// streaming e i risultati dei tool riempirebbero la UI senza dire di piu'.
+function vassalActivity(event) {
+    if (event.type === "tool_call") {
+        const arg = firstArg(event.call.input);
+        return { state: "active", label: clamp(`${event.call.name}${arg ? `(${arg})` : ""}`, LABEL_MAX) };
+    }
+    if (event.type === "turn_start")
+        return { state: "active", label: "Pianifica il task" };
+    if (event.type === "done")
+        return { state: "done" };
+    if (event.type === "error")
+        return { state: "error", label: clamp(event.message, LABEL_MAX) };
+    return null;
+}
+function toSummary(report) {
+    return {
+        slug: report.slug,
+        ok: report.ok,
+        rooms: report.rooms,
+        summary: clamp(report.summary, SUMMARY_MAX),
+        ...(report.model ? { model: report.model } : {}),
+        ...(report.role ? { role: report.role } : {}),
+        ...(report.parent ? { parent: report.parent } : {}),
+        ...(report.workstreamId ? { workstreamId: report.workstreamId } : {}),
+        ...(report.taskRefs?.length ? { taskRefs: [...report.taskRefs] } : {}),
+        ...(report.parentTaskRef ? { parentTaskRef: report.parentTaskRef } : {}),
+        ...(report.error ? { error: clamp(report.error, LABEL_MAX * 2) } : {}),
+        ...(report.branch ? { branch: report.branch } : {}),
+        ...(report.merge ? { merged: report.merge.ok } : {}),
+    };
+}
+// Risultato testuale del tool: quello che l'agente legge per sapere cosa hanno
+// prodotto i vassalli e cosa resta da fare a mano.
+export function formatKingdomOutcome(reports, sessionDir, kingdomId) {
+    const lines = reports
+        .map((r) => {
+        const merge = r.merge
+            ? (r.merge.ok ? " · merge ok" : ` · merge fallito (${r.merge.conflict ? "conflitto" : "errore"}, ramo ${r.branch} conservato)`)
+            : "";
+        return `[${r.slug}] ${r.ok ? "ok" : "fallito"} (${r.rooms} attivita)${r.error ? ` errore: ${r.error}` : ""}${merge}: ${clamp(r.summary, SUMMARY_MAX)}`;
+    })
+        .join("\n");
+    let index = "";
+    try {
+        const block = RoomMemory.open(sessionDir, kingdomId).indexBlock();
+        if (block.trim())
+            index = `\n\nATTIVITA ARCHIVIATE (recall per il dettaglio):\n${block}`;
+    }
+    catch {
+        // nessuna memoria del regno: il report resta valido
+    }
+    const isolated = reports.some((r) => r.branch);
+    const conflicts = collectConflicts(reports);
+    const gitNote = isolated
+        ? `\n\n[NOTA_GIT]
+@stato[rami]: ogni collaboratore in worktree isolato; rami merge-ati nel ramo base
+@conflitti[merge]: ${conflicts.length ? `${conflicts.map((r) => r.slug).join(", ")} NON merge-ati (rami conservati, risoluzione manuale)` : "nessuno"}
+@azione[consegna]: verifica diff e controlli nel ramo base; push solo se richiesto dall'utente`
+        : `\n\n[NOTA_GIT]
+@stato[modifiche]: nel working tree, NON committate (i collaboratori non fanno git: working dir condivisa)
+@azione[consegna]: verifica diff e controlli; commit e push solo se richiesti dall'utente`;
+    const stash = formatConflictList(conflicts);
+    return `ESECUZIONE ATTIVITA CONCLUSA · ${reports.length} gruppi\n${lines}${index}${gitNote}${stash ? `\n\n${stash}` : ""}`;
+}
+// Il comando di shell COME E' SCRITTO: a capo, indentazione e pipe intatti.
+// Non passa da `clamp`, che schiaccerebbe tutto su una riga — ed e' proprio
+// la forma che rende leggibile una pipeline. Solo i tool che eseguono davvero
+// qualcosa: per un `read` il "comando" non esiste e mostrarlo mentirebbe.
+function shellCommand(tool, input) {
+    if (!/(?:bash|shell|command|powershell|terminal|exec|run_)/i.test(tool))
+        return "";
+    const raw = input["command"] ?? input["script"] ?? input["cmd"];
+    if (typeof raw !== "string")
+        return "";
+    const text = raw.split(String.fromCharCode(13)).join("").trim();
+    if (!text)
+        return "";
+    return text.length > SHELL_COMMAND_MAX ? `${text.slice(0, SHELL_COMMAND_MAX - 1)}…` : text;
+}
+function firstArg(input) {
+    const path = input["path"];
+    if (typeof path === "string" && path)
+        return path;
+    const command = input["command"];
+    if (typeof command === "string")
+        return command;
+    const query = input["query"] ?? input["pattern"];
+    if (typeof query === "string")
+        return query;
+    const keys = Object.keys(input);
+    if (!keys.length)
+        return "";
+    const value = input[keys[0]];
+    return typeof value === "string" ? value : "";
+}
+function clamp(value, max) {
+    const text = value.replace(/\s+/g, " ").trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/dist/vascend/kingdom-scribe.d.ts

@@ -0,0 +1,20 @@
+import type { Message } from "../core/types.js";
+import { type RoomRecord } from "./room-memory.js";
+export interface ScribeSubmission {
+    readonly messages: readonly Message[];
+    readonly namespace?: string;
+    readonly createdAt: number;
+}
+declare class KingdomScribe {
+    private readonly sessionDir;
+    private readonly storeId;
+    private readonly fanout;
+    private readonly chains;
+    constructor(sessionDir: string, storeId: string, fanout: number);
+    private chainKey;
+    submitRoom(sub: ScribeSubmission): Promise<RoomRecord>;
+    private writeOne;
+}
+export declare function getKingdomScribe(sessionDir: string, storeId: string, fanout: number): KingdomScribe;
+export declare function _resetScribes(): void;
+export type { KingdomScribe };

package/dist/vascend/kingdom-scribe.js

@@ -0,0 +1,52 @@
+import { RoomMemory, formatRoomRecord } from "./room-memory.js";
+class KingdomScribe {
+    sessionDir;
+    storeId;
+    fanout;
+    // Coda di scrittura per store: la promise-chain garantisce un solo writer
+    // logico per volta sullo stesso file (serializzazione in-process).
+    chains = new Map();
+    constructor(sessionDir, storeId, fanout) {
+        this.sessionDir = sessionDir;
+        this.storeId = storeId;
+        this.fanout = fanout;
+    }
+    chainKey() {
+        return `${this.sessionDir}::${this.storeId}`;
+    }
+    // Accoda una scrittura serializzata. Ogni submit aspetta il precedente sullo
+    // stesso store, poi esegue la sua append sotto lock file-system.
+    submitRoom(sub) {
+        const key = this.chainKey();
+        const prev = this.chains.get(key) ?? Promise.resolve();
+        const next = prev.then(() => this.writeOne(sub), () => this.writeOne(sub));
+        // Tieni la catena viva ma non trattenere i risultati/errori.
+        this.chains.set(key, next.then(() => undefined, () => undefined));
+        return next;
+    }
+    writeOne(sub) {
+        // Apri una vista dello store; appendRoomNamespaced ricarica dal disco sotto
+        // lock prima di calcolare l'id, quindi va bene anche se questa istanza e'
+        // appena stata creata.
+        const mem = RoomMemory.open(this.sessionDir, this.storeId, this.fanout);
+        return mem.appendRoomNamespaced((id) => formatRoomRecord(id, sub.messages, sub.createdAt), sub.namespace);
+    }
+}
+// Singleton per store: tutte le scritture sullo stesso `${sessionDir}/${storeId}`
+// passano dallo stesso Scribe (stessa coda). Indispensabile: due Scribe diversi
+// sullo stesso file non si serializzerebbero in-process (resterebbe solo il
+// lock cross-processo, piu' costoso e con piu' contesa).
+const scribes = new Map();
+export function getKingdomScribe(sessionDir, storeId, fanout) {
+    const key = `${sessionDir}::${storeId}`;
+    let s = scribes.get(key);
+    if (!s) {
+        s = new KingdomScribe(sessionDir, storeId, fanout);
+        scribes.set(key, s);
+    }
+    return s;
+}
+// Solo per i test: azzera i singleton (catene di scrittura) tra un caso e l'altro.
+export function _resetScribes() {
+    scribes.clear();
+}

package/dist/vascend/kingdom.d.ts

@@ -0,0 +1,79 @@
+import type { Harness } from "../core/bootstrap.js";
+import { type FileCoordinationContext } from "../core/file-coordination.js";
+import type { AgentEvent, SpawnAgentSpec, ToolContext } from "../core/types.js";
+export { disjointAreas } from "./team-areas.js";
+import { type MergeResult } from "./worktree.js";
+export interface CastleSpec extends SpawnAgentSpec {
+}
+export interface VassalReport {
+    readonly artifacts?: readonly import("./team-handoff.js").ArtifactReference[];
+    readonly slug: string;
+    readonly ok: boolean;
+    readonly summary: string;
+    readonly rooms: number;
+    readonly model?: string;
+    readonly role?: string;
+    readonly parent?: string;
+    readonly workstreamId?: string;
+    readonly taskRefs?: readonly string[];
+    readonly parentTaskRef?: string;
+    readonly error?: string;
+    readonly branch?: string;
+    readonly worktree?: string;
+    readonly merge?: MergeResult;
+    readonly recovery?: WorktreeRecovery;
+}
+export type WorktreeRecoveryReason = "setup-failed" | "vassal-failed" | "commit-failed" | "merge-failed" | "cleanup-failed";
+export interface WorktreeRecovery {
+    readonly reason: WorktreeRecoveryReason;
+    readonly worktree?: string;
+    readonly commitRequired: boolean;
+    readonly mergeRequired: boolean;
+    readonly note: string;
+}
+export interface ConflictEntry {
+    readonly slug: string;
+    readonly branch: string;
+    readonly conflict: boolean;
+    readonly note: string;
+    readonly worktree?: string;
+    readonly reason?: WorktreeRecoveryReason;
+    readonly commitRequired?: boolean;
+    readonly mergeRequired?: boolean;
+    readonly integrated?: boolean;
+}
+export declare function collectConflicts(reports: readonly VassalReport[]): ConflictEntry[];
+export declare function formatConflictList(conflicts: readonly ConflictEntry[], base?: string): string;
+export interface KingdomWarmOptions {
+    readonly harness: Harness;
+    readonly kingdomId: string;
+    readonly castles: readonly CastleSpec[];
+    readonly signal: AbortSignal;
+    readonly confirm: (action: string, detail: string) => Promise<boolean>;
+    readonly ask?: ToolContext["ask"];
+    readonly fileCoordination?: FileCoordinationContext;
+    readonly concurrency?: number;
+    readonly onEvent?: (slug: string, event: AgentEvent) => void;
+    readonly worktree?: boolean;
+    readonly baseBranch?: string;
+    readonly onNotice?: (text: string) => void;
+    readonly onMemberState?: (slug: string, state: "running" | "completed" | "failed", report?: VassalReport) => void;
+}
+export declare function warmConcurrency(env: NodeJS.ProcessEnv, fallback?: number): number;
+export declare function looksBigGoal(text: string): boolean;
+export declare function decomposeKingdom(opts: {
+    readonly harness: Harness;
+    readonly goal: string;
+    readonly signal: AbortSignal;
+    readonly max?: number;
+}): Promise<CastleSpec[]>;
+export interface FinalizeVassalWorktreeOptions {
+    readonly root: string;
+    readonly base: string;
+    readonly branch: string;
+    readonly dir: string;
+    readonly report: VassalReport;
+    readonly signal?: AbortSignal;
+}
+export declare function finalizeVassalWorktree(opts: FinalizeVassalWorktreeOptions): Promise<VassalReport>;
+export declare function runKingdomWarm(opts: KingdomWarmOptions): Promise<VassalReport[]>;