@sylad/cadence 0.7.0 → 0.9.0

package/dist/orchestrate/guard.js

@@ -0,0 +1,131 @@
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { gitCommonDir, gitRoot, hooksDir } from '../git.js';
+const MARK = '# cadence orchestrate — hook pre-push temporaire (retiré à la fin de la vague)';
+const waveLine = (wave) => `# wave: ${wave}`;
+const hook = (wave) => `#!/bin/sh
+${MARK}
+${waveLine(wave)}
+# Une session lancée par l'orchestrateur porte CADENCE_ORCHESTRATED : elle ne pousse jamais.
+if [ -n "$CADENCE_ORCHESTRATED" ]; then
+  echo "cadence orchestrate : push refusé pendant la vague $CADENCE_ORCHESTRATED (le lead pousse)" >&2
+  exit 1
+fi
+exit 0
+`;
+const hookPath = (repo) => join(hooksDir(repo), 'pre-push');
+/**
+ * Ligne d'exclusion du hook quand `core.hooksPath` pointe dans l'arbre suivi (maritime-atlas : `.githooks`) :
+ * sans elle le hook temporaire serait un fichier non suivi du dépôt. null quand le hook est hors de l'arbre
+ * (`.git/hooks`, dossier extérieur) : rien à exclure.
+ */
+function excludeLine(repo) {
+    const root = gitRoot(repo);
+    if (!root)
+        return null;
+    const rel = relative(root, hookPath(repo));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return null;
+    const dotGit = relative(root, gitCommonDir(repo));
+    if (rel === dotGit || rel.startsWith(`${dotGit}/`))
+        return null;
+    return `/${rel.split('\\').join('/')}`;
+}
+const excludeFile = (repo) => join(gitCommonDir(repo), 'info', 'exclude');
+function addExclude(repo) {
+    const line = excludeLine(repo);
+    if (!line)
+        return;
+    const file = excludeFile(repo);
+    mkdirSync(join(gitCommonDir(repo), 'info'), { recursive: true });
+    const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    if (text.split('\n').includes(line))
+        return;
+    appendFileSync(file, `${text === '' || text.endsWith('\n') ? '' : '\n'}${line}\n`);
+}
+function removeExclude(repo) {
+    const line = excludeLine(repo);
+    const file = excludeFile(repo);
+    if (!line || !existsSync(file))
+        return;
+    const lines = readFileSync(file, 'utf8').split('\n');
+    if (!lines.includes(line))
+        return;
+    writeFileSync(file, lines.filter((l) => l !== line).join('\n'));
+}
+/**
+ * Pose le hook pre-push temporaire. Refus (raison) quand un autre hook pre-push existe : le remplacer
+ * modifierait un fichier suivi (husky) ou sauterait une règle du projet. Un hook laissé par une vague
+ * interrompue (même marque) est simplement remplacé.
+ */
+export function installPrePush(repo, wave = '?') {
+    const file = hookPath(repo);
+    if (existsSync(file) && !readFileSync(file, 'utf8').includes(MARK)) {
+        return { ok: false, reason: `un hook pre-push existe déjà (${file}) : l'orchestrateur ne le remplace pas` };
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    addExclude(repo);
+    writeFileSync(file, hook(wave));
+    chmodSync(file, 0o755);
+    return { ok: true };
+}
+/**
+ * Retire le hook s'il est le nôtre ; avec `wave`, seulement s'il a été posé par cette vague (jamais celui d'une
+ * autre vague vivante, qui garde aussi sa ligne d'exclusion). Hook supprimé ou remplacé par une session : la ligne
+ * d'exclusion part quand même, sinon un futur pre-push du projet resterait invisible à git.
+ */
+export function removePrePush(repo, wave) {
+    const file = hookPath(repo);
+    if (existsSync(file)) {
+        const text = readFileSync(file, 'utf8');
+        if (text.includes(MARK)) {
+            if (wave !== undefined && !text.split('\n').includes(waveLine(wave)))
+                return;
+            rmSync(file, { force: true });
+        }
+    }
+    removeExclude(repo);
+}
+/** Pourrait-on poser le hook ? (préconditions, sans écrire) */
+export function canInstallPrePush(repo) {
+    const file = hookPath(repo);
+    return existsSync(file) && !readFileSync(file, 'utf8').includes(MARK) ? `un hook pre-push existe déjà (${file}) : l'orchestrateur ne le remplace pas` : null;
+}
+/** git sans bloquer la boucle d'événements (un `ls-remote` peut durer 20 s) ; null en cas d'échec ou de délai. */
+function out(repo, args, timeout = 20_000) {
+    return new Promise((resolve) => {
+        // trimEnd seulement : la première colonne d'un `status --porcelain` peut être une espace.
+        execFile('git', args, { cwd: repo, encoding: 'utf8', timeout, maxBuffer: 1024 * 1024 * 1024 }, (err, stdout) => resolve(err ? null : stdout.trimEnd()));
+    });
+}
+/** Le hook temporaire (reconnu à sa marque) est-il en place ? */
+export function guardPresent(repo) {
+    const file = hookPath(repo);
+    return existsSync(file) && readFileSync(file, 'utf8').includes(MARK);
+}
+export async function snapshot(repo, opts = {}) {
+    const [status, head, upstream, remote] = await Promise.all([
+        out(repo, ['status', '--porcelain', '--untracked-files=all']),
+        out(repo, ['rev-parse', '--verify', '-q', 'HEAD']),
+        out(repo, ['rev-parse', '-q', '--verify', '@{u}']),
+        opts.remote === false ? Promise.resolve(null) : out(repo, ['ls-remote', '--heads']),
+    ]);
+    const lines = (status ?? '').split('\n').filter(Boolean);
+    const keep = (l) => !/^.. \.cadence\//.test(l) && !/^\?\? \.cadence\//.test(l);
+    return {
+        head: head?.trim() || null,
+        tracked: lines.filter((l) => !l.startsWith('??') && keep(l)),
+        untracked: lines.filter((l) => l.startsWith('??') && keep(l)).map((l) => l.slice(3)),
+        upstream,
+        guard: guardPresent(repo),
+        remote,
+    };
+}
+/** Écart de la référence amont ou du dépôt distant depuis `before` : un push est parti. */
+export function pushed(before, after) {
+    if (before.upstream !== after.upstream)
+        return true;
+    return before.remote !== null && after.remote !== null && before.remote !== after.remote;
+}

package/dist/orchestrate/launch.js

@@ -0,0 +1,221 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { RafError } from '../plan.js';
+import { isQuotaMessage, lacksStructuredOutput, parseSession, salvageUsage, sumTokens, tokensOf } from './result.js';
+/** Outils interdits à toute session : pas de sous-agent, pas de push, de livraison ni de verdict. */
+export const DISALLOWED = ['Agent', 'Bash(git push:*)', 'Bash(cadence deliver:*)', 'Bash(raf done:*)', 'Bash(raf review:*)', 'Bash(raf ux:*)'];
+export function buildArgs(spec, agents) {
+    const args = ['-p', spec.brief, '--output-format', 'json', '--json-schema', JSON.stringify(spec.schema), '--model', spec.model];
+    if (spec.agent) {
+        if (!agents[spec.agent])
+            throw new RafError(`agent introuvable dans le paquet : ${spec.agent}`);
+        args.push('--agents', JSON.stringify(agents), '--agent', spec.agent);
+    }
+    args.push('--session-id', spec.sessionId, '--permission-mode', spec.permissionMode);
+    for (const d of spec.addDirs)
+        args.push('--add-dir', d);
+    args.push('--disallowedTools', ...DISALLOWED);
+    return args;
+}
+/** Définitions d'agents du paquet (`agents/*.md`) au format de --agents. */
+export function readAgents(dir) {
+    const out = {};
+    if (!existsSync(dir))
+        return out;
+    for (const f of readdirSync(dir).filter((n) => n.endsWith('.md'))) {
+        const text = readFileSync(join(dir, f), 'utf8');
+        const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+        if (!m)
+            continue;
+        const meta = parse(m[1]);
+        if (!meta?.name || !meta.description)
+            continue;
+        out[meta.name] = {
+            description: meta.description,
+            prompt: m[2].trim(),
+            // Outils restreints : StructuredOutput ajouté, sinon --json-schema reste sans effet (la session finit en texte).
+            ...(meta.tools ? { tools: [...String(meta.tools).split(',').map((t) => t.trim()).filter(Boolean), 'StructuredOutput'] } : {}),
+        };
+    }
+    return out;
+}
+/** Consigne de la relance de mise en forme : rendre le rapport déjà établi au format demandé, rien d'autre. */
+export const FORMAT_RETRY_PROMPT = 'Return your report now in the required format (the JSON structure of the schema), exactly as you concluded it. Do not do any further work, do not add anything else.';
+/** Arguments de la relance : même session (--resume), mêmes schéma, modèle, agent (outils restreints), mode de permission, dossiers et interdits. */
+export function buildRetryArgs(spec, sessionId, agents) {
+    const args = ['-p', FORMAT_RETRY_PROMPT, '--output-format', 'json', '--json-schema', JSON.stringify(spec.schema), '--model', spec.model];
+    if (spec.agent) {
+        if (!agents[spec.agent])
+            throw new RafError(`agent introuvable dans le paquet : ${spec.agent}`);
+        args.push('--agents', JSON.stringify(agents), '--agent', spec.agent);
+    }
+    args.push('--resume', sessionId, '--permission-mode', spec.permissionMode);
+    for (const d of spec.addDirs)
+        args.push('--add-dir', d);
+    args.push('--disallowedTools', ...DISALLOWED);
+    return args;
+}
+/**
+ * Lance une session et range son issue : ok, quota atteint, ou échec nommé (jamais de nouvel essai ici), à une
+ * exception près : une session réussie qui finit en texte sans `structured_output` est relancée UNE fois, par
+ * `--resume` de la même session, pour qu'elle rende son rapport au format demandé. Les jetons de la relance
+ * s'ajoutent à ceux de la session ; toujours rien après elle, c'est l'échec habituel.
+ */
+export async function runSession(spec, deps) {
+    const launch = (args) => deps.claude(args, { cwd: spec.cwd, env: { CADENCE_ORCHESTRATED: spec.wave }, timeoutMs: spec.timeoutMs, onSpawn: deps.onSpawn });
+    const out = await launch(buildArgs(spec, deps.agents));
+    const first = classify(out);
+    const missing = first.kind === 'failed' && !out.timedOut && out.code === 0 ? lacksStructuredOutput(out.stdout) : null;
+    if (!missing)
+        return first;
+    const spentFirst = first.kind === 'failed' ? first.tokens : undefined;
+    const second = classify(await launch(buildRetryArgs(spec, missing.sessionId, deps.agents)));
+    const total = (t) => (spentFirst && t ? sumTokens(spentFirst, t) : (t ?? spentFirst));
+    if (second.kind === 'ok')
+        return { kind: 'ok', result: { ...second.result, tokens: total(second.result.tokens), formattingRetry: true }, firstStdout: out.stdout };
+    const tokens = total(second.tokens);
+    return { ...second, firstStdout: out.stdout, ...(tokens ? { tokens } : {}), sessionId: second.sessionId ?? missing.sessionId };
+}
+function classify(out) {
+    // Une session en échec a consommé des tokens : ceux de sa sortie, quand elle en donne, vont au budget.
+    const salvaged = salvageUsage(out.stdout);
+    const spent = salvaged ? { tokens: salvaged.tokens, sessionId: salvaged.sessionId } : {};
+    const failed = (cause) => ({ kind: 'failed', cause, stdout: out.stdout, stderr: out.stderr, ...spent });
+    if (out.timedOut)
+        return failed('délai dépassé');
+    let result;
+    try {
+        result = parseSession(out.stdout, { structured: true });
+    }
+    catch (e) {
+        // Une session arrêtée par le quota peut sortir sans structure : le message reste lisible dans stdout. Une session
+        // RÉUSSIE sans structure n'est jamais un quota, même si son texte en parle (une revue du code de quota) : relance.
+        if (!lacksStructuredOutput(out.stdout) && isQuotaMessage(out.stdout))
+            return { kind: 'quota', message: out.stdout.trim().slice(0, 300), ...spent };
+        return failed(out.code !== 0 ? `code ${out.code} — ${e.message}` : e.message);
+    }
+    if (result.isError) {
+        if (isQuotaMessage(result.result))
+            return { kind: 'quota', message: result.result, result, ...spent };
+        return failed(`${result.subtype || 'erreur'} : ${result.result.slice(0, 300)}${out.code !== 0 ? ` (code ${out.code})` : ''}`);
+    }
+    if (out.code !== 0)
+        return failed(`code ${out.code}`);
+    return { kind: 'ok', result };
+}
+const live = new Set();
+/** Suit un groupe de processus lancé par l'orchestrateur (commande du projet) : tué avec les sessions au signal. */
+export function trackGroup(pid) {
+    live.add(pid);
+    return () => live.delete(pid);
+}
+/** Tue les groupes de processus des sessions en cours (Ctrl-C, SIGTERM de l'orchestrateur). */
+export function killSessions() {
+    for (const pid of live) {
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch {
+            // déjà mort
+        }
+    }
+    live.clear();
+}
+/** Vrai lanceur : `claude` (ou CADENCE_CLAUDE_BIN) dans son propre groupe de processus, tué en bloc au délai. */
+export function realClaude(bin, base = process.env) {
+    return (args, opts) => new Promise((resolve) => {
+        const child = spawn(bin, args, { cwd: opts.cwd, env: { ...base, ...opts.env }, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+        const pid = child.pid;
+        if (pid === undefined) {
+            child.once('error', (e) => resolve({ code: 127, stdout: '', stderr: String(e.message), timedOut: false }));
+            return;
+        }
+        live.add(pid);
+        opts.onSpawn?.(pid);
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (d) => out.push(d));
+        child.stderr.on('data', (d) => err.push(d));
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                process.kill(-pid, 'SIGKILL');
+            }
+            catch {
+                // déjà mort
+            }
+        }, Math.max(1_000, opts.timeoutMs));
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            live.delete(pid);
+            // Un enfant resté dans le groupe ne survit pas à la session.
+            try {
+                process.kill(-pid, 'SIGKILL');
+            }
+            catch {
+                // groupe vide
+            }
+            resolve({ code: code ?? (signal ? 137 : 1), stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'), timedOut });
+        });
+    });
+}
+/** Dossier des journaux de sessions d'un répertoire : `<home>/projects/<chemin aplati>`. */
+export function projectLogDir(claudeHome, cwd) {
+    return join(claudeHome, 'projects', cwd.replace(/[^a-zA-Z0-9]/g, '-'));
+}
+/** Pic de contexte d'une session relu dans son journal (entrée + écriture + lecture de cache d'un tour) ; null si absent. */
+export function peakContext(claudeHome, cwd, sessionId) {
+    const file = join(projectLogDir(claudeHome, cwd), `${sessionId}.jsonl`);
+    if (!existsSync(file))
+        return null;
+    let peak = 0;
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try {
+            const u = JSON.parse(line)?.message?.usage;
+            if (!u)
+                continue;
+            const n = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
+            if (n > peak)
+                peak = n;
+        }
+        catch {
+            // ligne partielle
+        }
+    }
+    return peak;
+}
+/**
+ * Consommation d'une session relue dans son journal, par son identifiant (`--session-id`) : somme des tours (un
+ * message écrit sur plusieurs lignes n'est compté qu'une fois). Une session tuée (délai, signal) n'a rien rendu sur
+ * sa sortie. Jamais de session devinée par date : un autre journal du même dossier n'est pas le sien. Null si rien n'est lisible.
+ */
+export function journalTokens(claudeHome, cwd, sessionId) {
+    const dir = projectLogDir(claudeHome, cwd);
+    const id = sessionId;
+    const file = join(dir, `${id}.jsonl`);
+    if (!existsSync(file))
+        return null;
+    const byMessage = new Map();
+    let anon = 0;
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try {
+            const m = JSON.parse(line)?.message;
+            const u = m?.usage;
+            if (!u)
+                continue;
+            byMessage.set(typeof m.id === 'string' ? m.id : `anon-${anon++}`, [u.input_tokens ?? 0, u.cache_creation_input_tokens ?? 0, u.cache_read_input_tokens ?? 0, u.output_tokens ?? 0]);
+        }
+        catch {
+            // ligne partielle
+        }
+    }
+    if (byMessage.size === 0)
+        return null;
+    const sum = [0, 0, 0, 0];
+    for (const v of byMessage.values())
+        v.forEach((n, i) => (sum[i] += n));
+    return { tokens: tokensOf(sum[0], sum[1], sum[2], sum[3]), sessionId: id };
+}

package/dist/orchestrate/lock.js

@@ -0,0 +1,85 @@
+import { linkSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pidAlive } from '../state.js';
+/** Nom du verrou d'orchestration d'un dépôt, dans l'état commun aux worktrees (celui de `deliver`). */
+export const REPO_LOCK = 'orchestrate.lock';
+function read(file) {
+    let text;
+    let ageMs;
+    try {
+        ageMs = Date.now() - statSync(file).mtimeMs;
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(text);
+        return { pid: Number(raw.pid), wave: String(raw.wave), started: String(raw.started), ageMs };
+    }
+    catch {
+        return { pid: 0, wave: '?', started: '?', unreadable: true, ageMs };
+    }
+}
+const alive = (l) => (l.unreadable ? l.ageMs < 5_000 : pidAlive(l.pid));
+/** Le verrou s'il est tenu par un processus vivant, sinon null (absent ou périmé). */
+export function activeLock(file) {
+    const l = read(file);
+    return l && alive(l) ? l : null;
+}
+/**
+ * Pose le verrou (lien vers un fichier complet : atomique). Un verrou de pid mort est retiré — `stale` le
+ * dit pour avertir. `held` : le porteur vivant quand la pose échoue.
+ */
+export function takeLock(file, lock) {
+    let stale;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const tmp = join(dirname(file), `.orchestrate.lock.${lock.pid}.${Date.now()}.${attempt}.tmp`);
+        writeFileSync(tmp, JSON.stringify(lock));
+        try {
+            linkSync(tmp, file);
+            return stale ? { ok: true, stale } : { ok: true };
+        }
+        catch {
+            // déjà là
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
+        const seen = read(file);
+        if (!seen)
+            continue;
+        if (alive(seen))
+            return { ok: false, held: seen };
+        // périmé : l'écarter seulement s'il est encore celui qu'on a lu
+        const aside = `${file}.stale.${process.pid}`;
+        try {
+            renameSync(file, aside);
+        }
+        catch {
+            continue;
+        }
+        const now = read(aside);
+        if (now && now.pid === seen.pid && now.wave === seen.wave && now.started === seen.started) {
+            stale = { pid: seen.pid, wave: seen.wave, started: seen.started };
+            rmSync(aside, { force: true });
+        }
+        else {
+            try {
+                linkSync(aside, file);
+            }
+            catch {
+                // repris par un tiers
+            }
+            rmSync(aside, { force: true });
+        }
+    }
+    const held = read(file);
+    return { ok: false, held: held ?? lock };
+}
+/** Retire le verrou s'il appartient à ce pid. */
+export function releaseLock(file, pid) {
+    const l = read(file);
+    if (l && l.pid === pid)
+        rmSync(file, { force: true });
+}

package/dist/orchestrate/pool.js

@@ -0,0 +1,51 @@
+import { runLot } from './cycle.js';
+import { lotKey } from './state.js';
+/** Deux sessions au plus en même temps (imposé ici, pas de --parallel) : deux dépôts à la fois. */
+export const SLOTS = 2;
+/**
+ * Ordonnanceur : une file par dépôt, les lots d'un dépôt l'un après l'autre dans l'ordre donné, deux dépôts
+ * au plus en parallèle. Le budget, le quota et les incidents sont vérifiés par le cycle avant chaque session.
+ */
+export async function runPool(ctxs, slots = SLOTS, known = []) {
+    const queues = new Map();
+    for (const c of ctxs)
+        queues.set(c.lot.repo, [...(queues.get(c.lot.repo) ?? []), c]);
+    const pending = [...queues.values()];
+    const worker = async () => {
+        for (let queue = pending.shift(); queue; queue = pending.shift()) {
+            // Un lot en attente est revisité tant qu'un tour de la file en fait avancer un autre (sa dépendance peut venir après lui).
+            for (let todo = queue, progress = true; todo.length && progress;) {
+                const waiting = [];
+                progress = false;
+                for (const c of todo) {
+                    const state = (id) => [...ctxs.map((o) => o.lot), ...known].find((o) => o.project === c.lot.project && o.lot === id)?.status;
+                    const missing = (c.lot.dependsOn ?? []).filter((id) => state(id) !== 'ready');
+                    if (missing.length && c.lot.steps.length === 0 && (c.lot.status === 'queued' || c.lot.status === 'suspended')) {
+                        // Une dépendance suspendue, en question ou pas encore jouée (reprise) : le lot attend, il reste reprenable.
+                        // Seule une dépendance rendue au lead ou en échec le rend aussi.
+                        const dead = missing.filter((id) => ['handed-back', 'failed'].includes(state(id) ?? 'failed'));
+                        if (dead.length === 0) {
+                            c.lot.outcome = `en attente de : ${missing.join(', ')}`;
+                            c.wave.store.writeLot(c.lot);
+                            c.wave.log(`${lotKey(c.lot.project, c.lot.lot)} — ${c.lot.outcome}`);
+                            waiting.push(c);
+                            continue;
+                        }
+                        c.lot.status = 'handed-back';
+                        c.lot.outcome = `dépendance non prête dans la vague : ${missing.join(', ')}`;
+                        c.wave.store.writeLot(c.lot);
+                        c.wave.log(`${lotKey(c.lot.project, c.lot.lot)} → handed-back — ${c.lot.outcome}`);
+                        progress = true;
+                        continue;
+                    }
+                    if (c.lot.outcome?.startsWith('en attente de : '))
+                        c.lot.outcome = null;
+                    progress = true;
+                    await runLot(c);
+                }
+                todo = waiting;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(slots, pending.length) }, worker));
+}

package/dist/orchestrate/result.js

@@ -0,0 +1,94 @@
+import { RafError } from '../plan.js';
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function field(obj, path, kind) {
+    let cur = obj;
+    for (const k of path.split('.')) {
+        if (!isObject(cur) || !(k in cur))
+            throw new RafError(`sortie de claude : champ « ${path} » absent`);
+        cur = cur[k];
+    }
+    if (typeof cur !== kind)
+        throw new RafError(`sortie de claude : champ « ${path} » de type ${typeof cur} (attendu ${kind})`);
+    return cur;
+}
+/**
+ * Lit la sortie `claude -p --output-format json` (un objet unique). Les noms de champs sont ceux d'un
+ * échantillon réel (test/fixtures/claude-result.sample.json) : un champ absent est une erreur nommée,
+ * jamais un zéro. `structured` : la sortie de --json-schema est attendue (sauf quand la session a échoué).
+ */
+export function parseSession(stdout, opts) {
+    if (stdout.trim() === '')
+        throw new RafError('sortie de claude vide');
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        throw new RafError('sortie de claude illisible (JSON attendu)');
+    }
+    if (!isObject(raw))
+        throw new RafError('sortie de claude illisible (objet attendu)');
+    const isError = field(raw, 'is_error', 'boolean');
+    const input = field(raw, 'usage.input_tokens', 'number');
+    const cacheWrite = field(raw, 'usage.cache_creation_input_tokens', 'number');
+    const cacheRead = field(raw, 'usage.cache_read_input_tokens', 'number');
+    const output = field(raw, 'usage.output_tokens', 'number');
+    const result = {
+        isError,
+        subtype: field(raw, 'subtype', 'string'),
+        result: typeof raw.result === 'string' ? raw.result : '',
+        sessionId: field(raw, 'session_id', 'string'),
+        numTurns: field(raw, 'num_turns', 'number'),
+        durationMs: field(raw, 'duration_ms', 'number'),
+        tokens: { input, cacheWrite, cacheRead, output, counted: input + cacheWrite + output },
+    };
+    if (!isError && opts.structured) {
+        if (!('structured_output' in raw))
+            throw new RafError('sortie de claude : champ « structured_output » absent (--json-schema ignoré ?)');
+        result.structured = raw.structured_output;
+    }
+    return result;
+}
+/** Le message d'une session arrêtée par la limite d'usage (quota) ; l'heure de remise suit « | » quand elle est donnée. */
+export function isQuotaMessage(text) {
+    return /usage limit|limit reached|rate limit|quota/i.test(text);
+}
+/** Heure de remise (epoch s) lue dans « …limit reached|1759600000 », sinon null. */
+export function quotaReset(text) {
+    const m = /\|(\d{9,})\s*$/.exec(text.trim());
+    return m ? new Date(Number(m[1]) * 1000) : null;
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0);
+export const tokensOf = (input, cacheWrite, cacheRead, output) => ({ input, cacheWrite, cacheRead, output, counted: input + cacheWrite + output });
+/**
+ * Consommation lue sans rien exiger : une session en échec (is_error, code ≠ 0, sortie incomplète) a quand même
+ * consommé des tokens, que le budget doit compter. Null quand la sortie n'a aucun `usage` lisible.
+ */
+export function salvageUsage(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(raw) || !isObject(raw.usage))
+        return null;
+    const u = raw.usage;
+    const tokens = tokensOf(num(u.input_tokens), num(u.cache_creation_input_tokens), num(u.cache_read_input_tokens), num(u.output_tokens));
+    return { tokens, sessionId: typeof raw.session_id === 'string' ? raw.session_id : undefined };
+}
+/** Session réussie (pas d'erreur, `success`) qui a fini en texte sans `structured_output` : seul cas d'une relance de mise en forme. */
+export function lacksStructuredOutput(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(raw) || raw.is_error !== false || raw.subtype !== 'success' || 'structured_output' in raw)
+        return null;
+    return typeof raw.session_id === 'string' && raw.session_id ? { sessionId: raw.session_id } : null;
+}
+export const sumTokens = (a, b) => tokensOf(a.input + b.input, a.cacheWrite + b.cacheWrite, a.cacheRead + b.cacheRead, a.output + b.output);

package/dist/orchestrate/schemas.js

@@ -0,0 +1,48 @@
+const str = { type: 'string' };
+const num = { type: 'number' };
+const strings = { type: 'array', items: str };
+const result = { type: 'object', properties: { commande: str, resultat: str, vert: { type: 'boolean' } }, required: ['commande', 'resultat', 'vert'] };
+/** Sortie d'une implémentation ou d'une correction. */
+export const WORK_SCHEMA = {
+    type: 'object',
+    properties: {
+        commits: { type: 'array', items: { type: 'object', properties: { sha: str, sujet: str }, required: ['sha', 'sujet'] } },
+        tests: result,
+        build: result,
+        nonVerifie: strings,
+        questions: strings,
+        choix: strings,
+        resume: str,
+    },
+    required: ['commits', 'tests', 'build', 'nonVerifie', 'questions', 'resume'],
+};
+/** Sortie d'une revue (code, UX ou passe unique) : `verdict` est la ligne pour `raf review` / `raf ux`. */
+export const REVIEW_SCHEMA = {
+    type: 'object',
+    properties: {
+        bloquants: num,
+        majeurs: num,
+        mineurs: num,
+        constats: { type: 'array', items: { type: 'object', properties: { gravite: { type: 'string', enum: ['bloquant', 'majeur', 'mineur'] }, fichier: str, ligne: num, texte: str }, required: ['gravite', 'texte'] } },
+        sousTaches: strings,
+        nonVerifie: strings,
+        verdict: str,
+    },
+    required: ['bloquants', 'majeurs', 'mineurs', 'constats', 'sousTaches', 'nonVerifie', 'verdict'],
+};
+export const schemaFor = (kind) => (kind === 'implement' || kind === 'fix' ? WORK_SCHEMA : REVIEW_SCHEMA);
+/** Contrôle la forme d'une sortie structurée : un champ absent ou mal typé est une erreur nommée. */
+export function checkShape(value, schema) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('sortie structurée : objet attendu');
+    const o = value;
+    for (const k of schema.required) {
+        if (!(k in o))
+            throw new Error(`sortie structurée : champ « ${k} » absent`);
+        const want = schema.properties[k].type;
+        const ok = want === 'array' ? Array.isArray(o[k]) : typeof o[k] === want;
+        if (!ok)
+            throw new Error(`sortie structurée : champ « ${k} » mal typé (attendu ${want})`);
+    }
+    return value;
+}