@vascend/talos 0.1.0

package/dist/vascend/kingdom-channel.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { withLockSync } from "./file-lock.js";
+import { consumeInbox } from "./kingdom-bus.js";
+// Canale di comunicazione PERSISTENTE tra kingdoms (Kingdoms Mode): mentre il
+// KingdomBus in-memory funziona SOLO tra vassalli dello stesso processo (warm,
+// async), questo canale e' file-based e quindi CROSS-PROCESS. Serve quando i
+// kingdoms vengono lanciati granularmente (processi/sessioni separate che NON
+// condividono la memoria del processo): possono comunque scambiarsi messaggi e
+// coordinarsi durante l'esecuzione leggendo/scrivendo lo stesso file di board.
+//
+// Layout su disco (sotto sessionDir, accanto agli altri store del regno):
+//   ${kingdomId}.kingdom.bus.jsonl      -> board append-only, una riga per msg
+//   ${kingdomId}.kingdom.cursors.json   -> { slug -> ultimo seq letto }
+//
+// Mutua esclusione cross-process via file-lock (mkdir atomico). Le scritture
+// sono brevissime (append di una riga / rewrite di un piccolo json), quindi il
+// busy-wait sincrono del lock e' adeguato. Niente dipendenze a runtime.
+const MAX_BOARD = 500;
+function busFile(sessionDir, kingdomId) {
+    return join(sessionDir, `${kingdomId}.kingdom.bus.jsonl`);
+}
+function cursorsFile(sessionDir, kingdomId) {
+    return join(sessionDir, `${kingdomId}.kingdom.cursors.json`);
+}
+function readBoard(file) {
+    if (!existsSync(file))
+        return [];
+    const out = [];
+    let raw = "";
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (typeof o.seq === "number" && typeof o.from === "string" && typeof o.text === "string") {
+                out.push({
+                    seq: o.seq,
+                    from: o.from,
+                    to: typeof o.to === "string" && o.to ? o.to : null,
+                    text: o.text,
+                    ts: typeof o.ts === "number" ? o.ts : 0,
+                });
+            }
+        }
+        catch {
+            // riga corrotta: ignorata, il log resta recuperabile.
+        }
+    }
+    return out;
+}
+function readCursors(file) {
+    if (!existsSync(file))
+        return Object.create(null);
+    try {
+        const o = JSON.parse(readFileSync(file, "utf8"));
+        const out = Object.create(null);
+        for (const [k, v] of Object.entries(o)) {
+            if (typeof v === "number")
+                out[k] = { last: v }; // legacy cursor
+            else if (v && typeof v === "object" && typeof v.last === "number") {
+                const cursor = v;
+                out[k] = { last: cursor.last, seen: Array.isArray(cursor.seen) ? cursor.seen.filter(Number.isSafeInteger) : [] };
+            }
+        }
+        return out;
+    }
+    catch {
+        return Object.create(null);
+    }
+}
+// Canale persistente file-based con la STESSA interfaccia di KingdomBus, cosi'
+// i tool kingdom_send/inbox/wait restano invariati a prescindere dalla modalita'
+// (warm in-process vs granular cross-process).
+export class PersistentKingdomChannel {
+    sessionDir;
+    maxBoard;
+    constructor(sessionDir, opts = {}) {
+        this.sessionDir = sessionDir;
+        this.maxBoard = opts.maxBoard ?? MAX_BOARD;
+    }
+    // Pubblica un messaggio sulla board del regno. Il seq globale e' derivato dal
+    // contenuto attuale del file SOTTO LOCK, cosi' due processi non collidono.
+    post(kingdomId, from, to, text, ts) {
+        const file = busFile(this.sessionDir, kingdomId);
+        mkdirSync(dirname(file), { recursive: true });
+        return withLockSync(file, () => {
+            const board = readBoard(file);
+            const seq = board.reduce((mx, m) => (m.seq > mx ? m.seq : mx), 0) + 1;
+            const m = {
+                seq,
+                from,
+                to: to && to.trim() ? to.trim() : null,
+                text,
+                ts,
+            };
+            // Potatura: se la board supera il cap, riscrive il file con la coda.
+            if (board.length + 1 > this.maxBoard) {
+                const kept = [...board, m].slice(-this.maxBoard);
+                writeFileSync(file, kept.map((x) => JSON.stringify(x)).join("\n") + "\n", "utf8");
+            }
+            else {
+                appendFileSync(file, JSON.stringify(m) + "\n", "utf8");
+            }
+            return m;
+        });
+    }
+    // Messaggi NON ancora letti da `me` (destinati a me o broadcast, non miei).
+    // Avanza il cursore di lettura di `me` (read-modify-write atomico sul file
+    // dei cursori, sotto lock dedicato).
+    inbox(kingdomId, me, filter) {
+        const cfile = cursorsFile(this.sessionDir, kingdomId);
+        mkdirSync(dirname(cfile), { recursive: true });
+        return withLockSync(cfile, () => {
+            const board = readBoard(busFile(this.sessionDir, kingdomId));
+            const cursors = readCursors(cfile);
+            const read = consumeInbox(board, me, cursors[me] ?? { last: 0 }, filter);
+            cursors[me] = read.cursor;
+            writeFileSync(cfile, JSON.stringify(cursors), "utf8");
+            return read.messages;
+        });
+    }
+    // Tutti i messaggi del regno (per riepilogo/log), senza toccare i cursori.
+    history(kingdomId) {
+        return readBoard(busFile(this.sessionDir, kingdomId));
+    }
+    // Rimuove board e cursori del regno (cleanup a fine corsa).
+    clear(kingdomId) {
+        for (const f of [busFile(this.sessionDir, kingdomId), cursorsFile(this.sessionDir, kingdomId)]) {
+            try {
+                rmSync(f, { force: true });
+            }
+            catch {
+                // gia' assente
+            }
+        }
+    }
+}
+// Una istanza per sessionDir (riusata tra i tool dello stesso processo). Il
+// vero coordinamento cross-process avviene comunque sul file, quindi piu'
+// istanze in processi diversi convivono correttamente.
+const channels = new Map();
+export function getKingdomChannel(sessionDir, opts) {
+    let c = channels.get(sessionDir);
+    if (!c) {
+        c = new PersistentKingdomChannel(sessionDir, opts);
+        channels.set(sessionDir, c);
+    }
+    return c;
+}
+// --- Facade di selezione del backend ------------------------------------
+// I tool kingdom_send/inbox/wait non devono sapere QUALE backend e' attivo:
+// chiamano `resolveKingdomBus(env, sessionDir)` e ottengono un oggetto con la
+// stessa interfaccia (post/inbox/history/clear). Quando l'IPC e' abilitato e
+// c'e' un sessionDir, ritorna il canale persistente file-based (cross-process,
+// per i kingdoms lanciati granularmente); altrimenti il bus in-memory (warm,
+// vassalli nello stesso processo). Nessuna modifica alla firma dei tool.
+import { kingdomBus } from "./kingdom-bus.js";
+// IPC cross-process attivo? Default: ON quando c'e' un sessionDir (cosi' i
+// kingdoms granulari comunicano sempre). Disattivabile con TALOS_KINGDOM_IPC=0
+// per forzare il solo bus in-memory (es. test o single-process puro).
+export function kingdomIpcEnabled(env) {
+    const v = (env["TALOS_KINGDOM_IPC"] ?? "").trim().toLowerCase();
+    if (v === "0" || v === "off" || v === "false" || v === "no")
+        return false;
+    return true;
+}
+// Risolve il backend giusto. `sessionDir` assente => sempre in-memory (non c'e'
+// dove persistere). Garantisce il typing comune KingdomBusLike.
+export function resolveKingdomBus(env, sessionDir) {
+    if (sessionDir && kingdomIpcEnabled(env))
+        return getKingdomChannel(sessionDir);
+    return kingdomBus;
+}

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

@@ -0,0 +1,48 @@
+import type { Harness } from "../core/bootstrap.js";
+import type { VassalReport } from "./kingdom.js";
+import { type SelfImproveReport, type VisionLike } from "./self-improve.js";
+export interface KingdomKpi {
+    readonly castles: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly rooms: number;
+    readonly merged: number;
+    readonly mergeConflicts: number;
+    readonly emptyVassals: number;
+    readonly executionScore: number;
+}
+export declare function computeKingdomKpi(reports: readonly VassalReport[]): KingdomKpi;
+export declare function buildKingdomEvidence(opts: {
+    readonly reports: readonly VassalReport[];
+    readonly kpi: KingdomKpi;
+    readonly roomIndex?: string;
+}): string;
+export declare function kingdomVisionFromGoal(goal: string): VisionLike;
+export interface KingdomGateVerdict {
+    readonly kpi: KingdomKpi;
+    readonly alignment: SelfImproveReport;
+    readonly executionThreshold: number;
+    readonly delivered: boolean;
+    readonly reason: string;
+}
+export declare function kingdomKpiThreshold(env: NodeJS.ProcessEnv): number;
+export declare function kingdomKpiRounds(env: NodeJS.ProcessEnv): number;
+export declare function decideKingdomGate(opts: {
+    readonly kpi: KingdomKpi;
+    readonly alignment: SelfImproveReport;
+    readonly executionThreshold: number;
+}): KingdomGateVerdict;
+export interface KingdomGateInput {
+    readonly harness: Harness;
+    readonly reports: readonly VassalReport[];
+    readonly goal: string;
+    readonly vision?: VisionLike | string;
+    readonly roomIndex?: string;
+    readonly signal: AbortSignal;
+    readonly executionThreshold?: number;
+    readonly threshold?: number;
+    readonly maxProposals?: number;
+}
+export declare function runKingdomGate(input: KingdomGateInput): Promise<KingdomGateVerdict>;
+export declare function buildKingdomImproveSteer(goal: string, verdict: KingdomGateVerdict): string;
+export declare function formatKingdomGate(verdict: KingdomGateVerdict): string;

package/dist/vascend/kingdom-kpi.js

@@ -0,0 +1,172 @@
+import { runSelfImprove, } from "./self-improve.js";
+// Estrae i KPI di processo dai report dei vassalli. Puro: nessun side-effect.
+export function computeKingdomKpi(reports) {
+    const castles = reports.length;
+    const succeeded = reports.filter((r) => r.ok).length;
+    const failed = castles - succeeded;
+    const rooms = reports.reduce((acc, r) => acc + (r.rooms || 0), 0);
+    const merged = reports.filter((r) => r.merge?.ok).length;
+    const mergeConflicts = reports.filter((r) => r.merge && !r.merge.ok).length;
+    // Vassallo "vuoto": dichiarato ok ma senza alcuna evidenza (ne' stanze ne'
+    // testo di summary). Sospetto: forse non ha fatto nulla di reale.
+    const emptyVassals = reports.filter((r) => r.ok && (r.rooms || 0) === 0 && !r.summary.trim()).length;
+    const executionScore = scoreExecution({
+        castles,
+        succeeded,
+        mergeConflicts,
+        emptyVassals,
+    });
+    return { castles, succeeded, failed, rooms, merged, mergeConflicts, emptyVassals, executionScore };
+}
+// Punteggio di esecuzione 0..100. Base = quota di vassalli riusciti, con
+// penalita' per conflitti di merge (lavoro non integrato) e vassalli vuoti
+// (successo sospetto). Deterministico e monotono.
+function scoreExecution(p) {
+    if (p.castles === 0)
+        return 100; // niente da fare = nessun fallimento
+    const successRatio = p.succeeded / p.castles;
+    let score = successRatio * 100;
+    // Ogni conflitto di merge: lavoro non integrato, pesa come mezzo fallimento.
+    score -= (p.mergeConflicts / p.castles) * 50;
+    // Ogni vassallo vuoto: successo dubbio, penalita' lieve.
+    score -= (p.emptyVassals / p.castles) * 15;
+    return clampScore(score);
+}
+function clampScore(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(100, Math.round(n)));
+}
+// ---------------------------------------------------------------------------
+// Evidence di regno: sintesi testuale dell'operato dei vassalli, da passare a
+// runSelfImprove come STATO CORRENTE per il giudizio di allineamento alla Vision.
+// ---------------------------------------------------------------------------
+// Costruisce l'evidence aggregata dei vassalli (KPI + per-castello). `roomIndex`
+// opzionale = INDICE delle stanze del regno (RoomMemory.indexBlock) per dare al
+// giudice il dettaglio recuperabile. Limitata in lunghezza (anti-overflow).
+export function buildKingdomEvidence(opts) {
+    const { reports, kpi, roomIndex } = opts;
+    const head = `VERIFICA ATTIVITA: ${kpi.succeeded}/${kpi.castles} collaboratori ok, ` +
+        `${kpi.rooms} attivita, merge ${kpi.merged} ok / ${kpi.mergeConflicts} conflitti, ` +
+        `collaboratori vuoti ${kpi.emptyVassals}, executionScore ${kpi.executionScore}/100`;
+    const perCastle = reports
+        .map((r) => {
+        const status = r.ok ? "ok" : "FALLITO";
+        const mg = r.merge ? (r.merge.ok ? ", merge ok" : `, merge ${r.merge.conflict ? "CONFLITTO" : "errore"}`) : "";
+        const err = r.error ? `, errore: ${r.error}` : "";
+        const body = r.summary.trim() ? r.summary.trim().slice(0, 600) : "(nessun output)";
+        return `[${r.slug}] ${status} (${r.rooms} attivita${mg}${err}): ${body}`;
+    })
+        .join("\n");
+    const idx = roomIndex && roomIndex.trim()
+        ? `\n\nATTIVITA ARCHIVIATE (dettaglio recuperabile):\n${roomIndex.trim().slice(0, 2000)}`
+        : "";
+    return `${head}\n\nESITO PER GRUPPO:\n${perCastle}${idx}`;
+}
+// ---------------------------------------------------------------------------
+// Vision del regno: se non e' fornita una Vision esplicita, si costruisce una
+// Vision minima dal GOAL complessivo del regno (l'obiettivo finale dell'utente),
+// cosi' il giudizio di allineamento ha un riferimento.
+// ---------------------------------------------------------------------------
+export function kingdomVisionFromGoal(goal) {
+    return { finalGoal: goal.trim(), title: "Piano" };
+}
+// Soglia di executionScore (0..100) per considerare lo swarm "ben eseguito".
+// Default 80: la maggioranza schiacciante dei vassalli deve essere riuscita e
+// integrata. Override con TALOS_KINGDOM_KPI_THRESHOLD.
+export function kingdomKpiThreshold(env) {
+    const n = Number(env["TALOS_KINGDOM_KPI_THRESHOLD"]);
+    return Number.isFinite(n) && n >= 0 && n <= 100 ? Math.round(n) : 80;
+}
+// Quante iterazioni di wake-up del regno al massimo (anti-loop). Default 1:
+// dopo lo swarm si concede al piu' un giro di miglioramento. 0 = gate solo
+// diagnostico (misura ma non rilancia). Override con TALOS_KINGDOM_KPI_ROUNDS.
+export function kingdomKpiRounds(env) {
+    const n = Number(env["TALOS_KINGDOM_KPI_ROUNDS"]);
+    return Number.isInteger(n) && n >= 0 ? n : 1;
+}
+// Combina KPI di processo e report di allineamento in un verdetto.
+export function decideKingdomGate(opts) {
+    const { kpi, alignment, executionThreshold } = opts;
+    const execOk = kpi.executionScore >= executionThreshold;
+    const mustCount = alignment.proposals.filter((p) => p.priority === "must").length;
+    const delivered = execOk && alignment.atVision;
+    const reason = delivered
+        ? `piano consegnabile: esecuzione ${kpi.executionScore}/100 (soglia ${executionThreshold}), allineamento ${alignment.alignment}/100`
+        : `piano da rinforzare: esecuzione ${kpi.executionScore}/100 (soglia ${executionThreshold})` +
+            (execOk ? "" : `, ${kpi.failed} falliti/${kpi.mergeConflicts} conflitti`) +
+            (alignment.atVision ? "" : `, allineamento ${alignment.alignment}/100, ${mustCount} must residui`);
+    return { kpi, alignment, executionThreshold, delivered, reason };
+}
+export async function runKingdomGate(input) {
+    const kpi = computeKingdomKpi(input.reports);
+    const executionThreshold = input.executionThreshold ?? kingdomKpiThreshold(process.env);
+    const evidence = buildKingdomEvidence({
+        reports: input.reports,
+        kpi,
+        ...(input.roomIndex ? { roomIndex: input.roomIndex } : {}),
+    });
+    const vision = input.vision ?? kingdomVisionFromGoal(input.goal);
+    const alignment = await runSelfImprove({
+        harness: input.harness,
+        vision,
+        evidence,
+        goal: input.goal,
+        signal: input.signal,
+        ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
+        ...(input.maxProposals !== undefined ? { maxProposals: input.maxProposals } : {}),
+    });
+    return decideKingdomGate({ kpi, alignment, executionThreshold });
+}
+// ---------------------------------------------------------------------------
+// Steer di miglioramento del REGNO (notazione Danilov): se il verdetto NON e'
+// "delivered", rilancia l'agente principale (Imperatore) a colmare i gap —
+// prima i fallimenti di esecuzione (vassalli falliti/conflitti), poi le proposte
+// must verso la Vision. A differenza di buildSelfImproveSteer (un solo lavoro),
+// qui il contesto e' il regno appena eseguito.
+// ---------------------------------------------------------------------------
+export function buildKingdomImproveSteer(goal, verdict) {
+    const g = goal.replace(/"/g, "'").slice(0, 200);
+    const { kpi, alignment } = verdict;
+    const must = alignment.proposals.filter((p) => p.priority === "must");
+    const rows = (must.length ? must : alignment.proposals.slice(0, 5))
+        .map((p, i) => `(${i + 1}) [${p.priority}/${p.category}] ${p.text}${p.visionRef ? ` <${p.visionRef}>` : ""} (impatto ${p.impact})`)
+        .join(" ; ");
+    const execGap = kpi.failed > 0 || kpi.mergeConflicts > 0 || kpi.emptyVassals > 0
+        ? `collaboratori falliti=${kpi.failed}, conflitti merge=${kpi.mergeConflicts}, collaboratori vuoti=${kpi.emptyVassals}`
+        : "esecuzione completa";
+    return `[VASCEND_ATTIVITA_MIGLIORA]
+INDICE
+1 = goal
+2 = kpi
+3 = vision
+4 = azione
+
+DEFINIZIONI
+@goal[reale]: "${g}"
+@kpi[esecuzione]: ${kpi.executionScore}/100 (soglia ${verdict.executionThreshold}) · ${execGap}
+@vision[allineamento]: ${alignment.alignment}/100 verso l'obiettivo finale (must residui=${must.length})
+@proposta[gap]: ${rows || "nessuna proposta esplicita: rifinisci verso l'obiettivo finale"}
+@azione[colma]: NON consegni un piano parziale; PRIMA risolvi i gap di esecuzione (rilavora i gruppi falliti, integra i conflitti), POI realizza le proposte must verso la Vision
+
+RELAZIONI
+@R1: @kpi[esecuzione] -> @azione[colma]  [ i fallimenti di esecuzione vanno chiusi per primi ]
+@R2: @vision[allineamento] -> @proposta[gap]  [ il gap verso l'obiettivo diventa proposte ]
+@R3: @proposta[gap] -> @azione[colma]  [ realizza i must, poi rivaluta ]
+
+OUTPUT: colma i gap del piano col lavoro reale (esecuzione prima, poi proposte must verso la Vision) e completa le attivita con vascend_mark. Il gate KPI rivaluta.`;
+}
+// ---------------------------------------------------------------------------
+// Vista human-readable del verdetto (per la TUI).
+// ---------------------------------------------------------------------------
+export function formatKingdomGate(verdict) {
+    const { kpi, alignment } = verdict;
+    const head = verdict.delivered
+        ? `Piano consegnabile · esecuzione ${kpi.executionScore}/100 · allineamento ${alignment.alignment}/100`
+        : `Piano da rinforzare · ${verdict.reason}`;
+    const rows = alignment.proposals
+        .slice(0, 6)
+        .map((p) => `  - [${p.priority}/${p.category}] ${p.text}${p.rationale ? ` — ${p.rationale}` : ""}`)
+        .join("\n");
+    return rows ? `${head}\n${rows}` : head;
+}

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

@@ -0,0 +1,28 @@
+import type { UserInbox } from "../core/user-inbox.js";
+export interface LiveVassal {
+    readonly kingdomId: string;
+    readonly slug: string;
+    readonly inbox: UserInbox;
+    readonly since: number;
+}
+export interface DeliveryOutcome {
+    readonly ok: boolean;
+    readonly messageId?: string;
+    readonly error?: string;
+}
+export declare class KingdomLive {
+    private readonly vassals;
+    register(kingdomId: string, slug: string, inbox: UserInbox, now?: number): void;
+    release(kingdomId: string, slug: string): void;
+    has(kingdomId: string, slug: string): boolean;
+    /** Slug dei collaboratori che stanno lavorando adesso in questo regno. */
+    slugs(kingdomId: string): readonly string[];
+    /**
+     * Consegna un messaggio dell'utente a un collaboratore. Non attende che sia
+     * letto: ritorna l'id, cosi' l'host puo' dire "in attesa" e poi "letto"
+     * quando arriva l'evento `user_message` di quel vassallo.
+     */
+    deliver(kingdomId: string, slug: string, text: string, messageId?: string): DeliveryOutcome;
+    clear(kingdomId: string): void;
+}
+export declare const kingdomLive: KingdomLive;

package/dist/vascend/kingdom-live.js

@@ -0,0 +1,61 @@
+// Collaboratori VIVI di un regno: il punto in cui l'utente puo' parlare a un
+// singolo vassallo mentre lavora.
+//
+// Il KingdomBus e' il canale fra vassalli (pull: il destinatario legge quando
+// chiama kingdom_inbox). Non basta per una chat: un messaggio dell'utente non
+// puo' dipendere dal fatto che il collaboratore si ricordi di controllare la
+// posta. Qui teniamo invece la CASELLA del suo loop (la stessa UserInbox della
+// chat principale), che l'agente svuota da solo al primo confine sicuro, subito
+// dopo gli esiti dei tool.
+//
+// Registro in-memory di processo, chiave `${kingdomId}::${slug}`. Vive quanto il
+// turno del vassallo: chi lo registra lo rilascia in un finally, altrimenti la
+// UI crederebbe di poter scrivere a un agente che non c'e' piu'.
+const key = (kingdomId, slug) => `${kingdomId}::${slug}`;
+export class KingdomLive {
+    vassals = new Map();
+    register(kingdomId, slug, inbox, now = Date.now()) {
+        const id = String(kingdomId || "").trim();
+        const who = String(slug || "").trim();
+        if (!id || !who)
+            return;
+        this.vassals.set(key(id, who), { kingdomId: id, slug: who, inbox, since: now });
+    }
+    release(kingdomId, slug) {
+        this.vassals.delete(key(String(kingdomId || "").trim(), String(slug || "").trim()));
+    }
+    has(kingdomId, slug) {
+        return this.vassals.has(key(String(kingdomId || "").trim(), String(slug || "").trim()));
+    }
+    /** Slug dei collaboratori che stanno lavorando adesso in questo regno. */
+    slugs(kingdomId) {
+        const id = String(kingdomId || "").trim();
+        return [...this.vassals.values()].filter((v) => v.kingdomId === id).map((v) => v.slug);
+    }
+    /**
+     * Consegna un messaggio dell'utente a un collaboratore. Non attende che sia
+     * letto: ritorna l'id, cosi' l'host puo' dire "in attesa" e poi "letto"
+     * quando arriva l'evento `user_message` di quel vassallo.
+     */
+    deliver(kingdomId, slug, text, messageId) {
+        const body = String(text ?? "").trim();
+        if (!body)
+            return { ok: false, error: "messaggio vuoto" };
+        const live = this.vassals.get(key(String(kingdomId || "").trim(), String(slug || "").trim()));
+        if (!live)
+            return { ok: false, error: "collaboratore non piu' attivo" };
+        try {
+            return { ok: true, messageId: live.inbox.push(body, messageId) };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    }
+    clear(kingdomId) {
+        const id = String(kingdomId || "").trim();
+        for (const [k, v] of [...this.vassals])
+            if (v.kingdomId === id)
+                this.vassals.delete(k);
+    }
+}
+export const kingdomLive = new KingdomLive();

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

@@ -0,0 +1,18 @@
+import type { EventSink, ToolContext } from "../core/types.js";
+import type { Harness } from "../core/bootstrap.js";
+import { type CastleSpec, type VassalReport } from "./kingdom.js";
+import type { FileCoordinationContext } from "../core/file-coordination.js";
+export interface KingdomRunInput {
+    readonly harness: Harness;
+    readonly castles: readonly CastleSpec[];
+    readonly signal: AbortSignal;
+    readonly sink: EventSink;
+    readonly confirm: (action: string, detail: string) => Promise<boolean>;
+    readonly ask?: ToolContext["ask"];
+    readonly fileCoordination?: FileCoordinationContext;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly baseBranch?: string;
+    readonly detach?: boolean;
+}
+export declare function runKingdomForHost(input: KingdomRunInput): Promise<string>;
+export declare function formatKingdomOutcome(reports: readonly VassalReport[], sessionDir: string, kingdomId: string): string;