@vascend/talos 0.1.0

package/dist/vascend/work-agent.js

@@ -0,0 +1,83 @@
+// Esecuzione di UNA unita' di lavoro con un agente NUOVO.
+//
+// La proprieta' che rende possibile un run di giorni: il costo per unita' non
+// cresce. Ogni item apre una sessione propria e riceve solo il suo brief, quindi
+// la finestra parte pulita ogni volta. Cio' che DEVE accumularsi — la memoria
+// delle stanze, il piano, il profilo — resta sullo store condiviso: si eredita la
+// conoscenza, non la cronologia.
+//
+// L'esito non e' un'impressione: l'agente lo dichiara in chiusura con due righe
+// convenute, e chi non le scrive risulta "esito non dichiarato" (quindi si
+// ritenta). Il giudizio finale resta comunque del gate esterno.
+import { runTurn } from "../core/agent.js";
+import { Session } from "../core/session.js";
+const OUTCOME_MARK = "ESITO:";
+const EVIDENCE_MARK = "PROVE:";
+// Istruzioni di chiusura appese al brief. Sono l'unico contratto fra il ciclo e
+// l'agente: brevi, letterali, verificabili.
+export function briefFor(item) {
+    return [
+        `UNITA DI LAVORO ${item.id}: ${item.title}`,
+        "",
+        item.brief,
+        ...(item.reason ? ["", `TENTATIVO PRECEDENTE FALLITO: ${item.reason}`, "Non ripetere la stessa strada."] : []),
+        "",
+        "Lavori da solo su questa sola unita'. Nessuno leggera' la conversazione: cio' che",
+        "resta e' il codice, i file e le prove che dichiari.",
+        "Chiudi SEMPRE con due righe, in questo formato esatto:",
+        `${OUTCOME_MARK} ok        (oppure: ${OUTCOME_MARK} fallito <motivo in una riga>)`,
+        `${EVIDENCE_MARK} <file toccati, comandi eseguiti, output osservato>`,
+    ].join("\n");
+}
+// Legge le due righe convenute. PURA: si verifica senza agente.
+export function parseOutcome(text) {
+    const lines = String(text || "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const outcomeLine = [...lines].reverse().find((line) => line.toUpperCase().startsWith(OUTCOME_MARK));
+    const evidenceLine = [...lines].reverse().find((line) => line.toUpperCase().startsWith(EVIDENCE_MARK));
+    const evidence = evidenceLine
+        ? evidenceLine.slice(EVIDENCE_MARK.length).split(/\s*[;|]\s*/).map((part) => part.trim()).filter(Boolean)
+        : [];
+    if (!outcomeLine) {
+        return { ok: false, reason: "esito non dichiarato: l'unita' non ha chiuso con la riga ESITO" };
+    }
+    const value = outcomeLine.slice(OUTCOME_MARK.length).trim();
+    if (/^ok\b/i.test(value)) {
+        return { ok: true, ...(evidence.length ? { evidence } : {}) };
+    }
+    return {
+        ok: false,
+        reason: value.replace(/^fallito\s*/i, "").trim() || "fallito senza motivo dichiarato",
+        ...(evidence.length ? { evidence } : {}),
+    };
+}
+// Costruisce la funzione che il ciclo chiamera' per ogni unita'. `base` e' il
+// contesto dell'host (provider, tool, config): di quello si riusa tutto TRANNE
+// la sessione.
+export function createFreshAgentRunner(base, options = {}) {
+    return async (item, signal) => {
+        const session = Session.create(base.config.sessionDir, `work-${item.id}-${Date.now().toString(36)}`);
+        const deps = {
+            ...base,
+            session,
+            config: {
+                ...base.config,
+                ...(options.memoryScopeId ? { roomStoreId: options.memoryScopeId } : {}),
+                ...(options.planStoreId ? { planStoreId: options.planStoreId } : {}),
+            },
+        };
+        let text = "";
+        let failure = "";
+        await runTurn(deps, briefFor(item), (event) => {
+            if (event.type === "text")
+                text += event.delta;
+            // Un errore del provider non e' un fallimento dell'unita': va detto come
+            // tale, perche' al tentativo dopo la strada da cambiare non e' la stessa.
+            if (event.type === "error" && !failure)
+                failure = event.message;
+            options.onEvent?.(item, event);
+        }, signal);
+        if (failure)
+            return { ok: false, reason: `interrotta dal provider: ${failure}` };
+        return parseOutcome(text);
+    };
+}

package/dist/vascend/work-queue.d.ts

@@ -0,0 +1,62 @@
+export type WorkItemState = "ready" | "leased" | "done" | "blocked";
+export interface WorkItem {
+    readonly id: string;
+    readonly title: string;
+    readonly brief: string;
+    readonly state: WorkItemState;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly owner?: string;
+    readonly leaseUntil?: number;
+    readonly after?: readonly string[];
+    readonly source?: string;
+    readonly evidence?: readonly string[];
+    readonly reason?: string;
+    readonly log?: readonly string[];
+}
+export interface QueueCounts {
+    readonly ready: number;
+    readonly leased: number;
+    readonly done: number;
+    readonly blocked: number;
+    readonly total: number;
+}
+export declare const DEFAULT_MAX_ATTEMPTS = 3;
+export declare const DEFAULT_LEASE_MS: number;
+export interface NewWorkItem {
+    readonly title: string;
+    readonly brief: string;
+    readonly after?: readonly string[];
+    readonly source?: string;
+    readonly maxAttempts?: number;
+}
+export declare function makeItem(id: string, input: NewWorkItem, now: number): WorkItem;
+export declare function counts(items: readonly WorkItem[]): QueueCounts;
+export declare function claimable(items: readonly WorkItem[]): readonly WorkItem[];
+export declare function expire(items: readonly WorkItem[], now: number): readonly WorkItem[];
+export declare function claim(items: readonly WorkItem[], owner: string, now: number, leaseMs: number): {
+    readonly items: readonly WorkItem[];
+    readonly item: WorkItem | null;
+};
+export declare function heartbeat(items: readonly WorkItem[], id: string, owner: string, now: number, leaseMs: number): readonly WorkItem[];
+export declare function complete(items: readonly WorkItem[], id: string, now: number, evidence?: readonly string[]): readonly WorkItem[];
+export declare function fail(items: readonly WorkItem[], id: string, now: number, reason: string): readonly WorkItem[];
+export declare function formatQueue(items: readonly WorkItem[]): string;
+export declare class WorkQueue {
+    private readonly file;
+    private data;
+    private constructor();
+    static open(sessionDir: string, scope?: string): WorkQueue;
+    items(): readonly WorkItem[];
+    counts(): QueueCounts;
+    add(input: NewWorkItem, now?: number): WorkItem;
+    claim(owner: string, leaseMs?: number, now?: number): WorkItem | null;
+    sweep(now?: number): QueueCounts;
+    heartbeat(id: string, owner: string, leaseMs?: number, now?: number): void;
+    complete(id: string, evidence?: readonly string[], now?: number): void;
+    fail(id: string, reason: string, now?: number): void;
+    private read;
+    private write;
+}

package/dist/vascend/work-queue.js

@@ -0,0 +1,255 @@
+// Coda di lavoro durevole con LEASE: il pezzo che permette a un agente di
+// lavorare per giorni invece che per una conversazione.
+//
+// Il lavoro non puo' vivere nel contesto del modello. Un run lungo muore per due
+// motivi: la finestra si riempie, e qualunque interruzione (crash, riavvio,
+// provider giu') cancella lo stato. La via d'uscita e' la stessa che usa il
+// harness autonomo di oh-my-cli: gli item stanno FUORI, in una coda con una
+// macchina a stati, e ogni unita' di lavoro viene RIVENDICATA con un lease a
+// scadenza. Se chi la teneva non da' piu' segni di vita, il lease scade e l'item
+// torna disponibile: un crash diventa un ritardo, non una perdita.
+//
+//   ready --claim--> leased --complete--> done
+//     ^                 |
+//     |                 +--fail / lease scaduto--> ready (tentativo in piu')
+//     +-----------------------------------------------+
+//                                                     v
+//                                    blocked (tentativi esauriti, con motivo)
+//
+// Nucleo PURO: le transizioni sono funzioni su array immutabili, quindi si
+// verificano senza disco e senza orologio. La classe in fondo aggiunge la
+// persistenza atomica.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const DEFAULT_MAX_ATTEMPTS = 3;
+export const DEFAULT_LEASE_MS = 15 * 60_000;
+const MAX_LOG = 12;
+// --- nucleo puro --------------------------------------------------------------
+export function makeItem(id, input, now) {
+    const max = Number.isFinite(input.maxAttempts) && Number(input.maxAttempts) > 0
+        ? Math.trunc(Number(input.maxAttempts))
+        : DEFAULT_MAX_ATTEMPTS;
+    return {
+        id,
+        title: oneLine(input.title, 120) || id,
+        brief: String(input.brief || "").trim(),
+        state: "ready",
+        attempts: 0,
+        maxAttempts: max,
+        createdAt: now,
+        updatedAt: now,
+        ...(input.after?.length ? { after: [...input.after] } : {}),
+        ...(input.source ? { source: oneLine(input.source, 60) } : {}),
+        log: [`${stamp(now)} creato`],
+    };
+}
+export function counts(items) {
+    const tally = { ready: 0, leased: 0, done: 0, blocked: 0 };
+    for (const item of items)
+        tally[item.state] += 1;
+    return { ...tally, total: items.length };
+}
+// Item pronti a partire: stato ready e dipendenze tutte concluse. Ordine di
+// creazione, cosi' la coda e' prevedibile e riproducibile.
+export function claimable(items) {
+    const done = new Set(items.filter((item) => item.state === "done").map((item) => item.id));
+    return items
+        .filter((item) => item.state === "ready" && (item.after ?? []).every((dep) => done.has(dep)))
+        .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id));
+}
+// Lease scaduti: chi li teneva non ha dato segni di vita. Tornano disponibili
+// con un tentativo in piu'; esauriti i tentativi diventano blocked col motivo.
+// Il tentativo si conta alla RIVENDICAZIONE, non qui: un item che fa cadere il
+// processo deve consumare i suoi tentativi, altrimenti il loop ci gira sopra
+// per sempre.
+export function expire(items, now) {
+    return items.map((item) => {
+        if (item.state !== "leased")
+            return item;
+        if (Number(item.leaseUntil ?? 0) > now)
+            return item;
+        const exhausted = item.attempts >= item.maxAttempts;
+        return trim({
+            ...item,
+            state: exhausted ? "blocked" : "ready",
+            updatedAt: now,
+            ...(exhausted ? { reason: `nessun segno di vita dopo ${item.attempts} tentativi` } : {}),
+            owner: undefined,
+            leaseUntil: undefined,
+            log: [...(item.log ?? []), `${stamp(now)} lease scaduto (${item.owner || "?"}) -> ${exhausted ? "blocked" : "ready"}`],
+        });
+    });
+}
+export function claim(items, owner, now, leaseMs) {
+    const next = claimable(items)[0];
+    if (!next)
+        return { items, item: null };
+    const claimed = trim({
+        ...next,
+        state: "leased",
+        owner: String(owner || "agente"),
+        leaseUntil: now + Math.max(1_000, leaseMs),
+        attempts: next.attempts + 1,
+        updatedAt: now,
+        log: [...(next.log ?? []), `${stamp(now)} rivendicato da ${owner} (tentativo ${next.attempts + 1}/${next.maxAttempts})`],
+    });
+    return { items: replace(items, claimed), item: claimed };
+}
+export function heartbeat(items, id, owner, now, leaseMs) {
+    return items.map((item) => (item.id === id && item.state === "leased" && item.owner === owner
+        ? { ...item, leaseUntil: now + Math.max(1_000, leaseMs), updatedAt: now }
+        : item));
+}
+export function complete(items, id, now, evidence = []) {
+    return items.map((item) => (item.id === id ? trim({
+        ...item,
+        state: "done",
+        owner: undefined,
+        leaseUntil: undefined,
+        updatedAt: now,
+        ...(evidence.length ? { evidence: evidence.map((line) => oneLine(line, 200)) } : {}),
+        log: [...(item.log ?? []), `${stamp(now)} concluso`],
+    }) : item));
+}
+// Esito negativo dichiarato (dall'agente o dal gate di verifica). Il motivo
+// resta attaccato all'item: al tentativo dopo, chi lo riprende sa cosa e'
+// andato storto invece di ripetere lo stesso errore.
+export function fail(items, id, now, reason) {
+    return items.map((item) => {
+        if (item.id !== id)
+            return item;
+        const exhausted = item.attempts >= item.maxAttempts;
+        return trim({
+            ...item,
+            state: exhausted ? "blocked" : "ready",
+            owner: undefined,
+            leaseUntil: undefined,
+            updatedAt: now,
+            reason: oneLine(reason, 400),
+            log: [...(item.log ?? []), `${stamp(now)} fallito: ${oneLine(reason, 120)} -> ${exhausted ? "blocked" : "ready"}`],
+        });
+    });
+}
+export function formatQueue(items) {
+    if (!items.length)
+        return "coda vuota";
+    const tally = counts(items);
+    const head = `${tally.total} item · ${tally.ready} pronti · ${tally.leased} in corso · ${tally.done} conclusi · ${tally.blocked} bloccati`;
+    const rows = items.map((item) => {
+        const extra = item.state === "leased" ? `:${item.owner}` : "";
+        // Il motivo si mostra anche su un item tornato pronto: e' cio' che chi lo
+        // riprende deve sapere prima di ripetere la stessa strada.
+        const why = item.state !== "done" && item.reason ? ` — ${oneLine(item.reason, 90)}` : "";
+        const deps = item.after?.length ? ` dopo ${item.after.join(",")}` : "";
+        return `${item.id} [${item.state}${extra}] ${item.title}${deps} · tentativi ${item.attempts}/${item.maxAttempts}${why}`;
+    });
+    return [head, ...rows].join("\n");
+}
+const EMPTY = { version: 1, nextSeq: 1, items: [] };
+export class WorkQueue {
+    file;
+    data;
+    constructor(file) {
+        this.file = file;
+        this.data = this.read();
+    }
+    static open(sessionDir, scope = "default") {
+        const dir = join(sessionDir, "work-queue");
+        return new WorkQueue(join(dir, `${sanitize(scope)}.json`));
+    }
+    items() {
+        return this.data.items;
+    }
+    counts() {
+        return counts(this.data.items);
+    }
+    add(input, now = Date.now()) {
+        const id = `w${this.data.nextSeq}`;
+        const item = makeItem(id, input, now);
+        this.write({ version: 1, nextSeq: this.data.nextSeq + 1, items: [...this.data.items, item] });
+        return item;
+    }
+    // Ogni lettura per lavorare passa da qui: prima si recuperano i lease scaduti,
+    // poi si rivendica. Il watchdog non e' un processo a parte, e' un passo del
+    // ciclo — cosi' non esiste il caso "il watchdog era spento".
+    claim(owner, leaseMs = DEFAULT_LEASE_MS, now = Date.now()) {
+        const recovered = expire(this.data.items, now);
+        const outcome = claim(recovered, owner, now, leaseMs);
+        this.write({ ...this.data, items: outcome.items });
+        return outcome.item;
+    }
+    sweep(now = Date.now()) {
+        this.write({ ...this.data, items: expire(this.data.items, now) });
+        return this.counts();
+    }
+    heartbeat(id, owner, leaseMs = DEFAULT_LEASE_MS, now = Date.now()) {
+        this.write({ ...this.data, items: heartbeat(this.data.items, id, owner, now, leaseMs) });
+    }
+    complete(id, evidence = [], now = Date.now()) {
+        this.write({ ...this.data, items: complete(this.data.items, id, now, evidence) });
+    }
+    fail(id, reason, now = Date.now()) {
+        this.write({ ...this.data, items: fail(this.data.items, id, now, reason) });
+    }
+    read() {
+        try {
+            if (!existsSync(this.file))
+                return EMPTY;
+            const parsed = JSON.parse(readFileSync(this.file, "utf8"));
+            if (!parsed || !Array.isArray(parsed.items))
+                return EMPTY;
+            const seq = Number(parsed.nextSeq);
+            return {
+                version: 1,
+                nextSeq: Number.isFinite(seq) && seq > 0 ? Math.trunc(seq) : parsed.items.length + 1,
+                items: parsed.items,
+            };
+        }
+        catch {
+            // Una coda illeggibile non deve diventare una coda cancellata: si riparte
+            // vuoti in memoria ma il file resta sul disco per l'ispezione.
+            return EMPTY;
+        }
+    }
+    // Scrittura atomica: un'interruzione a meta' non deve lasciare una coda
+    // troncata, che e' esattamente lo stato in cui il recupero serve.
+    write(next) {
+        this.data = next;
+        try {
+            mkdirSync(join(this.file, ".."), { recursive: true });
+            const tmp = `${this.file}.tmp-${process.pid}`;
+            writeFileSync(tmp, JSON.stringify(next, null, 2), "utf8");
+            renameSync(tmp, this.file);
+        }
+        catch {
+            // La coda in memoria resta valida per questo giro: il chiamante lo scopre
+            // al riavvio, non a meta' di un'unita' di lavoro.
+        }
+    }
+}
+// --- helper ------------------------------------------------------------------
+function replace(items, item) {
+    return items.map((current) => (current.id === item.id ? item : current));
+}
+// I campi undefined non devono finire nel JSON (owner/leaseUntil di un item
+// tornato ready): un lease "presente ma nullo" e' un lease che confonde.
+function trim(item) {
+    const out = { ...item };
+    for (const key of ["owner", "leaseUntil", "reason", "evidence"]) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    if (Array.isArray(out["log"]))
+        out["log"] = out["log"].slice(-MAX_LOG);
+    return out;
+}
+function oneLine(value, max) {
+    const clean = String(value ?? "").replace(/\s+/g, " ").trim();
+    return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+function stamp(now) {
+    return new Date(now).toISOString().slice(0, 19).replace("T", " ");
+}
+function sanitize(value) {
+    return String(value || "default").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}

package/dist/vascend/work-runner.d.ts

@@ -0,0 +1,64 @@
+import { WorkQueue, type QueueCounts, type WorkItem } from "./work-queue.js";
+export interface ItemOutcome {
+    readonly ok: boolean;
+    readonly evidence?: readonly string[];
+    readonly reason?: string;
+}
+export interface GateOutcome {
+    readonly ok: boolean;
+    readonly log: string;
+}
+export type LoopEvent = {
+    readonly type: "sweep";
+    readonly counts: QueueCounts;
+} | {
+    readonly type: "claimed";
+    readonly item: WorkItem;
+} | {
+    readonly type: "ran";
+    readonly item: WorkItem;
+    readonly outcome: ItemOutcome;
+    readonly ms: number;
+} | {
+    readonly type: "gate";
+    readonly item: WorkItem;
+    readonly gate: GateOutcome;
+} | {
+    readonly type: "settled";
+    readonly item: WorkItem;
+    readonly state: "done" | "retry" | "blocked";
+} | {
+    readonly type: "idle";
+    readonly counts: QueueCounts;
+} | {
+    readonly type: "stopped";
+    readonly why: StopReason;
+    readonly counts: QueueCounts;
+};
+export type StopReason = "coda-vuota" | "budget-item" | "scadenza" | "interrotto" | "errore-ripetuto";
+export interface WorkLoopDeps {
+    readonly queue: WorkQueue;
+    readonly runItem: (item: WorkItem, signal: AbortSignal) => Promise<ItemOutcome>;
+    readonly verify?: (item: WorkItem, outcome: ItemOutcome) => Promise<GateOutcome>;
+    readonly owner?: string;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly onEvent?: (event: LoopEvent) => void;
+}
+export interface WorkLoopOptions {
+    readonly maxItems?: number;
+    readonly deadline?: number;
+    readonly leaseMs?: number;
+    readonly waitWhenEmptyMs?: number;
+    readonly idleRounds?: number;
+    readonly signal?: AbortSignal;
+}
+export interface LoopReport {
+    readonly why: StopReason;
+    readonly done: number;
+    readonly retried: number;
+    readonly blocked: number;
+    readonly ms: number;
+    readonly counts: QueueCounts;
+}
+export declare function runWorkLoop(deps: WorkLoopDeps, options?: WorkLoopOptions): Promise<LoopReport>;

package/dist/vascend/work-runner.js

@@ -0,0 +1,137 @@
+// Il ciclo che sta FUORI dalla conversazione.
+//
+// Un agente che lavora per giorni non e' un turno lungo: e' una sequenza di
+// unita' di lavoro brevi, ognuna eseguita da un agente NUOVO che riceve solo il
+// suo brief. Cosi' il contesto non cresce (il costo per unita' resta costante) e
+// un'interruzione perde un'unita', non il lavoro.
+//
+//   sweep (recupera i lease scaduti)
+//     -> claim (rivendica un'unita')
+//        -> esegui con un agente nuovo, battendo il cuore mentre lavora
+//           -> VERIFICA ESTERNA (exit code, non opinione del modello)
+//              -> verde: done   |   rosso: fail (ritenta, o blocked)
+//     -> ripeti fino a coda vuota o budget esaurito
+//
+// La verifica e' un parametro: chi la fornisce decide cosa vuol dire "fatto".
+// Senza di essa il ciclo si fida di chi ha scritto il codice, che e' il modo
+// tipico in cui i run lunghi divergono in silenzio.
+import { DEFAULT_LEASE_MS, WorkQueue, } from "./work-queue.js";
+export async function runWorkLoop(deps, options = {}) {
+    const now = deps.now ?? (() => Date.now());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const owner = deps.owner || "runner";
+    const leaseMs = Math.max(1_000, options.leaseMs ?? DEFAULT_LEASE_MS);
+    const maxItems = Math.max(1, Math.trunc(options.maxItems ?? 25));
+    const idleRounds = Math.max(0, Math.trunc(options.idleRounds ?? 0));
+    const startedAt = now();
+    let done = 0;
+    let retried = 0;
+    let blocked = 0;
+    let idle = 0;
+    // Due esecuzioni di fila che esplodono nel RUNNER (non nell'unita') sono un
+    // guasto dell'impianto: continuare consumerebbe i tentativi di tutta la coda.
+    let crashes = 0;
+    const emit = (event) => {
+        try {
+            deps.onEvent?.(event);
+        }
+        catch { /* l'osservatore non governa il ciclo */ }
+    };
+    const stop = (why) => {
+        const counts = deps.queue.counts();
+        emit({ type: "stopped", why, counts });
+        return { why, done, retried, blocked, ms: now() - startedAt, counts };
+    };
+    while (done + retried + blocked < maxItems) {
+        if (options.signal?.aborted)
+            return stop("interrotto");
+        if (options.deadline && now() >= options.deadline)
+            return stop("scadenza");
+        emit({ type: "sweep", counts: deps.queue.sweep(now()) });
+        const item = deps.queue.claim(owner, leaseMs, now());
+        if (!item) {
+            const counts = deps.queue.counts();
+            emit({ type: "idle", counts });
+            if (idle >= idleRounds || !options.waitWhenEmptyMs)
+                return stop("coda-vuota");
+            idle += 1;
+            await sleep(options.waitWhenEmptyMs);
+            continue;
+        }
+        idle = 0;
+        emit({ type: "claimed", item });
+        // Il battito tiene il lease vivo mentre l'unita' lavora: senza, un'unita'
+        // legittimamente lunga verrebbe rubata dal watchdog a meta'.
+        const beat = setInterval(() => {
+            try {
+                deps.queue.heartbeat(item.id, owner, leaseMs, now());
+            }
+            catch { /* riprovera' */ }
+        }, Math.max(1_000, Math.floor(leaseMs / 3)));
+        if (typeof beat.unref === "function")
+            beat.unref();
+        const controller = new AbortController();
+        const onAbort = () => controller.abort();
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const at = now();
+        let outcome;
+        try {
+            outcome = await deps.runItem(item, controller.signal);
+            crashes = 0;
+        }
+        catch (error) {
+            crashes += 1;
+            outcome = { ok: false, reason: `esecuzione interrotta: ${error?.message ?? String(error)}` };
+        }
+        finally {
+            clearInterval(beat);
+            options.signal?.removeEventListener("abort", onAbort);
+        }
+        emit({ type: "ran", item, outcome, ms: now() - at });
+        // Il gate gira SOLO se l'unita' si dichiara riuscita: verificare un
+        // fallimento dichiarato costa e non cambia l'esito.
+        let gate = null;
+        if (outcome.ok && deps.verify) {
+            try {
+                gate = await deps.verify(item, outcome);
+            }
+            catch (error) {
+                gate = { ok: false, log: `verifica non eseguibile: ${error?.message ?? String(error)}` };
+            }
+            emit({ type: "gate", item, gate });
+        }
+        const passed = outcome.ok && (gate ? gate.ok : true);
+        if (passed) {
+            const evidence = [...(outcome.evidence ?? []), ...(gate ? [`verifica: ${firstLines(gate.log, 2)}`] : [])];
+            deps.queue.complete(item.id, evidence, now());
+            done += 1;
+            emit({ type: "settled", item, state: "done" });
+        }
+        else {
+            const reason = gate && !gate.ok
+                ? `verifica fallita: ${firstLines(gate.log, 6)}`
+                : (outcome.reason || "esito negativo senza motivo dichiarato");
+            deps.queue.fail(item.id, reason, now());
+            const after = deps.queue.items().find((current) => current.id === item.id);
+            if (after?.state === "blocked") {
+                blocked += 1;
+                emit({ type: "settled", item, state: "blocked" });
+            }
+            else {
+                retried += 1;
+                emit({ type: "settled", item, state: "retry" });
+            }
+        }
+        if (crashes >= 2)
+            return stop("errore-ripetuto");
+    }
+    return stop("budget-item");
+}
+function firstLines(text, lines) {
+    return String(text || "")
+        .split(/\r?\n/)
+        .filter((line) => line.trim())
+        .slice(0, lines)
+        .join(" | ")
+        .slice(0, 400);
+}

package/dist/vascend/worktree.d.ts

@@ -0,0 +1,38 @@
+export interface GitResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommitAllResult {
+    readonly ok: boolean;
+    readonly committed: boolean;
+    readonly clean: boolean;
+    readonly note: string;
+}
+export interface BaseBranchCheck {
+    readonly ok: boolean;
+    readonly current: string | null;
+    readonly note: string;
+}
+export declare function runGit(cwd: string, args: readonly string[], signal?: AbortSignal): Promise<GitResult>;
+export declare function worktreeMode(env: NodeJS.ProcessEnv): boolean;
+export declare function isGitRepo(cwd: string): Promise<boolean>;
+export declare function repoRoot(cwd: string): Promise<string | null>;
+export declare function currentBranch(cwd: string, signal?: AbortSignal): Promise<string | null>;
+export declare function resolveBaseBranch(cwd: string, env: NodeJS.ProcessEnv, explicit?: string): Promise<string | null>;
+export declare function verifyBaseBranch(root: string, base: string, signal?: AbortSignal): Promise<BaseBranchCheck>;
+export declare function sanitizeRef(s: string): string;
+export declare function vassalBranchName(kingdomId: string, slug: string): string;
+export declare function worktreeDir(kingdomId: string, slug: string): string;
+export declare function addWorktree(root: string, dir: string, branch: string, base: string, signal?: AbortSignal): Promise<GitResult>;
+export declare function commitAll(dir: string, message: string, signal?: AbortSignal): Promise<CommitAllResult>;
+export interface MergeResult {
+    readonly ok: boolean;
+    readonly conflict: boolean;
+    readonly note: string;
+    readonly integrated?: boolean;
+}
+export declare function mergeBack(root: string, base: string, branch: string, message: string, signal?: AbortSignal): Promise<MergeResult>;
+export declare function removeWorktree(root: string, dir: string, signal?: AbortSignal): Promise<GitResult>;
+export declare function deleteBranch(root: string, branch: string, signal?: AbortSignal): Promise<GitResult>;
+export declare function revParse(cwd: string, ref: string, signal?: AbortSignal): Promise<string | null>;