@sylad/cadence 1.8.0 → 1.10.0

package/dist/orchestrate/table.js

@@ -1,10 +1,11 @@
 import { lotWork } from '../audit.js';
 import { planLoader } from '../config.js';
-import { isAncestor } from '../git.js';
+import { gitRoot, isAncestor } from '../git.js';
+import { repoWork } from '../repos.js';
 import { quotaReset } from './result.js';
 const k = (n) => `${Math.round(n / 1000)} k`;
 const m = (n) => `${(n / 1_000_000).toFixed(1).replace('.', ',')} M`;
-const LABEL = {
+export const LABEL = {
     queued: 'en attente',
     implementing: 'implémentation',
     reviewing: 'revue',
@@ -93,8 +94,76 @@ function deliverable(lots, ancestor, fromGit) {
     }
     return out;
 }
+/**
+ * Sha abrégés des commits de `l` dans `repo` que git lui attribue — dans le dépôt de son projet (commits qui citent le lot) ou, quand `repo` est
+ * l'un de ses dépôts voisins (clé `repos:`, L62), dans ce voisin (`repoWork` : commits qui citent le lot, dans sa période, et sa chaîne `cite:`).
+ * Contrairement à `gitCommitsOf`, une lecture impossible LÈVE : plan du projet illisible ou qui ne connaît pas le lot, dépôt qui n'est plus un dépôt
+ * git. « Aucun commit » et « commits illisibles » ne se confondent pas ici : la garde de `deliver --sha` refuse le second.
+ */
+export function gitCommitsIn(l, repo) {
+    const plan = planLoader(l.repo)();
+    if (!plan.lots().some((x) => x.id === l.lot))
+        throw new Error(`le plan de ${l.repo} ne connaît pas le lot ${l.lot}`);
+    const neighbour = l.repo === repo ? undefined : (l.repos ?? []).find((r) => r.path === repo);
+    const where = neighbour ? neighbour.path : l.repo;
+    if (!gitRoot(where))
+        throw new Error(`${where} n'est pas un dépôt git`);
+    const work = neighbour ? repoWork(plan, neighbour, l.lot) : lotWork(plan, l.repo, l.lot);
+    return work.map((c) => c.sha.slice(0, 7)).reverse();
+}
+/** Sha des commits que les étapes de `l` ont notés dans `repo` : entrées `<sha> <sujet>` pour son dépôt, `[rel] <sha> <sujet>` pour un voisin. */
+function stepCommits(l, repo) {
+    const entries = l.steps.flatMap((s) => s.commits ?? []);
+    const prefixes = l.repo === repo ? [] : (l.repos ?? []).filter((r) => r.path === repo).map((r) => `[${r.rel}] `);
+    if (prefixes.length === 0)
+        return entries.filter((c) => !c.startsWith('[')).map((c) => c.split(' ')[0]);
+    return entries.flatMap((c) => prefixes.filter((p) => c.startsWith(p)).map((p) => c.slice(p.length).split(' ')[0]));
+}
+/**
+ * Livrer au fil de l'eau (L277) : les lots de la vague qui empêchent de livrer `sha` dans `repo` — ceux qui ne sont pas prêts (en cours, en file,
+ * en question, suspendus, rendus, échoués) et dont un commit est dans l'histoire de `sha`. `blocking` vide ET `unreadable` vide : tous les commits de
+ * `sha` qui citent un lot de la vague citent des lots prêts, revus (« prêt » est l'état d'un lot dont la revue est conforme) ; `sha` est
+ * « livrable jusqu'à » de la vague. Un lot sans commit ne bloque rien.
+ *
+ * Les commits d'un lot pas prêt sont l'union de ce que git lui attribue (`read`) et de ce que ses étapes ont noté : les entrées d'étape ne sont
+ * écrites qu'à la fin d'une session au rapport valide, git voit tout de suite le commit d'une session en cours, coupée par le quota ou échouée,
+ * dans son dépôt comme dans un voisin. Un lot dont les commits n'ont pu être lus (`read` lève) et dont aucun commit déjà connu ne bloque est
+ * `unreadable` : on ne laisse passer que ce qu'on a pu vérifier.
+ */
+export function blockingLots(lots, repo, sha, ancestor = isAncestor, read = gitCommitsIn) {
+    const guard = { blocking: [], unreadable: [] };
+    for (const l of lots) {
+        if (l.status === 'ready')
+            continue;
+        let found = [];
+        let readable = true;
+        try {
+            found = read(l, repo);
+        }
+        catch {
+            readable = false;
+        }
+        if ([...found, ...stepCommits(l, repo)].some((c) => ancestor(repo, c, sha)))
+            guard.blocking.push(l);
+        else if (!readable)
+            guard.unreadable.push(l);
+    }
+    return guard;
+}
 /** Tests déjà rouges au départ listés un par un dans le tableau ; au-delà, un compte. */
 const BASELINE_LISTED = 30;
+/**
+ * La commande de reprise d'une vague, SEULE forme que le programme imprime (L309) : `--resume --wave <id>` et non `--resume <id>`, car un id qui ressemble à un lot
+ * (`suite2`) est lu comme un lot à lancer sans `--wave` (et refusé), et `--resume` sans vague est refusé dès que le dossier en garde plusieurs non terminées.
+ * `extra` : les options qui suivent (`--drop a:L1`, `--integrate a:L1`...).
+ */
+export function resumeCommand(waveId, ...extra) {
+    return ['cadence orchestrate --resume --wave', waveId, ...extra].join(' ');
+}
+/** La commande qui répond à une question (L309) : la reprise ci-dessus, avec `--answer`. */
+export function resumeAnswerHint(waveId, l) {
+    return resumeCommand(waveId, '--answer', `${l.project}:${l.lot}`, '"…"');
+}
 /** Le tableau de fin de vague (ou de `--status`), une ligne par lot puis le total et les questions. */
 export function renderTable(wave, lots, deps = {}) {
     const rows = lots.map((l) => [`${l.project}:${l.lot}`, LABEL[l.status], String(l.pass), review(l), ux(l), String(commits(l)), k(counted(l)), `${minutes(l)} min`]);
@@ -106,7 +175,7 @@ export function renderTable(wave, lots, deps = {}) {
     const tail = [`${by('ready')} prêt(s)`, by('question') ? `${by('question')} question(s)` : '', by('handed-back') + by('failed') ? `${by('handed-back') + by('failed')} rendu(s) au lead` : '', by('suspended') ? `${by('suspended')} suspendu(s)` : ''].filter(Boolean);
     out.push(`vague ${wave.id} : ${k(wave.consumed)} / ${m(wave.budget)} comptés (lecture de cache ${m(wave.cacheRead)}) — ${tail.join(', ')} — ${wave.status}`);
     for (const l of lots.filter((x) => x.status === 'question')) {
-        out.push(`question : ${l.project}:${l.lot} — « ${l.questions.join(' / ')} » (cadence orchestrate --resume --answer ${l.project}:${l.lot} "…")`);
+        out.push(`question : ${l.project}:${l.lot} — « ${l.questions.join(' / ')} » (${resumeAnswerHint(wave.id, l)})`);
     }
     for (const l of lots.filter((x) => x.status === 'handed-back' || x.status === 'failed' || x.status === 'suspended')) {
         out.push(`${l.project}:${l.lot} — ${l.outcome ?? LABEL[l.status]}`);
@@ -117,6 +186,8 @@ export function renderTable(wave, lots, deps = {}) {
         out.push(`${d.ready.project}:${d.ready.lot} — livrable jusqu'à ${d.sha} (dernier commit de ${d.ready.lot}, sous ${d.under.lot} ${d.under.status === 'handed-back' || d.under.status === 'failed' ? 'rendu' : LABEL[d.under.status]}) : git push origin ${d.sha}:main && cadence deliver --sha ${d.sha}`);
     }
     for (const l of lots) {
+        if (l.goal)
+            out.push(`${l.project}:${l.lot} — objectif donné : ${l.goal}`);
         if (l.uxNote)
             out.push(`${l.project}:${l.lot} — ${l.uxNote}`);
         if (l.uxCaptures)

package/dist/orchestrate/timeouts.js

@@ -0,0 +1,40 @@
+/** Estimate (en jours) que le délai de base `timeouts.work` couvre : un lot jusqu'à un quart de jour. */
+export const BASE_ESTIMATE = 0.25;
+/** Majoration d'un lot à fiche (étape spec, écran ou `spec: true`) : la session lit la fiche et écrit un test par règle. */
+export const FICHE_FACTOR = 1.5;
+/** Plafond du délai proportionné, en multiples du délai de base. */
+export const MAX_FACTOR = 4;
+/** Prolongation accordée à chaque échéance où la session a commité depuis la dernière. */
+export const EXTENSION_MS = 15 * 60_000;
+/** Nombre de prolongations au plus : 2 h de plus après le délai proportionné, la session qui commite sans fin finit par être coupée. */
+export const MAX_EXTENSIONS = 8;
+/**
+ * Délai d'une étape d'écriture (L298) : le délai configuré (`timeouts.implement`, 45 min par défaut) vaut pour un lot de 0,25 j ;
+ * il croît avec l'estimate (0,5 j : le double), d'un tiers en plus de moitié pour un lot à fiche, sans dépasser 4 fois le délai de base.
+ */
+export function workTimeoutMs(baseMs, estimate, fiche) {
+    const scale = Math.max(1, (estimate ?? BASE_ESTIMATE) / BASE_ESTIMATE) * (fiche ? FICHE_FACTOR : 1);
+    return Math.round(Math.min(scale, MAX_FACTOR) * baseMs);
+}
+const isTest = (f) => /(^|\/)(tests?|__tests__)\//.test(f) || /\.(test|spec)\.[a-z]+$/.test(f);
+/** Fichiers listés au plus dans le message : au-delà, le nombre seul. */
+const LISTED = 8;
+/**
+ * Phrase du tableau pour une étape d'écriture coupée à l'échéance (L298) : commits conservés, travail NON commité
+ * (fichiers, dont les tests, lignes). `numstat` : sortie de `git diff --numstat HEAD` ; les fichiers non suivis n'y ont pas de lignes.
+ */
+export function cutReport(o) {
+    const lines = o.numstat
+        .split('\n')
+        .map((l) => l.split('\t'))
+        .filter((p) => p.length >= 3)
+        .reduce((n, p) => n + (Number(p[0]) || 0), 0);
+    const kept = o.commits === 0 ? 'aucun commit' : `${o.commits} commit${o.commits > 1 ? 's' : ''} conservé${o.commits > 1 ? 's' : ''}`;
+    const head = `coupé au délai de ${o.minutes} min : ${kept}`;
+    if (o.files.length === 0)
+        return `${head}, rien de non commité`;
+    const tests = o.files.filter(isTest);
+    const names = o.files.length > LISTED ? `${o.files.slice(0, LISTED).join(', ')}, …` : o.files.join(', ');
+    const t = tests.length ? `, dont ${tests.length} de test (${tests.length > LISTED ? `${tests.slice(0, LISTED).join(', ')}, …` : tests.join(', ')})` : ', aucun de test';
+    return `${head} ; travail NON commité : ${o.files.length} fichier${o.files.length > 1 ? 's' : ''} (${names})${t}${lines ? `, ${lines} lignes ajoutées` : ''} — laissé dans le dépôt, à commiter ou à reprendre par le lead`;
+}

package/dist/orchestrate/worktree.js

@@ -0,0 +1,368 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, rmSync, symlinkSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { lotSlug } from './state.js';
+import { cadenceHome, liveWaves } from './registry.js';
+/** Un worktree par lot (L279) : nom du dossier de la vague où ils vivent, hors du dépôt du lead. */
+export const WORKTREES_DIR = 'worktrees';
+/** Dossiers ignorés de sortie de build : jamais liés dans un worktree, une commande de tests qui y écrit toucherait le build du dépôt vivant. */
+const OUTPUT_DIRS = new Set(['dist', 'build', 'out', 'coverage', 'target', '.next', '.nuxt', '.output', '.angular', '.turbo', '.svelte-kit', '.parcel-cache']);
+/** Une commande git dans `cwd`, sa sortie sans les blancs de bord ; lève si elle échoue. Commune à l'orchestration (worktrees, intégration, cycle). */
+export function git(cwd, ...args) {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+/** Le message d'une commande git qui a échoué : sa sortie d'erreur (sur une ligne), à défaut le message de l'exception. */
+export function gitFailure(e) {
+    const err = e.stderr;
+    const text = typeof err === 'string' && err.trim() ? err : e instanceof Error ? e.message : String(e);
+    return text.trim().replace(/\s*\n\s*/g, ' ');
+}
+/** Comme `git`, null quand la commande échoue. */
+export const tryGit = (cwd, ...args) => {
+    try {
+        return git(cwd, ...args);
+    }
+    catch {
+        return null;
+    }
+};
+/** Branche du lot : `cadence/<vague>/<projet>--<lot>` (R14), le même nom à la reprise. Le projet d'une vague lancée à la racine du dépôt s'appelle `.` : git refuse un composant de branche qui commence par un point, il devient `_`. */
+export const lotBranch = (wave, project, lot) => `cadence/${wave}/${lotSlug(project, lot).replace(/^\./, '_')}`;
+/**
+ * Dossier du worktree du lot : sous le dossier de la vague (R14). Une vague lancée depuis la racine du dépôt a son dossier DANS le dépôt : le worktree
+ * irait alors sous son arbre ; avec `repo`, il part sous le dossier des worktrees de cadence (`<CADENCE_HOME>/worktrees/<vague>-<empreinte du dossier>/`), hors du dépôt.
+ */
+export function lotTreeDir(waveDir, project, lot, repo) {
+    const slug = lotSlug(project, lot);
+    if (repo && withinRepo(repo, waveDir))
+        return join(cadenceHome(), WORKTREES_DIR, `${basename(waveDir)}-${createHash('sha1').update(realOrSelf(waveDir)).digest('hex').slice(0, 8)}`, slug);
+    return join(waveDir, WORKTREES_DIR, slug);
+}
+const realOrSelf = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+};
+const withinRepo = (repo, path) => {
+    const rel = relative(realOrSelf(repo), realOrSelf(path));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+const config = (repo, branch, key) => tryGit(repo, 'config', '--local', '--get', `branch.${branch}.cadence-${key}`) || null;
+/** La branche de départ du lot, notée dans la config git de sa branche à la création ; null si la branche n'est pas celle d'un worktree de cadence. */
+export const baseBranchOf = (repo, branch) => config(repo, branch, 'base');
+/** La branche existe dans le dépôt (marquée ou non comme worktree de cadence). */
+export const branchExists = (repo, branch) => branchSha(repo, branch) !== null;
+const branchSha = (repo, branch) => tryGit(repo, 'rev-parse', '--verify', '-q', `refs/heads/${branch}^{commit}`);
+/** Les worktrees enregistrés par git : chemin → branche (null en HEAD détaché). */
+function registered(repo) {
+    const out = new Map();
+    const text = tryGit(repo, 'worktree', 'list', '--porcelain') ?? '';
+    for (const block of text.split(/\n\s*\n/)) {
+        const path = /^worktree (.+)$/m.exec(block)?.[1];
+        if (!path)
+            continue;
+        out.set(path, /^branch refs\/heads\/(.+)$/m.exec(block)?.[1] ?? null);
+    }
+    return out;
+}
+/**
+ * Un `node_modules` dans un worktree : un vrai dossier dont chaque entrée est un lien vers celle du dépôt vivant, SAUF les liens
+ * de workspace (npm, pnpm, yarn : `node_modules/@x/shared -> ../../packages/shared`) qui pointent vers du code du dépôt hors de tout
+ * `node_modules`. Lier le dossier d'un bloc les ferait résoudre dans le dépôt vivant, donc exécuter le code du lot au lieu de celui du worktree ;
+ * ils sont refaits vers la copie du worktree (absente au sha de départ : pas de lien). Les dossiers de portée `@x` sont parcourus,
+ * pas les paquets. Ajoute chaque lien créé à `links`.
+ */
+export function mirrorNodeModules(repo, dir, name, links) {
+    const repoReal = realpathSync(repo);
+    const workspaceCopy = (live) => {
+        let real;
+        try {
+            real = realpathSync(live);
+        }
+        catch {
+            return null; // lien mort dans le dépôt vivant : rien à refaire
+        }
+        const rel = relative(repoReal, real);
+        if (!rel || rel.startsWith('..') || isAbsolute(rel) || rel.split(sep).includes('node_modules'))
+            return null;
+        return join(dir, rel);
+    };
+    const link = (target, at) => {
+        symlinkSync(target, at);
+        links.push(at);
+    };
+    const mirror = (liveDir, to, scope) => {
+        mkdirSync(to);
+        for (const e of readdirSync(liveDir, { withFileTypes: true })) {
+            const live = join(liveDir, e.name);
+            const at = join(to, e.name);
+            if (e.isSymbolicLink()) {
+                const copy = workspaceCopy(live);
+                if (copy) {
+                    if (existsSync(copy))
+                        link(copy, at);
+                    continue;
+                }
+            }
+            else if (!scope && e.isDirectory() && e.name.startsWith('@')) {
+                mirror(live, at, true);
+                continue;
+            }
+            link(live, at);
+        }
+    };
+    mirror(join(repo, name), join(dir, name), false);
+}
+/**
+ * Relie dans le worktree `dir` les dossiers ignorés du dépôt vivant, de tout niveau (node_modules, .venv… ; `dist` et les autres sorties de
+ * build exclus) pour que les dépendances s'y trouvent. `--directory` ne descend pas dans un dossier ignoré, donc chaque entrée est le dossier ou
+ * fichier ignoré le plus haut ; son parent doit exister dans le worktree (sinon rien où le relier). Rend les liens créés.
+ */
+export function linkIgnored(repo, dir) {
+    const links = [];
+    const ignored = git(repo, 'ls-files', '--others', '--ignored', '--exclude-standard', '--directory').split('\n').map((f) => f.replace(/\/$/, '')).filter((f) => f && !f.startsWith('.cadence') && !f.split('/').some((p) => OUTPUT_DIRS.has(p)));
+    for (const name of ignored) {
+        const to = join(dir, name);
+        if (existsSync(to) || !existsSync(dirname(to)))
+            continue;
+        if (basename(name) === 'node_modules' && lstatSync(join(repo, name)).isDirectory()) {
+            mirrorNodeModules(repo, dir, name, links);
+            continue;
+        }
+        symlinkSync(join(repo, name), to);
+        links.push(to);
+    }
+    return links;
+}
+/**
+ * Crée le worktree du lot sur sa branche propre, ou le retrouve (R11) : branche reconnue (la config git de cadence y est) avec son dossier → rejoué tel quel ;
+ * dossier disparu → élagué et recréé sur la branche existante. Une branche du même nom qui n'est pas la nôtre est refusée sans y toucher (R5).
+ * Un échec ne laisse ni dossier ni branche créés par cet appel.
+ */
+export function prepareTree(t) {
+    const exists = branchSha(t.repo, t.branch) !== null;
+    if (exists && baseBranchOf(t.repo, t.branch) === null)
+        return { ok: false, cause: `la branche ${t.branch} existe déjà et n'est pas un worktree de cadence` };
+    const alive = existsSync(join(t.dir, '.git')) && registered(t.repo).has(t.dir);
+    if (exists && alive) {
+        try {
+            linkIgnored(t.repo, t.dir);
+        }
+        catch {
+            // liens de confort : le worktree repris reste utilisable
+        }
+        return { ok: true, reused: true };
+    }
+    const madeDir = !existsSync(t.dir);
+    try {
+        tryGit(t.repo, 'worktree', 'prune');
+        mkdirSync(dirname(t.dir), { recursive: true });
+        if (exists)
+            git(t.repo, 'worktree', 'add', t.dir, t.branch);
+        else {
+            git(t.repo, 'worktree', 'add', '-b', t.branch, t.dir, t.base);
+            git(t.repo, 'config', '--local', `branch.${t.branch}.cadence-base`, t.base);
+            git(t.repo, 'config', '--local', `branch.${t.branch}.cadence-created`, String(Date.now()));
+            if (t.lot)
+                git(t.repo, 'config', '--local', `branch.${t.branch}.cadence-lot`, t.lot);
+        }
+        linkIgnored(t.repo, t.dir);
+        return { ok: true, reused: exists };
+    }
+    catch (e) {
+        const cause = gitFailure(e);
+        tryGit(t.repo, 'worktree', 'remove', '--force', t.dir);
+        if (madeDir && existsSync(t.dir) && lstatSync(t.dir).isDirectory())
+            rmSync(t.dir, { recursive: true, force: true });
+        tryGit(t.repo, 'worktree', 'prune');
+        if (!exists) {
+            tryGit(t.repo, 'branch', '-D', t.branch);
+            tryGit(t.repo, 'config', '--local', '--remove-section', `branch.${t.branch}`);
+        }
+        return { ok: false, cause };
+    }
+}
+/**
+ * Chemin de reprise d'un lot rendu hors intégration (revue non conforme, tests rouges, HEAD déplacé, plan touché, verrou d'acceptation : sa branche et son
+ * worktree sont conservés) : la nouvelle vague du même lot retrouve la branche `cadence/<vague>/<projet>--<lot>` LA PLUS RÉCENTE (date de création notée par cadence)
+ * d'une vague passée, reconnue, partie de la même branche `base` et qui porte des commits non intégrés. Elle est renommée au nom de la nouvelle vague
+ * (git emporte la config de cadence) et son worktree déplacé vers `dir` : le reste de l'orchestration, qui ne connaît que les noms de la vague, la voit
+ * comme la sienne. Rend la branche reprise, ou null (rien à reprendre). Jamais la branche d'une vague vivante.
+ * Une branche que la reprise ne pourrait pas mener à l'intégration est refusée sans y toucher (`refused` dit pourquoi) : son worktree porte un fichier suivi modifié
+ * (R11 : comme `--resume`, la session n'y démarre pas), ou un de ses commits touche un fichier du plan (`planFiles`, relatifs au dépôt : le plan n'est écrit que par le programme). Un `git worktree move` ou `git branch -m` qui échoue est refusé de même, avec la cause de git (le déplacement est défait).
+ */
+export function recoverTree(repo, branch, dir, base, planFiles = new Set()) {
+    const slug = branch.split('/').slice(2).join('/');
+    const found = keptTrees(repo)
+        .filter((t) => t.branch !== branch && t.branch.split('/').slice(2).join('/') === slug && t.base === base && t.unintegrated > 0)
+        .sort((a, b) => b.created - a.created || (a.branch < b.branch ? 1 : -1))[0];
+    if (!found || branchSha(repo, branch) !== null)
+        return null;
+    tryGit(repo, 'worktree', 'prune');
+    const moved = found.dir !== null && existsSync(found.dir);
+    const dirty = moved && existsSync(join(found.dir, '.git')) ? trackedDirty(found.dir) : [];
+    if (dirty.length)
+        return { from: found.branch, refused: `son worktree porte des fichiers suivis modifiés (${dirty.join(', ')})` };
+    const touched = (tryGit(repo, 'log', '--name-only', '--format=', `refs/heads/${found.branch}`, '--not', `refs/heads/${base}`) ?? '').split('\n').find((f) => planFiles.has(f));
+    if (touched)
+        return { from: found.branch, refused: `un de ses commits modifie le plan (${touched})` };
+    try {
+        if (moved) {
+            mkdirSync(dirname(dir), { recursive: true });
+            git(repo, 'worktree', 'move', found.dir, dir);
+        }
+        git(repo, 'branch', '-m', found.branch, branch);
+    }
+    catch (e) {
+        if (moved && existsSync(dir) && !existsSync(found.dir))
+            tryGit(repo, 'worktree', 'move', dir, found.dir);
+        return { from: found.branch, refused: `déplacement ou renommage de la branche refusé par git (${gitFailure(e)}), rien n'a bougé` };
+    }
+    return { from: found.branch, unintegrated: found.unintegrated };
+}
+/** Les fichiers du plan qu'une session ne doit pas toucher, relatifs au dépôt : le fichier de plan, la page Gantt et ce qui est généré avec (`plan.files`). */
+export function planFileSet(plan, repo) {
+    const rel = relative(repo, plan.path);
+    return new Set([rel, join(dirname(rel), 'gantt.html'), ...plan.files]);
+}
+/** Les commits de la branche du lot déjà dans la branche du dépôt ? */
+export function integrated(repo, branch, base) {
+    return tryGit(repo, 'merge-base', '--is-ancestor', `refs/heads/${branch}`, `refs/heads/${base}`) !== null;
+}
+/** Nombre de commits de la branche du lot qui ne sont pas dans la branche du dépôt. */
+export function unintegratedCommits(repo, branch, base) {
+    return Number(tryGit(repo, 'rev-list', '--count', `refs/heads/${branch}`, '--not', `refs/heads/${base}`) ?? 0);
+}
+/** Fichiers suivis modifiés d'un arbre (`git status --porcelain`, sans les fichiers non suivis). */
+export function trackedDirty(dir) {
+    let out = '';
+    try {
+        // pas de trim : la première colonne d'un `status --porcelain` peut être une espace
+        out = execFileSync('git', ['status', '--porcelain', '--untracked-files=no'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch {
+        // arbre illisible : rien de modifié connu
+    }
+    return out.split('\n').filter(Boolean).map((l) => l.slice(3).replace(/^.* -> /, ''));
+}
+/**
+ * Fichiers non suivis et non ignorés d'un arbre (L279, correctif de revue) : `git worktree remove --force` les supprimerait. Les liens que cadence a posés
+ * (dépendances ignorées reliées au dépôt) sont des liens symboliques : ils ne comptent pas.
+ */
+export function untrackedFiles(dir) {
+    let out = '';
+    try {
+        out = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch {
+        // arbre illisible : rien de connu
+    }
+    return out
+        .split('\n')
+        .filter((l) => l.startsWith('?? '))
+        .map((l) => l.slice(3).replace(/^"|"$/g, ''))
+        .filter((f) => {
+        try {
+            return !lstatSync(join(dir, f)).isSymbolicLink();
+        }
+        catch {
+            return true;
+        }
+    });
+}
+/**
+ * Retire le worktree et la branche d'un lot (R12). Sans `abandon`, seul un lot dont tous les commits sont dans la branche du dépôt, à l'arbre propre (ni fichier suivi modifié, ni fichier non suivi non ignoré),
+ * est retiré ; la branche part alors par une suppression gardée par son sha (jamais `-D`). Avec `abandon` (commande explicite du lead, R20),
+ * les commits non intégrés sont abandonnés. Les liens vers le dépôt vivant ne sont pas suivis : seul le lien est supprimé.
+ */
+export function removeTree(t, opts = {}) {
+    const sha = branchSha(t.repo, t.branch);
+    const unintegrated = sha ? unintegratedCommits(t.repo, t.branch, t.base) : 0;
+    if (!opts.abandon) {
+        if (unintegrated > 0)
+            return { ok: false, unintegrated };
+        const dirty = existsSync(join(t.dir, '.git')) ? trackedDirty(t.dir) : [];
+        if (dirty.length)
+            return { ok: false, unintegrated: 0, dirty };
+        const untracked = existsSync(join(t.dir, '.git')) ? untrackedFiles(t.dir) : [];
+        if (untracked.length)
+            return { ok: false, unintegrated: 0, untracked };
+    }
+    if (existsSync(t.dir)) {
+        try {
+            git(t.repo, 'worktree', 'remove', '--force', t.dir);
+        }
+        catch {
+            rmSync(t.dir, { recursive: true, force: true });
+        }
+    }
+    tryGit(t.repo, 'worktree', 'prune');
+    if (sha) {
+        if (opts.abandon && unintegrated > 0)
+            git(t.repo, 'branch', '-D', t.branch);
+        else
+            git(t.repo, 'update-ref', '-d', `refs/heads/${t.branch}`, sha);
+        tryGit(t.repo, 'config', '--local', '--remove-section', `branch.${t.branch}`);
+    }
+    return { ok: true, abandoned: opts.abandon ? unintegrated : 0 };
+}
+/**
+ * Les worktrees de lot que le dépôt garde (R19) : toute branche `cadence/*` reconnue (la config git de cadence y est). Rien n'est stocké ailleurs :
+ * un worktree retiré a perdu sa branche, un worktree conservé reste listé tant que personne ne le retire (R20).
+ */
+export function keptTrees(repo, opts = {}) {
+    const live = new Set(liveWaves(cadenceHome()).map((w) => w.wave));
+    const trees = registered(repo);
+    const dirOf = new Map([...trees].filter(([, b]) => b).map(([p, b]) => [b, p]));
+    const branches = (tryGit(repo, 'for-each-ref', '--format=%(refname:short)', 'refs/heads/cadence/') ?? '').split('\n').filter(Boolean);
+    const out = [];
+    for (const branch of branches) {
+        const base = baseBranchOf(repo, branch);
+        if (!base)
+            continue;
+        const dir = dirOf.get(branch) ?? null;
+        out.push({
+            lot: config(repo, branch, 'lot') ?? branch,
+            wave: branch.split('/')[1] ?? '?',
+            branch,
+            base,
+            dir,
+            dirExists: dir !== null && existsSync(dir),
+            created: Number(config(repo, branch, 'created') ?? 0),
+            unintegrated: unintegratedCommits(repo, branch, base),
+            active: live.has(branch.split('/')[1] ?? ''),
+        });
+    }
+    return opts.includeActive ? out : out.filter((t) => !t.active); // le worktree d'une vague vivante n'est pas « conservé » : il sert
+}
+/**
+ * Le plan vu depuis un worktree (R21) : le même plan, avec le chemin du fichier correspondant sous `root` — pour les lectures d'historique
+ * (lotWork, isPlanOnly, coveredTasks, unreviewedWork) qui rapportent le fichier de plan à la racine qu'on leur passe. Ne sert jamais à écrire.
+ */
+export function planSeenFrom(plan, repo, root) {
+    const under = (p) => {
+        const rel = relative(repo, p);
+        return rel === '' || rel.startsWith('..') || isAbsolute(rel) ? p : join(root, rel);
+    };
+    return Object.create(plan, { path: { value: under(plan.path) }, configFile: { get: () => (plan.configFile === null ? null : under(plan.configFile)) } });
+}
+/** Âge lisible d'un worktree conservé : minutes, heures, puis jours. */
+export function ageText(ms) {
+    const min = Math.max(0, Math.round(ms / 60_000));
+    return min < 60 ? `${min} min` : min < 48 * 60 ? `${Math.round(min / 60)} h` : `${Math.round(min / 1440)} j`;
+}
+export const KEPT_TITLE = 'worktrees de lot conservés (cadence orchestrate --remove-worktree <projet>:<lot> pour les retirer) :';
+/** Une ligne par worktree conservé (R19) : dépôt, lot, âge, commits non intégrés, chemin. */
+export const keptLine = (repoName, t, now = Date.now()) => `  ${repoName} · ${t.lot} · ${ageText(now - t.created)} · ${t.unintegrated} commit(s) non intégré(s) · ${t.dir ?? `(worktree absent, branche ${t.branch})`}`;
+/**
+ * Les lignes qui disent les worktrees de lot conservés (R19) : un titre puis une ligne par worktree ; aucune ligne quand il n'y en a pas. Source commune de
+ * `cadence orchestrate --status`, du tableau de fin de vague et de `cadence lead tour`.
+ */
+export function keptLines(repos, now = Date.now()) {
+    const rows = [...new Set(repos)].flatMap((repo) => keptTrees(repo).map((t) => keptLine(basename(repo), t, now)));
+    return rows.length ? [KEPT_TITLE, ...rows] : [];
+}