pipcode 0.0.0-stage → 2.1.0

package/src/auto/pricing.js

@@ -0,0 +1,49 @@
+// src/auto/pricing.js — Table publique de prix modèles (USD / 1M tokens, in/out).
+// Surchargeable via env PLUGCTO_PRICING_JSON (JSON string). Devis = estimation honnête,
+// pas une garantie (cf. computeImpact index.js).
+
+// Table de prix par provider/modèle. Fallback conservatif si modèle inconnu.
+/** @returns {PricingTable} */
+export function loadPricing() {
+  /** @type {PricingTable} */
+  const def = {
+    openai: {
+      "gpt-5": { in: 1.25, out: 10 }, "gpt-5-mini": { in: 0.25, out: 2 },
+      "gpt-4.1": { in: 2, out: 8 }, "gpt-4.1-mini": { in: 0.4, out: 1.6 },
+      "gpt-4.1-nano": { in: 0.1, out: 0.4 }, "gpt-4o": { in: 2.5, out: 10 },
+      "gpt-4o-mini": { in: 0.15, out: 0.6 },
+    },
+    anthropic: {
+      "claude-3-opus-latest": { in: 15, out: 75 }, "claude-3-5-sonnet-latest": { in: 3, out: 15 },
+      "claude-sonnet-5": { in: 3, out: 15 }, "claude-opus-5": { in: 15, out: 75 },
+      "claude-haiku-4-5": { in: 1, out: 5 },
+    },
+    gemini: {
+      "gemini-1.5-pro": { in: 1.25, out: 5 }, "gemini-1.5-flash": { in: 0.075, out: 0.3 },
+      "gemini-2.5-flash": { in: 0.15, out: 0.6 }, "gemini-2.5-pro": { in: 1.25, out: 5 },
+      "gemini-2.0-flash": { in: 0.1, out: 0.4 },
+    },
+    zhipu: { "glm-4.6": { in: 0.6, out: 2.2 }, "glm-4-flash": { in: 0.1, out: 0.3 } },
+  };
+  // Famille par défaut (fallback si modèle inconnu) — conservative.
+  const famDef = { openai: { in: 1, out: 5 }, anthropic: { in: 3, out: 15 }, gemini: { in: 0.5, out: 2 }, zhipu: { in: 0.6, out: 2.2 } };
+  if (process.env.PLUGCTO_PRICING_JSON) {
+    try { return /** @type {PricingTable} */ (JSON.parse(process.env.PLUGCTO_PRICING_JSON)); } catch { /* ignore, garde défaut */ }
+  }
+  def.__default = famDef;
+  return def;
+}
+
+/** @type {PricingTable} */
+export const PROVIDER_PRICING = loadPricing();
+
+// Prix d'un modèle (ou fallback famille/défaut absolu { in: 1, out: 5 }).
+/** @param {string} provider @param {string} model @returns {PricePair} */
+export function lookupPrice(provider, model) {
+  const table = PROVIDER_PRICING[provider];
+  if (table && table[model]) return table[model];
+  const famDef = PROVIDER_PRICING.__default;
+  if (famDef && famDef[provider]) return famDef[provider];
+  return { in: 1, out: 5 }; // garde-fou absolu.
+}
+// MODULE_COMPLETE

package/src/auto/project-files.js

@@ -0,0 +1,12 @@
+// src/auto/project-files.js — Fichiers source du projet pour le LLM : git ls-files si dépôt, sinon lecture du disque
+// (projet brut non versionné : jamais bloquant, jamais liste vide à tort).
+
+import { gitListSourceFiles } from "./git.js";
+import { fsListSourceFiles } from "./fs-list.js";
+
+/** @param {string} projectPath @returns {Promise<string[]>} */
+export async function listProjectFiles(projectPath) {
+  const tracked = await gitListSourceFiles(projectPath);
+  return tracked.length > 0 ? tracked : fsListSourceFiles(projectPath);
+}
+// MODULE_COMPLETE

package/src/auto/prompts.js

@@ -0,0 +1,24 @@
+// src/auto/prompts.js — Prompt + schéma de décomposition des micro-tâches.
+// Byte-stable (aucune interpolation runtime) : le contexte variable va dans le bloc user (callLLM),
+// jamais dans le system prompt (doctrine de prompt caching).
+
+// Prompt de décomposition (CTO architecte senior → tableau JSON de micro-tâches) : TEXTE servi par le serveur
+// (lot Pro) ; ici seulement l'accès au registre mémoire (jamais de prompt inventé sans règles chargées).
+import { getRules } from "../rules/rules-registry.js";
+/** @returns {string} */
+export const taskDecompPrompt = () => getRules().prompts.decomp;
+
+// Schéma JSON de validation des micro-tâches (champs requis + enum de status).
+export const TASK_SCHEMA = {
+  type: "object",
+  required: ["id", "title", "file", "objective", "acceptance"],
+  properties: {
+    id: { type: "string" },
+    title: { type: "string" },
+    file: { type: "string" },
+    objective: { type: "string" },
+    acceptance: { type: "string" },
+    status: { type: "string", enum: ["pending", "done", "failed", "skipped"] },
+  },
+};
+// MODULE_COMPLETE

package/src/auto/quote-format.js

@@ -0,0 +1,33 @@
+// src/auto/quote-format.js — Rendu du devis Auto Mode : durée estimée
+// (débit LLM prudent, headroom re-attaque ×1.3 déjà inclus dans les tokens)
+// + formatQuote (tâches, budget, coût, avertissement honnête).
+
+// Durée d'exécution estimée : les tokens du devis (headroom inclus) divisés
+// par un débit de sortie prudent 30-100 tok/s, + latence fixe par appel LLM.
+/** @param {AutoTask[]} tasks @param {BudgetQuote} budget @returns {{ low: number, high: number }} */
+export function estimateRunMinutes(tasks, budget) {
+  const calls = Math.max(1, tasks.length);
+  const tokens = budget.tokensEst || 0;
+  const low = Math.max(1, Math.ceil(tokens / 6000 + calls * 0.25));
+  const high = Math.max(low + 1, Math.ceil(tokens / 1800 + calls * 0.75));
+  return { low, high };
+}
+
+// Rendu lisible du devis (durée, budget, coût, avertissement estimation).
+/** @param {AutoTask[]} tasks @param {BudgetQuote} budget @returns {string} */
+export function formatQuote(tasks, budget) {
+  const d = estimateRunMinutes(tasks, budget);
+  const lines = [];
+  lines.push(`📋 Plan Auto Mode — ${tasks.length} micro-tâches`);
+  lines.push(`   Durée estimée : ~${d.low} à ${d.high} min (estimation, latence variable selon fournisseur)`);
+  lines.push(`   Budget estimé : ~${(budget.tokensEst || 0).toLocaleString()} tokens`);
+  lines.push(`   Coût API estimé : ~$${(budget.costUsdEst || 0).toFixed(4)} (provider BYOK, prix output)`);
+  lines.push(`   Tâches :`);
+  for (const t of tasks.slice(0, 10)) lines.push(`     • [${t.id}] ${t.file} — ${t.title}`);
+  if (tasks.length > 10) lines.push(`     • … (+${tasks.length - 10} autres)`);
+  lines.push("");
+  lines.push("⚠️ Estimation honnête, pas une garantie. Lancement bloqué jusqu'au consentement.");
+  lines.push("   Pour lancer : npx pipcode auto run (Y/n).");
+  return lines.join("\n");
+}
+// MODULE_COMPLETE

package/src/auto/retry.js

@@ -0,0 +1,40 @@
+// src/auto/retry.js — U3 : retry/backoff exponentiel + jitter sur erreurs transient.
+// isTransientLLMError : 429/5xx/408/409/425 + réseau sans status. On NE retente pas
+// sur 400/401/403/404/422 (erreurs définitives). withTransientRetry : borné par
+// LLM_RETRY.maxRetries. Orthogonal au QA-retry (MAX_QA_ATTEMPTS).
+
+import { LLM_RETRY, LLM_RETRYABLE_STATUS } from "./constants.js";
+
+// Erreur provider retryable ? (status HTTP retryable, ou réseau sans status).
+/** @param {unknown} err @returns {boolean} */
+export function isTransientLLMError(err) {
+  if (!err) return false;
+  const e = /** @type {Error & { status?: number, rateLimitExhausted?: boolean }} */ (err);
+  if (e.rateLimitExhausted) return false; // série de 429 déjà épuisée dans callLLM : on ne la recommence pas
+  const status = e.status;
+  if (Number.isFinite(status)) return LLM_RETRYABLE_STATUS.has(/** @type {number} */ (status));
+  // Pas de status HTTP → échec réseau/timeout (AbortError, fetch failed, ECONNRESET).
+  return true;
+}
+
+// Exécute fn avec retry/backoff exponentiel + jitter (±25%) sur erreurs transient.
+// Renvoie le résultat de fn ou re-throw la dernière erreur. Borné par maxRetries.
+/** @template T @param {() => Promise<T>} fn @param {string} [_label] @returns {Promise<T>} */
+export async function withTransientRetry(fn, _label = "llm") {
+  const maxRetries = LLM_RETRY.maxRetries;
+  let lastErr;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (attempt === maxRetries || !isTransientLLMError(err)) throw err;
+      // Backoff exponentiel + jitter (±25%) : 0.8s, 1.6s, 3.2s… anti thundering herd.
+      const base = LLM_RETRY.baseMs * Math.pow(2, attempt);
+      const jitter = base * (0.75 + Math.random() * 0.5);
+      await new Promise((r) => setTimeout(r, jitter));
+    }
+  }
+  throw lastErr;
+}
+// MODULE_COMPLETE

package/src/auto/run-lock.js

@@ -0,0 +1,40 @@
+// src/auto/run-lock.js — Verrou d'exécution mono-instance (audit hebdo, INFO).
+// <plugDir>/run.lock contient le PID du détenteur ; un verrou dont le PID n'est
+// plus vivant (crash/reboot) est déclaré périmé et écrasé sans bloquer la suite.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { plugDirOf } from "./paths.js";
+
+const LOCK_FILE = "run.lock";
+
+// PID vivant ? process.kill(pid, 0) : ESRCH = mort, EPERM = vivant (autre session).
+// Résidu assumé (mono-utilisateur) : un PID mort réutilisé par l'OS donnerait un
+// faux « déjà en cours » temporaire — la vérification lève la barre du trivial.
+/** @param {number} pid @returns {boolean} */
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (err) {
+    const e = /** @type {Error & { code?: string }} */ (err);
+    return e.code === "EPERM"; // EPERM = vivant (autre session) ; ESRCH = mort
+  }
+}
+
+// Acquiert le verrou du projet ; retourne release() (best-effort). Jette si une
+// instance vivante le détient déjà. Verrou périmé (PID mort/illisible) → écrasé.
+/** @param {string} projectPath @returns {Promise<() => Promise<void>>} */
+export async function acquireRunLock(projectPath) {
+  const plugDir = plugDirOf(projectPath);
+  const lockFile = path.join(plugDir, LOCK_FILE);
+  let prev = null;
+  try { prev = Number((await fs.readFile(lockFile, "utf8")).trim()); } catch { /* absent → prise directe */ }
+  if (typeof prev === "number" && Number.isInteger(prev) && prev > 0 && pidAlive(prev)) {
+    throw new Error(`Une exécution pipcode auto est déjà en cours sur ce projet (PID ${prev}).`);
+  }
+  await fs.mkdir(plugDir, { recursive: true });
+  await fs.writeFile(lockFile, String(process.pid), "utf8");
+  return async () => {
+    try { await fs.rm(lockFile, { force: true }); } catch { /* best-effort : verrou périmé au prochain run */ }
+  };
+}
+// MODULE_COMPLETE

package/src/auto/run-loop.js

@@ -0,0 +1,38 @@
+// src/auto/run-loop.js — Boucle d'exécution du Mode Auto + garde-fou : cap de
+// MAX_CONSECUTIVE_FAILURES échecs consécutifs (persistés dans l'état) → arrêt
+// immédiat, état préservé, rapport d'arrêt avec les 2 options de restauration.
+// Le compteur est remis à zéro par toute tâche validée (step-green).
+
+import { runAutoStep } from "./step.js";
+import { loadAutoState, saveAutoState, progressOf } from "./state.js";
+import { pauseRun } from "./cancel.js";
+import { isRunAborted } from "../core/abort-signal.js";
+import { MAX_CONSECUTIVE_FAILURES } from "./constants.js";
+import { stopReport } from "./stop-options.js";
+import { ensureGitRepo } from "./git-init.js";
+
+// Boucle : exécute runAutoStep (confirmed:true) jusqu'à done/failed/isError ou maxSteps.
+/** @param {{ projectPath: string, pcfg: { primary: ProviderPrimary }, cfg: PlugConfig, maxSteps: number }} arg @param {AutoDeps} deps @returns {Promise<AutoResult>} */
+export async function runAutoLoop({ projectPath, pcfg, cfg, maxSteps }, deps) {
+  const state = await loadAutoState(projectPath);
+  if (state && (state.failureStreak || 0) >= MAX_CONSECUTIVE_FAILURES) {
+    // Garde-fou anti-boucle infinie : refus d'exécution, l'utilisateur arbitre.
+    const text = await stopReport({ projectPath, state },
+      `Garde-fou : ${MAX_CONSECUTIVE_FAILURES} échecs consécutifs — le Mode Auto refuse de relancer une boucle identique.`);
+    return { isError: true, text, progress: progressOf(state), status: state.status, last: { failed: true } };
+  }
+  if (state && state.status === "awaiting_user") return { asking: true, question: state.question, status: state.status, progress: progressOf(state) };
+  try { await ensureGitRepo(projectPath); } catch (e) { return { isError: true, text: /** @type {Error} */ (e).message }; }
+  /** @type {AutoResult[]} */ const steps = [];
+  let n = 0; let last;
+  if (state && state.status === "paused") { state.status = "running"; await saveAutoState(projectPath, state); } // reprise après un Stop
+  while (n < maxSteps) {
+    if (isRunAborted()) return pauseRun(projectPath); // Stop entre deux tâches
+    last = await runAutoStep({ projectPath, confirmed: true, pcfg, cfg }, deps);
+    steps.push(last);
+    if (last.done || last.failed || last.isError || last.asking || last.cancelled) break; // une question posée est une PAUSE, pas un échec
+    n++;
+  }
+  return { progress: last && last.progress, steps, status: last && last.status, summary: last && last.summary, last };
+}
+// MODULE_COMPLETE

package/src/auto/run.js

@@ -0,0 +1,49 @@
+// src/auto/run.js — Pilier 2 : runAutoRun + reprise sur crash resumeAuto.
+// Boucle d'exécution extraite dans run-loop.js (garde-fou cap d'échecs
+// consécutifs). Verrou mono-instance autour de l'exécution.
+
+import { loadAutoState, saveAutoState, progressOf, formatRunSummary } from "./state.js";
+import { formatQuote } from "./quote-format.js";
+import { runAutoLoop } from "./run-loop.js";
+import { acquireRunLock } from "./run-lock.js";
+import { resumeFromPause } from "./ask-pause.js";
+
+// Boucle : exécute runAutoStep (confirmed:true) jusqu'à done/failed/isError ou maxSteps.
+/** @param {AutoRunArgs} arg @param {AutoDeps} deps @returns {Promise<AutoResult>} */
+export async function runAutoRun({ projectPath, confirmed, maxSteps = 50, pcfg, cfg }, deps) {
+  const state = await loadAutoState(projectPath);
+  if (!state) return { isError: true, text: "Aucun plan Auto trouvé. Établissez d'abord le plan du Mode Auto." };
+  if (state.status === "consent_pending" && !confirmed) {
+    return { needsConsent: true, quote: formatQuote(state.tasks, state.budget), status: "consent_pending" };
+  }
+  if (state.status === "done") return { done: true, progress: progressOf(state), summary: formatRunSummary(state), status: "done" };
+  /** @type {() => Promise<void>} */
+  let release;
+  try { release = await acquireRunLock(projectPath); } // mono-instance (audit hebdo)
+  catch (err) {
+    const e = /** @type {Error & { message?: string }} */ (err);
+    return { isError: true, text: String((e && e.message) || err) };
+  }
+  try {
+    return await runAutoLoop({ projectPath, pcfg, cfg, maxSteps }, deps);
+  } finally {
+    await release(); // best-effort : verrou retiré quoi qu'il arrive
+  }
+}
+
+// Reprise sur crash : lit state, reprend à cursor (consent_pending → needsConsent, sinon running).
+/** @param {ResumeArgs} arg @param {AutoDeps} deps @returns {Promise<AutoResult>} */
+export async function resumeAuto({ projectPath, maxSteps = 50, answer, pcfg, cfg }, deps) {
+  const state = await loadAutoState(projectPath);
+  if (!state) return { isError: true, text: "Aucun plan Auto à reprendre (pas de .pipcode/auto-state.json)." };
+  if (state.status === "done") return { done: true, progress: progressOf(state), summary: formatRunSummary(state), status: "done" };
+  if (state.status === "consent_pending") {
+    return { needsConsent: true, quote: formatQuote(state.tasks, state.budget), status: "consent_pending" };
+  }
+  const paused = await resumeFromPause(projectPath, state, answer); // pause ASK_USER : question rendue, ou réponse enregistrée
+  if (paused) return paused;
+  state.status = "running";
+  await saveAutoState(projectPath, state);
+  return runAutoRun({ projectPath, confirmed: true, maxSteps, pcfg, cfg }, deps);
+}
+// MODULE_COMPLETE

package/src/auto/snapshot-gate.js

@@ -0,0 +1,51 @@
+// src/auto/snapshot-gate.js — checkGreen : détection + exécution des gates du
+// projet client. tsconfig.json (avec typescript local installé) → tsc --noEmit ;
+// scripts.test → npm test. Absents = "skipped" (le checkpoint git tient lieu de
+// preuve verte). Commandes à arguments FIXES uniquement (aucune entrée utilisateur).
+// OBSERVER : quand une gate est rouge, sa sortie (stdout + stderr) est CAPTURÉE : la boucle auto-corrective la relit.
+
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { GREEN_TSC_TIMEOUT_MS, GREEN_TEST_TIMEOUT_MS } from "./constants.js";
+import { runSignal } from "../core/abort-signal.js";
+
+// Exécute une commande fixe dans le projet : green/red + sortie capturée quand rouge (fail-safe).
+/** @param {string} projectPath @param {string} file @param {string[]} args @param {number} timeoutMs @returns {Promise<{ status: "green" | "red", log: string }>} */
+function runFixed(projectPath, file, args, timeoutMs) {
+  return new Promise((resolve) => {
+    execFile(file, args, { cwd: projectPath, windowsHide: true, timeout: timeoutMs, maxBuffer: 8 * 1024 * 1024, signal: runSignal, shell: process.platform === "win32" }, (err, stdout, stderr) => {
+      resolve(err ? { status: "red", log: `${stdout}\n${stderr}`.trim() || String(err.message) } : { status: "green", log: "" });
+    });
+  });
+}
+
+// Le projet a-t-il une gate tsc exécutable localement (tsconfig + typescript) ?
+/** @param {string} projectPath @returns {Promise<boolean>} */
+async function hasTscGate(projectPath) {
+  try {
+    await fs.access(path.join(projectPath, "tsconfig.json"));
+    await fs.access(path.join(projectPath, "node_modules", "typescript", "bin", "tsc"));
+    return true;
+  } catch { return false; }
+}
+
+// Le package.json déclare-t-il scripts.test ? (parse défensif, jamais de crash)
+/** @param {string} projectPath @returns {Promise<boolean>} */
+async function hasTestScript(projectPath) {
+  try {
+    const p = JSON.parse(await fs.readFile(path.join(projectPath, "package.json"), "utf8"));
+    return !!(p && typeof p === "object" && p.scripts && typeof p.scripts.test === "string" && p.scripts.test.trim());
+  } catch { return false; }
+}
+
+// État des gates du projet : tsc et tests (green/red/skipped chacun) + sortie des gates rouges (log).
+/** @param {string} projectPath @returns {Promise<GreenReport>} */
+export async function checkGreen(projectPath) {
+  if (typeof projectPath !== "string" || !projectPath.trim()) return { tsc: "skipped", tests: "skipped" };
+  const tsc = (await hasTscGate(projectPath)) ? await runFixed(projectPath, "npx", ["tsc", "--noEmit"], GREEN_TSC_TIMEOUT_MS) : null;
+  const tests = (await hasTestScript(projectPath)) ? await runFixed(projectPath, "npm", ["test"], GREEN_TEST_TIMEOUT_MS) : null;
+  const log = [tsc?.log && `tsc --noEmit :\n${tsc.log}`, tests?.log && `npm test :\n${tests.log}`].filter(Boolean).join("\n\n");
+  return { tsc: tsc?.status ?? "skipped", tests: tests?.status ?? "skipped", ...(log ? { log } : {}) };
+}
+// MODULE_COMPLETE

package/src/auto/snapshot-paths.js

@@ -0,0 +1,33 @@
+// src/auto/snapshot-paths.js — Chemins du cache de garde-fou du Mode Auto :
+// .pipcode/cache/snapshots/ (repères state_pre_gen / state_last_green). Exclusion
+// Git idempotente du dossier dans le projet client (jamais commité).
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// Repères de restauration (Option 1 = avant génération, Option 2 = dernier vert).
+export const SNAP_PRE = "state_pre_gen";
+export const SNAP_GREEN = "state_last_green";
+export const SNAP_KINDS = [SNAP_PRE, SNAP_GREEN];
+
+// Dossier snapshots à la racine du projet client (<projectPath>/.pipcode/cache/snapshots).
+/** @param {string} projectPath @returns {string} */
+export function snapDirOf(projectPath) { return path.join(projectPath, ".pipcode", "cache", "snapshots"); }
+
+// Chemin du marqueur JSON d'un repère (<snapDir>/<kind>.json).
+/** @param {string} projectPath @param {string} kind @returns {string} */
+export function markerPathOf(projectPath, kind) { return path.join(snapDirOf(projectPath), `${kind}.json`); }
+
+// Exclut .pipcode/cache/ du Git du projet client. Idempotent, best-effort (jamais de crash).
+/** @param {string} projectPath @returns {Promise<void>} */
+export async function ensureGitignored(projectPath) {
+  const line = ".pipcode/cache/";
+  const gi = path.join(projectPath, ".gitignore");
+  let cur = "";
+  try { cur = await fs.readFile(gi, "utf8"); } catch { /* absent → créé ci-dessous */ }
+  const norm = cur.replace(/\r\n/g, "\n");
+  if (norm.split("\n").some((l) => l.trim() === line)) return;
+  const data = norm + (norm.endsWith("\n") || norm === "" ? "" : "\n") + line + "\n";
+  await fs.writeFile(gi, data, { encoding: "utf8" });
+}
+// MODULE_COMPLETE

package/src/auto/snapshot-restore.js

@@ -0,0 +1,59 @@
+// src/auto/snapshot-restore.js — restoreSnapshot : restitue le projet client au
+// repère demandé (Option 1 = state_pre_gen, Option 2 = state_last_green) :
+// git reset --hard <head> du repère, purge des fichiers créés par le run annulé
+// (nouveaux fichiers du patch, absents du HEAD du repère), puis ré-application
+// du patch (état de travail exact au moment du repère ; les untracked présents
+// au repère survivent et font partie de l'état restauré).
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { gitExec } from "./git.js";
+import { touchedFilesFromDiff } from "./diff.js";
+import { markerPathOf, snapDirOf, SNAP_KINDS } from "./snapshot-paths.js";
+
+// Lit et valide le marqueur du repère (Zero Trust : head contrôlé).
+/** @param {string} projectPath @param {string} kind @returns {Promise<SnapshotMarker>} */
+async function readMarker(projectPath, kind) {
+  let raw;
+  try { raw = await fs.readFile(markerPathOf(projectPath, kind), "utf8"); }
+  catch { throw new Error(`Aucun repère ${kind} (aucun snapshot pris avant la génération).`); }
+  const m = /** @type {SnapshotMarker} */ (JSON.parse(raw));
+  if (!m || typeof m !== "object" || typeof m.head !== "string" || !/^[0-9a-f]{7,40}$/.test(m.head)) {
+    throw new Error(`Repère ${kind} corrompu (head invalide) — supprimez .pipcode/cache/snapshots/.`);
+  }
+  return m;
+}
+
+// Purge les résidus du run annulé : fichiers touchés par le patch mais absents du
+// HEAD du repère (nouveaux fichiers devenus untracked après reset --hard).
+/** @param {string} projectPath @param {string} head @param {string} patchText @returns {Promise<void>} */
+async function purgeRunLeftovers(projectPath, head, patchText) {
+  for (const f of touchedFilesFromDiff(patchText)) {
+    try { await gitExec(projectPath, ["cat-file", "-e", `${head}:${f}`]); } catch {
+      await fs.rm(path.join(projectPath, f), { force: true }).catch(() => { /* best-effort */ });
+    }
+  }
+}
+
+// Restitue l'état capturé par le repère. Option 1 → pre_gen, Option 2 → last_green.
+/** @param {string} projectPath @param {number} option @returns {Promise<{ restored: string, head: string }>} */
+export async function restoreSnapshot(projectPath, option) {
+  if (typeof projectPath !== "string" || !projectPath.trim()) throw new Error("Chemin de projet invalide.");
+  const kind = option === 1 ? SNAP_KINDS[0] : option === 2 ? SNAP_KINDS[1] : "";
+  if (!kind) throw new Error("Option invalide : 1 (state_pre_gen) ou 2 (state_last_green).");
+  const m = await readMarker(projectPath, kind);
+  // m.untracked = fichiers présents au repère : ils survivent à reset --hard et
+  // font partie de l'état restauré — jamais supprimés. Seuls les résidus du run
+  // annulé (nouveaux fichiers du patch, absents du HEAD du repère) sont purgés.
+  await gitExec(projectPath, ["reset", "--hard", m.head]);
+  if (typeof m.patch === "string" && m.patch.trim()) {
+    const patchPath = path.join(snapDirOf(projectPath), m.patch);
+    const patchText = await fs.readFile(patchPath, "utf8");
+    if (patchText.trim()) { // arbre propre au repère → patch vide → rien à ré-appliquer
+      await purgeRunLeftovers(projectPath, m.head, patchText);
+      await gitExec(projectPath, ["apply", patchPath]);
+    }
+  }
+  return { restored: kind, head: m.head };
+}
+// MODULE_COMPLETE

package/src/auto/snapshot-take.js

@@ -0,0 +1,30 @@
+// src/auto/snapshot-take.js — takeSnapshot : capture légère (diff/patch) de l'état
+// du code sous .pipcode/cache/snapshots/ et écrit le marqueur <kind>.json (head +
+// patch + untracked). Fail-safe : toute erreur → null, le run ne plante jamais.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { gitExec } from "./git.js";
+import { snapDirOf, markerPathOf, ensureGitignored } from "./snapshot-paths.js";
+
+// Prend un snapshot (diff HEAD + untracked + HEAD sha) et marque le repère.
+/** @param {string} projectPath @param {string} kind @returns {Promise<SnapshotMarker | null>} */
+export async function takeSnapshot(projectPath, kind) {
+  try {
+    const dir = snapDirOf(projectPath);
+    await fs.mkdir(dir, { recursive: true });
+    await ensureGitignored(projectPath);
+    const head = await gitExec(projectPath, ["rev-parse", "HEAD"]);
+    const diff = await gitExec(projectPath, ["diff", "HEAD"]);
+    const rawUntracked = await gitExec(projectPath, ["ls-files", "--others", "--exclude-standard"]);
+    const untracked = rawUntracked.split("\n").map((s) => s.trim()).filter(Boolean).filter((f) => !f.startsWith(".pipcode/"));
+    const patch = `snap-${kind}-${crypto.randomBytes(6).toString("hex")}.patch`;
+    await fs.writeFile(path.join(dir, patch), diff + (diff.endsWith("\n") || diff === "" ? "" : "\n"), { encoding: "utf8", mode: 0o600 });
+    /** @type {SnapshotMarker} */
+    const marker = { kind, head, patch, untracked, takenAt: new Date().toISOString() };
+    await fs.writeFile(markerPathOf(projectPath, kind), JSON.stringify(marker, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    return marker;
+  } catch { return null; } // fail-safe : un snapshot impossible n'arrête jamais le run
+}
+// MODULE_COMPLETE

package/src/auto/state.js

@@ -0,0 +1,52 @@
+// src/auto/state.js — État (checkpoint) Auto : lecture/écriture atomique 0600.
+// loadAutoState : {} si absent/corrompu. saveAutoState : temp à entropie + rename.
+// progressOf : rendu "done/total". Pur (hors I/O fs).
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { statePathOf } from "./paths.js";
+
+// Lit le state Auto ; null si absent, non-objet ou corrompu (parse échoue).
+/** @param {string} projectPath @returns {Promise<AutoState | null>} */
+export async function loadAutoState(projectPath) {
+  try {
+    const raw = await fs.readFile(statePathOf(projectPath), "utf8");
+    const s = /** @type {unknown} */ (JSON.parse(raw));
+    if (s && typeof s === "object") return /** @type {AutoState} */ (s);
+    return null;
+  } catch { return null; }
+}
+
+// Écrit le state atomiquement (temp + rename, permissions 0600).
+/** @param {string} projectPath @param {AutoState} state @returns {Promise<void>} */
+export async function saveAutoState(projectPath, state) {
+  const p = statePathOf(projectPath);
+  await fs.mkdir(path.dirname(p), { recursive: true });
+  const data = JSON.stringify(state, null, 2) + "\n";
+  const tmp = `${p}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+  await fs.writeFile(tmp, data, { encoding: "utf8", mode: 0o600 });
+  try { await fs.rename(tmp, p); }
+  catch { await fs.writeFile(p, data, { encoding: "utf8", mode: 0o600 }); await fs.rm(tmp, { force: true }); }
+}
+
+// Rendu de progression "done/total" depuis le state.
+/** @param {AutoState} state @returns {string} */
+export function progressOf(state) {
+  const total = state.tasks.length;
+  const done = state.tasks.filter((t) => t.status === "done").length;
+  return `${done}/${total}`;
+}
+
+// Bilan final du run Auto (exigence produit) : durée devis → fin, tokens
+// consommés (estimation honnête par tâche, budget.js) et coût API dérivé.
+// Pur — consomme uniquement l'état persisté (reprise sur crash incluse).
+/** @param {AutoState} state @returns {string} */
+export function formatRunSummary(state) {
+  const b = state.budget || { tokensUsed: 0, costUsdUsed: 0 };
+  const ms = Date.parse(state.updatedAt || "") - Date.parse(state.startedAt || "");
+  const dur = Number.isFinite(ms) && ms >= 0 ? `${Math.round(ms / 60000)} min` : "—";
+  const tokens = (b.tokensUsed || 0).toLocaleString();
+  return `⏱️ Durée : ${dur} • 🔋 Tokens consommés (estimation honnête) : ~${tokens} • 💰 Coût API : ~$${(b.costUsdUsed || 0).toFixed(4)}`;
+}
+// MODULE_COMPLETE

package/src/auto/step-commit.js

@@ -0,0 +1,46 @@
+// src/auto/step-commit.js — Application sûre + checkpoint de runAutoStep (Pilier 2/3).
+// applyTaskDiff : applyDiffSafe + rollback état si échec. checkpointTask : done, budget,
+// amnésie lastDiff, journalise, trio documentaire client en fin de mission, retourne AutoResult.
+
+import { applyDiffBacked } from "./apply-diff-backed.js";
+import { saveAutoState, progressOf, formatRunSummary } from "./state.js";
+import { estimateTaskTokens } from "./budget.js";
+import { lookupPrice } from "./pricing.js";
+import { redactError } from "./amnesia.js";
+import { generateClientDocs } from "./mission-docs.js";
+
+// Applique le diff (git apply + commit, SAFE_SURGERY). Retourne { applied }, { exit } (failed) ou — en mode « soft » de la boucle auto-corrective — { error } sans toucher à l'état de la tâche.
+/** @param {StepCtx} ctx @param {OrchestratorResult} result @param {number} attempts @param {boolean} [soft] @returns {Promise<{ applied?: { commit: string, touched: string[] }, exit?: AutoResult, error?: string }>} */
+export async function applyTaskDiff(ctx, result, attempts, soft = false) {
+  const { deps, projectPath, task, state, idx } = ctx;
+  try {
+    const applied = await applyDiffBacked({ projectPath, file: task.file, diff: result.patch, deps });
+    return { applied };
+  } catch (e) {
+    const ee = /** @type {Error} */ (e);
+    if (soft) return { error: redactError(ee.message) }; // le tour suivant corrige : la tâche n'est PAS encore en échec
+    task.status = "failed"; task.attempts = attempts + 1; task.error = redactError(ee.message);
+    state.cursor = idx + 1; state.updatedAt = new Date().toISOString();
+    await saveAutoState(projectPath, state);
+    return { exit: { failed: true, task, error: ee.message, progress: progressOf(state), status: state.status } };
+  }
+}
+
+// Checkpoint : marque done, budget utilisé, amnésie lastDiff, journalise, retourne AutoResult.
+/** @param {StepCtx} ctx @param {OrchestratorResult} result @param {number} attempts @param {{ commit: string, touched: string[] }} applied @returns {Promise<AutoResult>} */
+export async function checkpointTask(ctx, result, attempts, applied) {
+  const { deps, projectPath, task, state, idx, pcfg, missionPath, fileContent } = ctx;
+  task.status = "done"; task.attempts = attempts + 1; task.commit = applied.commit;
+  state.lastDiff = result.patch; // Pilier 3 : on ne stocke QUE lastDiff (pas analysis/code).
+  state.cursor = idx + 1;
+  state.budget.tokensUsed = (state.budget.tokensUsed || 0) + estimateTaskTokens(deps, fileContent.length);
+  state.budget.costUsdUsed = Math.round((state.budget.tokensUsed / 1_000_000) * lookupPrice(pcfg.primary.provider, pcfg.primary.model).out * 10000) / 10000;
+  if (state.cursor >= state.tasks.length) state.status = "done";
+  state.updatedAt = new Date().toISOString();
+  await saveAutoState(projectPath, state);
+  try { await deps.logIteration(missionPath, `auto ${task.id}: ${task.title} (commit ${applied.commit.slice(0, 7)})`); } catch { /* best-effort */ }
+  // Fin de mission : mise à jour du trio documentaire client (best-effort, n'échoue jamais le run).
+  if (state.status === "done") await generateClientDocs({ projectPath, state, mission: ctx.mission });
+  return { progress: progressOf(state), task, diff: result.patch, commit: applied.commit, status: state.status, budget: state.budget, summary: formatRunSummary(state) };
+}
+// MODULE_COMPLETE

package/src/auto/step-green.js

@@ -0,0 +1,38 @@
+// src/auto/step-green.js — markGreen : après apply, exécute les gates du projet
+// client (tsc + tests). Vert → snapshot state_last_green + remise à zéro du
+// compteur d'échecs. Rouge → annulation du commit auto (reset HEAD~1 + restore)
+// et échec de tâche propre avec rapport d'arrêt (2 options de restauration).
+
+import { checkGreen } from "./snapshot-gate.js";
+import { takeSnapshot } from "./snapshot-take.js";
+import { SNAP_GREEN } from "./snapshot-paths.js";
+import { gitExec } from "./git.js";
+import { gitRestore } from "./git-restore.js";
+import { failTask, stopReport } from "./stop-options.js";
+
+// Annule le dernier commit auto (reset HEAD~1) puis restitue les fichiers (best-effort).
+/** @param {string} projectPath @param {string[]} touched @returns {Promise<void>} */
+async function undoAutoCommit(projectPath, touched) {
+  try { await gitExec(projectPath, ["reset", "--hard", "HEAD~1"]); } catch { /* premier commit ou HEAD immobile : options de restauration dispo */ }
+  try { await gitRestore(projectPath, touched); } catch { /* best-effort */ }
+}
+
+// Gate verte post-apply. Retourne { green }, { exit } (échec + rapport d'arrêt) ou — mode « soft » de la boucle auto-corrective — { error } (sortie réelle des gates, commit auto annulé, tâche NON marquée en échec).
+/** @param {StepCtx} ctx @param {{ commit: string, touched: string[] }} applied @param {number} attempts @param {boolean} [soft] @returns {Promise<{ green: boolean } | { exit: AutoResult } | { error: string }>} */
+export async function markGreen(ctx, applied, attempts, soft = false) {
+  const { projectPath, state } = ctx;
+  const report = await checkGreen(projectPath);
+  if (report.tsc === "red" || report.tests === "red") {
+    await undoAutoCommit(projectPath, applied.touched);
+    if (soft) return { error: report.log || `tsc ${report.tsc} / tests ${report.tests}` };
+    const cause = `Génération invalidée par les gates du projet (tsc : ${report.tsc}, tests : ${report.tests}) — commit auto annulé.`;
+    const exit = await failTask(ctx, `tsc ${report.tsc} / tests ${report.tests}`, attempts);
+    exit.stop = await stopReport(ctx, cause);
+    return { exit };
+  }
+  // Vert (ou gates absentes : le checkpoint git tient lieu de preuve) → repère vert.
+  await takeSnapshot(projectPath, SNAP_GREEN); // best-effort fail-safe (null si impossible)
+  state.failureStreak = 0;
+  return { green: true };
+}
+// MODULE_COMPLETE