@vascend/talos 0.1.0

package/dist/vascend/kingdom.js

@@ -0,0 +1,870 @@
+import { artifactReference } from "./team-handoff.js";
+import { ToolOutputStore } from "../core/tool-result-store.js";
+import { existsSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { runTurn } from "../core/agent.js";
+import { Session } from "../core/session.js";
+import { createUserInbox } from "../core/user-inbox.js";
+import { kingdomLive } from "./kingdom-live.js";
+import { fileActor, withFileActor } from "../core/file-coordination.js";
+import { RoomMemory } from "./room-memory.js";
+import { VascendPlanStore } from "./plan-store.js";
+import { formatMandate, mandateFor, mandateGoal } from "./mandate.js";
+import { launchGranularKingdom } from "./granular-kingdom.js";
+import { scheduleTeam, validateTeamGraph } from "./team-scheduler.js";
+import { disjointAreas } from "./team-areas.js";
+export { disjointAreas } from "./team-areas.js";
+import { formatGranularReport, granularConcurrency } from "./granular-launcher.js";
+import { worktreeMode, repoRoot, resolveBaseBranch, vassalBranchName, worktreeDir, addWorktree, commitAll, mergeBack, removeWorktree, deleteBranch, runGit, } from "./worktree.js";
+// Estrae dai report la lista dei rami in conflitto/non-merge-ati che richiedono
+// risoluzione manuale (rami conservati). Vuota se tutto e' filato liscio o se
+// non si e' in modalita' worktree.
+export function collectConflicts(reports) {
+    const out = [];
+    for (const r of reports) {
+        if (r.recovery && r.branch) {
+            out.push({
+                slug: r.slug,
+                branch: r.branch,
+                conflict: r.merge?.conflict ?? false,
+                note: r.recovery.note,
+                ...(r.recovery.worktree ? { worktree: r.recovery.worktree } : {}),
+                reason: r.recovery.reason,
+                commitRequired: r.recovery.commitRequired,
+                mergeRequired: r.recovery.mergeRequired,
+                integrated: r.merge?.integrated === true,
+            });
+        }
+        else if (r.merge && !r.merge.ok && r.branch) {
+            out.push({
+                slug: r.slug,
+                branch: r.branch,
+                conflict: r.merge.conflict,
+                note: r.merge.note,
+                integrated: r.merge.integrated === true,
+            });
+        }
+    }
+    return out;
+}
+// Lista azionabile (notazione Danilov + comandi git) dei rami da risolvere a
+// mano. Ritorna "" se non c'e' nulla in sospeso. `base` = ramo di integrazione
+// su cui rifare il merge dopo la risoluzione.
+export function formatConflictList(conflicts, base) {
+    if (!conflicts.length)
+        return "";
+    const into = base ? ` in ${base}` : "";
+    const rows = conflicts
+        .map((c) => {
+        const state = conflictState(c);
+        const wt = c.worktree ? ` · worktree=${c.worktree}` : "";
+        return `@ramo[${c.slug}]: ${c.branch} · ${state}${wt}${c.note ? ` · ${c.note}` : ""}`;
+    })
+        .join("\n");
+    const inspect = conflicts
+        .map((c) => c.worktree
+        ? `  git -C ${quoteCommandArg(c.worktree)} status   # ispeziona il lavoro conservato di ${c.slug}`
+        : `  git log --oneline ${base ? `${base}..` : ""}${c.branch}   # ispeziona il ramo conservato di ${c.slug}`)
+        .join("\n");
+    const commits = conflicts
+        .filter((c) => c.commitRequired && c.worktree)
+        .map((c) => `  git -C ${quoteCommandArg(c.worktree)} add -A && git -C ${quoteCommandArg(c.worktree)} commit   # salva prima del merge`)
+        .join("\n");
+    const merges = conflicts
+        .filter((c) => c.mergeRequired !== false && !c.integrated)
+        .map((c) => `  ${base ? `git switch ${base} && ` : ""}git merge --no-ff ${c.branch}   # verifica/risolvi, poi commit se richiesto`)
+        .join("\n");
+    const cleanup = conflicts
+        .filter((c) => c.integrated)
+        .map((c) => `${c.worktree ? `  git worktree remove ${quoteCommandArg(c.worktree)}\n` : ""}  git branch -d ${c.branch}`)
+        .join("\n");
+    const actions = [inspect, commits, merges, cleanup].filter(Boolean).join("\n");
+    return `[STASH_DA_RISOLVERE]
+@stato[sospeso]: ${conflicts.length} ramo/i di collaboratore da recuperare${into} (nessun lavoro e' stato eliminato)
+${rows}
+@azione[risoluzione]: ispeziona, committa se indicato, poi integra SOLO dal ramo base:
+${actions}
+@azione[pulizia]: solo dopo aver verificato il merge: git worktree remove <path> ; git branch -d <ramo>`;
+}
+function quoteCommandArg(value) {
+    return `"${value.replace(/\\/g, "/").replace(/"/g, '\\"')}"`;
+}
+function conflictState(entry) {
+    if (entry.integrated)
+        return "merge completato, pulizia sospesa";
+    if (entry.conflict)
+        return "CONFLITTO di merge";
+    if (entry.reason === "vassal-failed")
+        return "collaboratore fallito, lavoro conservato";
+    if (entry.reason === "setup-failed")
+        return "setup worktree fallito";
+    if (entry.reason === "commit-failed")
+        return "commit fallito, lavoro conservato";
+    return "merge fallito";
+}
+export function warmConcurrency(env, fallback = 8) {
+    const n = Number(env["TALOS_KINGDOM_CONCURRENCY"]);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+// Euristica "obiettivo grande": evita di scomporre i prompt piccoli (la
+// scomposizione costa una chiamata al modello). Conservativa.
+export function looksBigGoal(text) {
+    const t = text.trim();
+    if (t.length >= 240)
+        return true;
+    if (t.split("\n").filter((l) => l.trim()).length >= 4)
+        return true;
+    const signals = (t.match(/\b(e poi|inoltre|vari|varie|multipl|in parallelo|workstream|diverse|diversi|piu'|più|oltre a)\b/gi) ?? []).length;
+    return signals >= 2;
+}
+const DECOMPOSE_SYSTEM = `# Coordinatore del team
+
+INDICE
+1 = coordinatore
+2 = obiettivo
+3 = incarico
+4 = indipendenza
+5 = confine
+
+DEFINIZIONI
+@coordinatore[ruolo]: scompone un obiettivo grande in incarichi
+@obiettivo[input]: macro-goal da spezzare
+@incarico[unita]: sotto-obiettivo autonomo, che un collaboratore puo' portare a termine da solo
+@indipendenza[regola]: gli incarichi non dipendono dall'output l'uno dell'altro nello stesso giro
+@confine[criterio]: taglia per area/modulo/file, NON per fase sequenziale
+
+RELAZIONI
+@R1: @obiettivo[input] -> @incarico[unita]  [ scomponi in parti ]
+@R2: @incarico[unita] -> @indipendenza[regola]  [ partono tutti insieme ]
+@R3: @incarico[unita] -> @confine[criterio]  [ confini netti ]
+
+OUTPUT: SOLO un array JSON di {slug, goal, after}; slug kebab-case breve; goal autonomo e completo;
+"after" = array degli slug degli incarichi PREREQUISITO (dipendenze forti: cio' che deve esistere prima),
+[] se indipendente — e indipendente e' quasi sempre la risposta giusta: un "after" di troppo mette in
+fila lavoro che poteva andare in parallelo. Niente prosa, niente markdown.`;
+// L'Imperatore scompone un obiettivo in castelli (slug + goal) con UNA chiamata
+// al modello. Ritorna [] se non risolvibile; fallback a un solo castello se il
+// parsing fallisce.
+export async function decomposeKingdom(opts) {
+    const { harness, goal, signal } = opts;
+    const max = Math.max(2, opts.max ?? 6);
+    const resolved = harness.providers.resolve(harness.config.model);
+    if (!resolved)
+        return [];
+    const user = `Obiettivo:\n${goal}\n\nScomponilo in al massimo ${max} incarichi INDIPENDENTI.\n` +
+        `Rispondi SOLO con un array JSON di oggetti {"slug","goal"}: slug breve in kebab-case (max 24 char), ` +
+        `goal autonomo e completo (una frase eseguibile). Niente prosa, niente markdown, solo l'array JSON.`;
+    const res = await resolved.provider.complete({
+        system: DECOMPOSE_SYSTEM,
+        messages: [{ role: "user", content: [{ type: "text", text: user }] }],
+        tools: [],
+        model: resolved.modelId,
+        maxTokens: harness.config.maxTokens,
+        signal,
+        sessionId: `decompose-${harness.session.id}`,
+    });
+    const parsed = parseCastlesJson(res.text);
+    if (parsed.length)
+        return parsed.slice(0, max);
+    return [{ slug: "c1", goal }];
+}
+function parseCastlesJson(text) {
+    const m = /\[[\s\S]*\]/.exec(text);
+    if (!m)
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(m[0]);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    raw.forEach((item, i) => {
+        if (!item || typeof item !== "object")
+            return;
+        const o = item;
+        const goal = typeof o["goal"] === "string" ? o["goal"].trim() : "";
+        if (!goal)
+            return;
+        let slug = (typeof o["slug"] === "string" ? o["slug"] : `c${i + 1}`)
+            .toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 24) || `c${i + 1}`;
+        while (seen.has(slug))
+            slug = `${slug}-${i + 1}`;
+        seen.add(slug);
+        const after = Array.isArray(o["after"])
+            ? o["after"].map(String).map((s) => s.trim()).filter(Boolean)
+            : [];
+        const list = (value) => Array.isArray(value)
+            ? value.map(String).map((entry) => entry.trim()).filter(Boolean).slice(0, 64)
+            : [];
+        const toolsRaw = o["tools"] && typeof o["tools"] === "object" && !Array.isArray(o["tools"])
+            ? o["tools"]
+            : null;
+        const allow = list(toolsRaw?.["allow"]);
+        const deny = list(toolsRaw?.["deny"]);
+        const effort = ["low", "medium", "high", "max"].includes(String(o["effort"] ?? "").toLowerCase())
+            ? String(o["effort"]).toLowerCase()
+            : "";
+        out.push({
+            slug,
+            goal,
+            ...(after.length ? { after } : {}),
+            ...(typeof o["parent"] === "string" && o["parent"].trim() ? { parent: o["parent"].trim().slice(0, 80) } : {}),
+            ...(typeof o["role"] === "string" && o["role"].trim() ? { role: o["role"].trim().slice(0, 80) } : {}),
+            ...(typeof o["model"] === "string" && o["model"].trim() ? { model: o["model"].trim().slice(0, 180) } : {}),
+            ...(effort ? { effort } : {}),
+            ...(typeof o["instructions"] === "string" && o["instructions"].trim()
+                ? { instructions: o["instructions"].trim().slice(0, 12_000) }
+                : {}),
+            ...(allow.length || deny.length
+                ? { tools: { ...(allow.length ? { allow } : {}), ...(deny.length ? { deny } : {}) } }
+                : {}),
+        });
+    });
+    // Pulisce le dipendenze: tieni solo gli slug esistenti e niente auto-dipendenza.
+    const slugs = new Set(out.map((c) => c.slug));
+    return out.map((c) => {
+        const dep = (c.after ?? []).filter((a) => a !== c.slug && slugs.has(a));
+        if (dep.length)
+            return { ...c, after: dep };
+        const { after: _after, ...rest } = c;
+        return rest;
+    });
+}
+// Unico punto che puo' integrare e pulire un worktree. La sequenza e'
+// deliberatamente monotona: commit verificato -> merge verificato -> remove
+// non forzato -> branch delete non forzato. A ogni errore si ferma e pubblica
+// un recovery report; non esiste alcun percorso che faccia cleanup anticipato.
+export async function finalizeVassalWorktree(opts) {
+    const { root, base, branch, dir, report, signal } = opts;
+    const committed = await commitAll(dir, `team(${report.slug}): lavoro del collaboratore`, signal);
+    if (!committed.ok) {
+        const note = `${committed.note}; merge non eseguito; ramo ${branch} e worktree ${dir} conservati`;
+        return recoveryReport(report, branch, dir, "commit-failed", note, true, true, {
+            ok: false,
+            conflict: false,
+            integrated: false,
+            note,
+        });
+    }
+    // Un vassallo fallito puo' aver prodotto lavoro parziale utile. Lo mettiamo
+    // al sicuro nel suo ramo, ma non lo integriamo automaticamente nel base.
+    if (!report.ok) {
+        const saved = committed.committed ? "lavoro parziale committato" : "ramo gia' pulito";
+        const note = `collaboratore fallito; ${saved}; verifica manuale richiesta prima del merge; ramo ${branch} e worktree ${dir} conservati`;
+        return recoveryReport(report, branch, dir, "vassal-failed", note, false, true, {
+            ok: false,
+            conflict: false,
+            integrated: false,
+            note,
+        });
+    }
+    const merged = await mergeBack(root, base, branch, `merge team(${report.slug}) in ${base}`, signal);
+    if (!merged.ok) {
+        const note = `${merged.note}; ramo ${branch} e worktree ${dir} conservati`;
+        return recoveryReport(report, branch, dir, "merge-failed", note, false, true, { ...merged, note });
+    }
+    const removed = await removeWorktree(root, dir, signal);
+    if (removed.code !== 0) {
+        const detail = gitResultDetail(removed);
+        const note = `merge verificato in ${base}, ma rimozione worktree fallita: ${detail}; ramo ${branch} e worktree ${dir} conservati`;
+        return recoveryReport(report, branch, dir, "cleanup-failed", note, false, false, { ...merged, note });
+    }
+    const deleted = await deleteBranch(root, branch, signal);
+    if (deleted.code !== 0) {
+        const detail = gitResultDetail(deleted);
+        const note = `merge verificato e worktree rimosso, ma eliminazione ramo fallita: ${detail}; ramo ${branch} conservato`;
+        return recoveryReport(report, branch, undefined, "cleanup-failed", note, false, false, { ...merged, note });
+    }
+    return { ...report, branch, merge: merged };
+}
+function recoveryReport(report, branch, worktree, reason, note, commitRequired, mergeRequired, merge) {
+    const error = report.error ? `${report.error}; ${note}` : note;
+    const recovery = {
+        reason,
+        ...(worktree ? { worktree } : {}),
+        commitRequired,
+        mergeRequired,
+        note,
+    };
+    return {
+        ...report,
+        ok: false,
+        error,
+        branch,
+        ...(worktree ? { worktree } : {}),
+        merge,
+        recovery,
+    };
+}
+function gitResultDetail(result) {
+    return (result.stderr || result.stdout || `uscita ${result.code}`).trim().slice(0, 360);
+}
+export async function runKingdomWarm(opts) {
+    const { harness, kingdomId, castles, signal, onNotice } = opts;
+    const env = process.env;
+    validateTeamGraph(castles);
+    // Setup ISOLAMENTO via worktree (se richiesto e siamo in un repo git). I
+    // worktree si creano in SEQUENZA (toccano lo stato condiviso del repo) prima
+    // di lanciare i vassalli in parallelo.
+    const wantWt = opts.worktree ?? worktreeMode(env);
+    const root = wantWt ? await repoRoot(harness.config.cwd) : null;
+    const base = root ? await resolveBaseBranch(root, env, opts.baseBranch) : null;
+    const useWt = Boolean(root && base);
+    const wt = new Map();
+    const setupFailures = new Map();
+    if (useWt) {
+        // I worktree sono l'unica cosa che il regno scrive PRIMA di qualsiasi
+        // lavoro: creano rami e cartelle nel repo dell'utente. Vanno chiesti come
+        // ogni altra azione che tocca il disco, e vanno chiesti UNA volta per tutto
+        // il regno, non una per castello.
+        const dirs = worktreeDir(kingdomId, castles[0]?.slug ?? "castello");
+        const approved = await opts.confirm("git worktree", `${castles.length} worktree isolati da "${base}" (un ramo ${vassalBranchName(kingdomId, "<gruppo>")} per gruppo), `
+            + `sotto ${dirs.slice(0, dirs.lastIndexOf(sep) + 1) || dirs}; merge seriali nel ramo base al completamento`);
+        if (!approved) {
+            // Rifiutato: non si ripiega sulla working dir condivisa, che sarebbe piu'
+            // invasiva (tutti i vassalli a scrivere nella stessa copia), non meno.
+            return castles.map((c) => ({
+                slug: c.slug,
+                ok: false,
+                summary: "",
+                rooms: 0,
+                error: "worktree isolati non autorizzati: piano non avviato. Per lavorare senza isolamento, nella stessa working dir, riavvia con TALOS_KINGDOM_WORKTREE=0",
+            }));
+        }
+        onNotice?.(`worktree isolati · ramo base "${base}" · merge a fine corsa`);
+        for (const c of castles) {
+            if (signal.aborted)
+                break;
+            const branch = vassalBranchName(kingdomId, c.slug);
+            const dir = worktreeDir(kingdomId, c.slug);
+            const r = await addWorktree(root, dir, branch, base, signal);
+            if (r.code === 0)
+                wt.set(c.slug, { dir, branch });
+            else {
+                const detail = gitResultDetail(r);
+                const note = `worktree non creato: ${detail}; nessun collaboratore avviato in working dir condivisa; eventuale ramo/worktree preesistente lasciato intatto`;
+                setupFailures.set(c.slug, { dir, branch, note });
+                onNotice?.(`[${c.slug}] ${note}`);
+            }
+        }
+    }
+    else if (wantWt) {
+        onNotice?.(root
+            ? "nessun ramo base (HEAD staccato?): niente worktree, modalita' condivisa + commit unico finale"
+            : "non e' un repo git: niente worktree, modalita' condivisa + commit unico finale");
+    }
+    const requestedLimit = Math.max(1, opts.concurrency ?? warmConcurrency(env));
+    /* Senza worktree i collaboratori scrivono nella STESSA cartella, e due
+       write sullo stesso file si sovrascrivono. La coda seriale era la difesa,
+       ma pagata da tutti: anche tre lavori che non si toccano nemmeno partivano
+       uno alla volta, e una squadra diventava una fila.
+       La difesa ora e' mirata: chi dichiara la propria AREA e non si sovrappone
+       a nessun altro parte subito; si resta in fila solo se le aree mancano o
+       si incrociano, cioe' quando il conflitto e' davvero possibile. */
+    const aree = disjointAreas(castles, harness.config.cwd);
+    const limit = requestedLimit;
+    if (!useWt && castles.length > 1 && !aree.disjoint) {
+        onNotice?.(`Coordinamento nella stessa cartella: ${aree.detail}. `
+            + "Gli incarichi con aree sovrapposte o mancanti vengono serializzati; dichiara l'area "
+            + "per eseguire contemporaneamente i lavori indipendenti.");
+    }
+    const peers = castles.map((c) => c.slug);
+    const handoffs = new Map();
+    const executeMember = async (castle, i) => {
+        const setupFailure = setupFailures.get(castle.slug);
+        if (setupFailure) {
+            const hasWorktree = existsSync(setupFailure.dir);
+            return {
+                slug: castle.slug,
+                ok: false,
+                summary: "",
+                rooms: 0,
+                error: setupFailure.note,
+                branch: setupFailure.branch,
+                ...(hasWorktree ? { worktree: setupFailure.dir } : {}),
+                merge: { ok: false, conflict: false, integrated: false, note: setupFailure.note },
+                recovery: {
+                    reason: "setup-failed",
+                    ...(hasWorktree ? { worktree: setupFailure.dir } : {}),
+                    commitRequired: false,
+                    mergeRequired: false,
+                    note: setupFailure.note,
+                },
+            };
+        }
+        const w = wt.get(castle.slug);
+        const workerPool = Array.isArray(harness.config.workerModelPool)
+            ? harness.config.workerModelPool : undefined;
+        const requested = castle.model?.trim() || "";
+        const selected = requested || (workerPool && workerPool.length
+            ? workerPool[i % workerPool.length]
+            : harness.config.model);
+        if (workerPool && (!workerPool.length || !workerPool.includes(selected))) {
+            return {
+                slug: castle.slug,
+                ok: false,
+                summary: "",
+                rooms: 0,
+                model: selected,
+                ...(castle.role ? { role: castle.role } : {}),
+                parent: castle.parent ?? "orchestratore",
+                error: workerPool.length
+                    ? `modello collaboratore non autorizzato: ${selected}`
+                    : "nessun modello collaboratore autorizzato dall'utente",
+            };
+        }
+        const resolved = harness.providers.resolve(selected);
+        if (!resolved) {
+            return {
+                slug: castle.slug,
+                ok: false,
+                summary: "",
+                rooms: 0,
+                model: selected,
+                ...(castle.role ? { role: castle.role } : {}),
+                parent: castle.parent ?? "orchestratore",
+                error: `modello non configurato: ${selected}`,
+            };
+        }
+        return runVassal(opts, resolved.provider, resolved.modelId, selected, castle, peers, {
+            cwd: w?.dir,
+            isolated: Boolean(w),
+            base: base ?? undefined,
+        }, (castle.after ?? []).map((slug) => handoffs.get(slug)).filter(Boolean));
+    };
+    // Integration mutates the shared repository. Serialize it, while allowing
+    // independent agents to continue working in their own worktrees.
+    let integration = Promise.resolve();
+    const integrate = (action) => {
+        const next = integration.then(action);
+        integration = next.catch(() => undefined);
+        return next;
+    };
+    const reports = await scheduleTeam({
+        members: castles, concurrency: limit, signal,
+        compatible: (left, right) => useWt || disjointAreas([left, right], harness.config.cwd).disjoint,
+        failure: (castle, error) => {
+            const w = wt.get(castle.slug);
+            return { slug: castle.slug, ok: false, summary: "", rooms: 0, error,
+                ...(w ? { branch: w.branch, worktree: w.dir, recovery: {
+                        reason: "vassal-failed", worktree: w.dir, commitRequired: false, mergeRequired: false,
+                        note: `${error}; worktree non eseguito conservato in ${w.dir}`,
+                    } } : {}),
+            };
+        },
+        run: async (castle, index) => {
+            const w = wt.get(castle.slug);
+            if (w && castle.after?.length) {
+                const synced = await integrate(() => runGit(w.dir, ["merge", "--ff-only", base], signal));
+                if (synced.code !== 0)
+                    throw new Error(`impossibile acquisire i prerequisiti in ${w.dir}: ${gitResultDetail(synced)}`);
+            }
+            opts.onMemberState?.(castle.slug, "running");
+            const report = await executeMember(castle, index);
+            if (!w || signal.aborted)
+                return report;
+            const finalized = await integrate(() => signal.aborted ? Promise.resolve(report) : finalizeVassalWorktree({
+                root: root, base: base, branch: w.branch, dir: w.dir, report, signal,
+            }));
+            onNotice?.(finalized.merge?.ok ? `[${castle.slug}] merge verificato in ${base}; cleanup completato`
+                : `[${castle.slug}] integrazione sospesa: ${finalized.recovery?.note ?? finalized.error ?? "errore"}`);
+            return finalized;
+        },
+        settled: (castle, report) => {
+            handoffs.set(castle.slug, report);
+            opts.onMemberState?.(castle.slug, report.ok ? "completed" : "failed", report);
+        },
+    });
+    if (signal.aborted) {
+        // Non eseguire commit/merge seriali dopo lo stop: erano la parte che
+        // faceva sembrare il comando bloccato. I worktree con lavoro parziale
+        // restano esplicitamente recuperabili, senza fondere modifiche incomplete.
+        onNotice?.("swarm arrestato; nessun merge ulteriore del lavoro parziale");
+        return castles.map((castle, index) => {
+            const report = reports[index];
+            const w = wt.get(castle.slug);
+            const note = w
+                ? `arrestato prima del completamento; worktree conservato in ${w.dir}`
+                : "arrestato prima dell'avvio";
+            if (report) {
+                if (report.merge?.ok)
+                    return report;
+                return w ? {
+                    ...report,
+                    ok: false,
+                    error: report.error || note,
+                    branch: w.branch,
+                    worktree: w.dir,
+                    recovery: {
+                        reason: "vassal-failed",
+                        worktree: w.dir,
+                        commitRequired: true,
+                        mergeRequired: true,
+                        note,
+                    },
+                } : report;
+            }
+            return {
+                slug: castle.slug,
+                ok: false,
+                summary: "",
+                rooms: 0,
+                model: castle.model?.trim() || harness.config.model,
+                role: castle.role?.trim() || "collaboratore",
+                parent: castle.parent?.trim() || "orchestratore",
+                ...(castle.castle ? { workstreamId: castle.castle } : {}),
+                ...(castle.tasks?.length ? { taskRefs: [...castle.tasks] } : {}),
+                error: note,
+                ...(w ? {
+                    branch: w.branch,
+                    worktree: w.dir,
+                    recovery: {
+                        reason: "vassal-failed",
+                        worktree: w.dir,
+                        commitRequired: true,
+                        mergeRequired: true,
+                        note,
+                    },
+                } : {}),
+            };
+        });
+    }
+    return reports;
+}
+// Preambolo di coordinamento del vassallo: chi e', con chi collabora, le sue
+// dipendenze, e come cooperare attivamente (annuncia/aspetta) via i kingdom tool.
+function vassalSteer(self, peers, after, identity, git, mandateBlock) {
+    const others = peers.filter((p) => p !== self);
+    // Regola git diversa per modalita': isolato (worktree dedicato → committa sul
+    // tuo ramo) vs condiviso (working dir comune → niente git che muta).
+    const gitDef = git.isolated
+        ? `@git[isolato]: lavori in una working dir TUA (worktree) su un ramo TUO; usa PATH RELATIVI; committa il tuo lavoro qui (git add/commit liberi). Chi ti ha ingaggiato fara' il merge del tuo ramo in "${git.base ?? "base"}". NON cambiare ramo/checkout/reset, NON toccare altri worktree.`
+        : `@git[condiviso]: NON eseguire git che modifica (add/commit/push/pull/reset/checkout/stash/clean): condividi la STESSA working dir con gli altri, vi sovrascrivereste; modifica SOLO i file, il commit avviene UNA volta sola alla fine fuori dallo swarm (git status/diff sono ok)`;
+    const gitRel = git.isolated
+        ? `@R4: @ruolo[collaboratore] -> @git[isolato]  [ committa sul tuo ramo, path relativi ]`
+        : `@R4: @ruolo[collaboratore] -> @git[condiviso]  [ niente git che muta, solo edit dei file ]`;
+    const gitOut = git.isolated
+        ? `committa il tuo lavoro sul TUO ramo (il merge lo fa chi ti ha ingaggiato).`
+        : `NIENTE git che modifica.`;
+    return `[COLLABORATORE ${self}]
+INDICE
+1 = ruolo
+2 = dipendenze
+3 = cooperazione
+4 = confine
+
+DEFINIZIONI
+@ruolo[collaboratore]: id=${self}, ruolo=${identity.role}, parent=${identity.parent}, peer=[${others.join(", ") || "nessuno"}]
+@dipendenze[after]: ${after.length ? after.join(", ") : "nessuna (parti subito)"}
+@cooperazione[annuncio]: all'avvio usa team_say(to="${identity.parent}") per confermare task e piano breve; durante il lavoro annuncia milestone; alla fine invia esito e file toccati
+@cooperazione[ascolto]: team_inbox REGOLARMENTE — dopo ogni passaggio, non solo se dipendi da qualcuno: chi ti scrive puo' averti risparmiato un lavoro sbagliato, o aspettare una tua risposta
+@cooperazione[attesa]: team_wait(from/contains) solo se non hai altro di utile da fare; se puoi andare avanti su un altro pezzo, vai avanti
+@cooperazione[info]: tieni informato chi dipende da te, e rispondi a chi ti chiede qualcosa: un messaggio senza risposta blocca chi l'ha mandato
+@cooperazione[scoperte]: se scopri qualcosa che cambia il lavoro di un altro (un file che non e' dove sembrava, un'assunzione che non regge) diglielo SUBITO con team_say, prima che ci sbatta anche lui
+@confine[regola]: resta nel tuo incarico, non duplicare il lavoro altrui
+${gitDef}
+
+RELAZIONI
+@R1: @cooperazione[ascolto] -> @cooperazione[scoperte]  [ si lavora insieme, non in parallelo silenzioso ]
+@R2: @ruolo[collaboratore] -> @cooperazione[annuncio]  [ sblocca gli altri annunciando ]
+@R3: @ruolo[collaboratore] -> @confine[regola]  [ niente sovrapposizioni ]
+${gitRel}
+
+OUTPUT: esegui il tuo incarico cooperando con gli altri (annuncia/ascolta/aspetta), resta nel confine, ${gitOut}
+
+${mandateBlock ? `${mandateBlock}\n\n` : ""}OBIETTIVO_ATTIVITA
+`;
+}
+const MAX_UNITS = 16;
+// Mandato del collaboratore: il castello del PIANO che gli e' stato affidato.
+// Assente quando l'assegnazione e' solo una frase (nessun `castle`).
+function resolveMandate(sessionDir, planStoreId, castle) {
+    if (!castle.castle)
+        return null;
+    const store = VascendPlanStore.open(sessionDir, planStoreId, { strict: true });
+    const plan = store.castle(castle.castle);
+    if (!plan)
+        throw new Error(`gruppo assegnato non trovato: ${castle.castle}`);
+    for (const ref of castle.tasks ?? []) {
+        if (!plan.tasks.some((task) => task.id.toLowerCase() === ref.toLowerCase() || String(task.bit) === ref)) {
+            throw new Error(`attivita assegnata non trovata: ${castle.castle}/${ref}`);
+        }
+    }
+    const mandate = mandateFor(store, castle.castle, castle.tasks);
+    if (!mandate)
+        throw new Error(`nessun task aperto nel gruppo assegnato: ${castle.castle}`);
+    return mandate;
+}
+function unitGoal(goal, files, skills) {
+    const hints = [
+        files?.length ? `file: ${files.join(", ")}` : "",
+        skills?.length ? `skill: ${skills.join(", ")}` : "",
+    ].filter(Boolean).join(" · ");
+    return hints ? `${goal}\n(${hints})` : goal;
+}
+/**
+ * Converte le richieste del vassallo in unita' del team. Quando lo slug e' un
+ * ref del suo mandato (T01...) l'unita' EREDITA la stanza: titolo, peso, file e
+ * skill che l'orchestratore aveva gia' allegato al piano.
+ */
+function toUnits(specs, mandate) {
+    const rooms = new Map((mandate?.rooms ?? []).map((room) => [room.ref.toLowerCase(), room]));
+    const built = [];
+    const seen = new Set();
+    for (const spec of specs.slice(0, MAX_UNITS)) {
+        const raw = String(spec.slug ?? "").trim();
+        if (!raw)
+            continue;
+        const room = rooms.get(raw.toLowerCase());
+        const id = room ? room.ref : raw;
+        if (seen.has(id.toLowerCase()))
+            continue;
+        const goal = String(spec.goal ?? "").trim() || room?.title || "";
+        if (!goal)
+            continue;
+        seen.add(id.toLowerCase());
+        built.push({
+            id,
+            goal: room ? unitGoal(goal, room.files, room.skills) : goal,
+            assignment: { ...spec, ...(room && !spec.area?.length && room.files?.length ? { area: room.files } : {}) },
+            ...(spec.after?.length ? { deps: [...spec.after] } : {}),
+            ...(room?.weight ? { weight: room.weight } : {}),
+        });
+    }
+    // Preserve unknown dependencies so validation reports them instead of
+    // silently starting a task whose prerequisite was never assigned.
+    const ids = new Map(built.map((unit) => [unit.id.toLowerCase(), unit.id]));
+    return built.map((unit) => {
+        const deps = (unit.deps ?? [])
+            .map((dep) => ids.get(String(dep).trim().toLowerCase()) ?? dep);
+        const { deps: _drop, ...rest } = unit;
+        return deps.length ? { ...rest, deps: [...new Set(deps)] } : rest;
+    });
+}
+/**
+ * Delega dal collaboratore: forma un team sulle proprie stanze. Il granular
+ * launcher mantiene il grafo delle dipendenze e puo' propagare la facolta' di
+ * spawn ai figli fino al limite configurato; la decisione di usarla resta
+ * sempre dell'agente che sta lavorando.
+ */
+function subTeamSpawner(opts, castle, mandate, iso, planStoreId) {
+    return async (specs) => {
+        const units = toUnits(specs, mandate);
+        if (!units.length)
+            return "team non avviato: nessuna unita' con un task riconoscibile";
+        try {
+            const report = await launchGranularKingdom({
+                harness: opts.harness,
+                kingdomId: opts.kingdomId,
+                castleSlug: castle.slug,
+                units,
+                signal: opts.signal,
+                confirm: opts.confirm,
+                ask: opts.ask,
+                concurrency: granularConcurrency(process.env),
+                // Lo slug composto dice all'host che questi sono sotto-collaboratori di
+                // questo castello, non nuovi vassalli dell'Imperatore.
+                onEvent: (id, event) => opts.onEvent?.(`${castle.slug}/${id}`, event),
+                onNotice: (text) => opts.onNotice?.(`[${castle.slug}] ${text}`),
+                ...(iso.cwd ? { cwd: iso.cwd } : {}),
+                isolated: iso.isolated,
+                planStoreId,
+                ...(opts.fileCoordination ? { fileCoordination: opts.fileCoordination } : {}),
+                depth: 2,
+                maxDepth: Number.isInteger(Number(process.env["TALOS_KINGDOM_MAX_DEPTH"]))
+                    ? Math.max(1, Math.min(5, Number(process.env["TALOS_KINGDOM_MAX_DEPTH"])))
+                    : 3,
+                ...(mandate ? { markCastle: mandate.castle } : {}),
+            });
+            return formatGranularReport(report);
+        }
+        catch (err) {
+            // Grafo malformato (ciclo, id duplicati): lo dice al vassallo, che puo'
+            // correggere, invece di far cadere il suo turno.
+            return `team non avviato: ${err.message}`;
+        }
+    };
+}
+async function runVassal(opts, provider, modelId, displayModel, castle, peers, iso, prerequisites = []) {
+    const { harness, kingdomId, signal, confirm, onEvent } = opts;
+    // Sessione (conversazione) dedicata al vassallo; store memoria CONDIVISO del
+    // regno (kingdomId) con id stanze namespaced sullo slug del castello.
+    const session = Session.create(harness.config.sessionDir, `${kingdomId}-${castle.slug}`);
+    const effort = ["low", "medium", "high", "max"].includes(String(castle.effort ?? "").toLowerCase())
+        ? String(castle.effort).toLowerCase()
+        : "";
+    // Il piano resta quello di chi ha pianificato: le stanze che il collaboratore
+    // marca sono le stesse che l'utente vede sulla board.
+    // Gli host reali hanno sempre `harness.session`; i runner minimali/test e
+    // alcuni adapter legacy no. In quel caso il regno resta comunque uno scope
+    // stabile e condiviso invece di impedire lo spawn.
+    const planStoreId = harness.config.planStoreId ?? harness.session?.id ?? kingdomId;
+    const mandate = resolveMandate(harness.config.sessionDir, planStoreId, castle);
+    const runConfig = {
+        ...harness.config,
+        model: modelId,
+        ...(effort ? { effort } : {}),
+        roomStoreId: kingdomId,
+        roomNamespace: castle.slug,
+        planStoreId,
+        ...(mandate ? { planCastle: mandate.castle, planTasks: mandate.rooms.map((room) => room.ref) } : {}),
+        // In modalita' isolata la working dir del vassallo e' il suo worktree.
+        ...(iso.cwd ? { cwd: iso.cwd } : {}),
+    };
+    // Casella del vassallo: l'utente puo' scrivergli mentre lavora dalla sua
+    // scheda, e il messaggio entra nel contesto al primo confine sicuro come in
+    // chat principale. Senza, l'unico modo di correggerlo era fermare il regno.
+    const inbox = createUserInbox();
+    kingdomLive.register(kingdomId, castle.slug, inbox);
+    const workerTools = harness.tools.scoped(castle.tools);
+    for (const name of ["team_say", "team_inbox", "team_wait", "team_report", "vascend_status"])
+        workerTools.promote(name);
+    const deps = {
+        provider,
+        tools: workerTools,
+        session,
+        config: runConfig,
+        confirm,
+        ask: opts.ask,
+        host: undefined,
+        inbox,
+        ...(opts.fileCoordination ? {
+            fileCoordination: withFileActor(opts.fileCoordination, fileActor(`${opts.fileCoordination.actor.id}:${castle.slug}`, castle.slug, "subagent")),
+        } : {}),
+        // Delega di secondo livello: un castello grande si gestisce formando un team
+        // sulle proprie stanze. Prima questo campo mancava, e kingdoms_warm dentro
+        // un vassallo rispondeva "non disponibile": la gerarchia era ferma a 1.
+        spawnKingdom: subTeamSpawner({ ...opts, harness: { ...harness, config: runConfig, tools: workerTools } }, castle, mandate, iso, planStoreId),
+        // isolated abilita il git nel vassallo (worktree proprio); altrimenti il
+        // bash tool blocca il git che muta (working dir condivisa).
+        kingdom: { id: kingdomId, self: castle.slug, isolated: iso.isolated, peers },
+    };
+    let summary = "";
+    const artifacts = new Map();
+    const reportArtifacts = () => {
+        const store = ToolOutputStore.open(harness.config.sessionDir, kingdomId);
+        const entry = store.put("report-" + session.id, castle.slug + " report", summary.trim());
+        if (entry?.sha256)
+            artifacts.set(kingdomId + ":" + entry.id, { id: entry.id, scope: kingdomId, name: entry.name, sha256: entry.sha256, chars: entry.chars });
+        return [...artifacts.values()];
+    };
+    let runError = "";
+    let completed = false;
+    const sink = (event) => {
+        if (event.type === "tool_result") {
+            const ref = artifactReference(event.result);
+            if (ref) {
+                artifacts.set(ref.scope + ":" + ref.id, ref);
+                if (artifacts.size > 64)
+                    artifacts.delete(artifacts.keys().next().value);
+            }
+        }
+        if (event.type === "text")
+            summary += event.delta;
+        if (event.type === "error")
+            runError = event.message;
+        if (event.type === "done")
+            completed = true;
+        onEvent?.(castle.slug, event);
+    };
+    try {
+        const role = castle.role?.trim() || "collaboratore";
+        const parent = castle.parent?.trim() || "orchestratore";
+        const instructions = (castle.area?.length ? `\nAREA_ASSEGNATA: ${castle.area.join(", ")}. Coordina modifiche fuori area prima di eseguirle.\n` : "") + (castle.instructions?.trim()
+            ? `\nISTRUZIONI_AGGIUNTIVE\n${castle.instructions.trim()}\n\n`
+            : "\n");
+        // Con un castello assegnato l'obiettivo si DERIVA dal piano: nessuno deve
+        // riscrivere in prosa quello che le stanze dicono gia'.
+        const goal = castle.goal?.trim() || (mandate ? mandateGoal(mandate) : "");
+        const input = vassalSteer(castle.slug, peers, castle.after ?? [], { role, parent }, { isolated: iso.isolated, base: iso.base }, mandate ? formatMandate(mandate, true) : "") + instructions + (prerequisites.length ? "\nPREREQUISITI_COMPLETATI (risultati da verificare)\n"
+            + prerequisites.map((report) => `[${report.slug}] task=${(report.taskRefs ?? []).join(",")}\n`
+                + (report.artifacts ?? []).slice(-4).map((ref) => `output_page id="${ref.id}" scope="${ref.scope}" sha256=${ref.sha256}`).join("\n")
+                + "\n" + report.summary.slice(0, 1600)).join("\n").slice(0, 10000) + "\n\n" : "") + goal;
+        await runTurn(deps, input, sink, signal);
+        const rooms = countRooms(harness.config.sessionDir, kingdomId, castle.slug);
+        const completion = mandateCompletion(harness.config.sessionDir, planStoreId, mandate);
+        const ok = !signal.aborted && !runError && completed && completion.ok;
+        return {
+            slug: castle.slug,
+            ok,
+            summary: summary.trim(),
+            artifacts: reportArtifacts(),
+            rooms,
+            model: displayModel,
+            role,
+            parent,
+            ...(castle.castle ? { workstreamId: castle.castle } : {}),
+            ...(castle.tasks?.length
+                ? { taskRefs: [...castle.tasks] }
+                : mandate?.rooms.length ? { taskRefs: mandate.rooms.map((room) => room.ref) } : {}),
+            ...(!ok ? {
+                error: signal.aborted
+                    ? "collaboratore arrestato"
+                    : runError || completion.error || "task non completato",
+            } : {}),
+        };
+    }
+    catch (err) {
+        return {
+            slug: castle.slug,
+            ok: false,
+            summary: summary.trim(),
+            artifacts: reportArtifacts(),
+            rooms: 0,
+            model: displayModel,
+            role: castle.role?.trim() || "collaboratore",
+            parent: castle.parent?.trim() || "orchestratore",
+            ...(castle.castle ? { workstreamId: castle.castle } : {}),
+            ...(castle.tasks?.length ? { taskRefs: [...castle.tasks] } : {}),
+            error: err.message,
+        };
+    }
+    finally {
+        deps.fileCoordination?.hub.clearActor(deps.fileCoordination.actor.id);
+        // Il collaboratore non c'e' piu': la UI deve saperlo subito, altrimenti
+        // continuerebbe a offrire un campo di scrittura che non consegna nulla.
+        kingdomLive.release(kingdomId, castle.slug);
+    }
+}
+function mandateCompletion(sessionDir, planStoreId, mandate) {
+    if (!mandate)
+        return { ok: true };
+    try {
+        const current = VascendPlanStore.open(sessionDir, planStoreId).castle(mandate.castle);
+        if (!current)
+            return { ok: false, error: `gruppo ${mandate.castle} non piu' disponibile` };
+        const refs = new Set(mandate.rooms.map((room) => room.ref.toLowerCase()));
+        const assigned = current.tasks.filter((task) => refs.has(task.id.toLowerCase()));
+        const failed = assigned.filter((task) => task.status === "failed");
+        const open = assigned.filter((task) => task.status !== "completed" && task.status !== "failed");
+        if (failed.length) {
+            return { ok: false, error: `task falliti: ${failed.map((task) => task.id).join(", ")}` };
+        }
+        if (assigned.length !== refs.size || open.length) {
+            const pending = open.map((task) => `${task.id} (${task.status})`);
+            return {
+                ok: false,
+                error: `task non conclusi: ${pending.length ? pending.join(", ") : "assegnazione incompleta"}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: `verifica task fallita: ${err.message}` };
+    }
+}
+// Conta le stanze (livello 0) di un castello nello store condiviso del regno.
+function countRooms(sessionDir, kingdomId, slug) {
+    try {
+        const mem = RoomMemory.open(sessionDir, kingdomId);
+        return mem.all().filter((r) => r.level === 0 && r.room.startsWith(`${slug}-`)).length;
+    }
+    catch {
+        return 0;
+    }
+}