novahiz 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -3,8 +3,65 @@
 All notable changes to Novahiz are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.2] - 2026-10-10
+
+### Fixed
+
+- **In-place `npm install -g novahiz` now keeps the new package instead of
+  silently restoring the previous one** (`install/install.mjs`): the
+  `Finalize` step spawned `npm outdated` / `npm update` from inside npm's own
+  `postinstall` to refresh dependencies. npm exports its config to lifecycle
+  scripts (`npm_config_*`, `envExport` default true), so the inherited
+  `npm_config_global=true` from the outer `npm install -g` turned that refresh
+  into a **second reify of the same global prefix while npm's transaction was
+  still open**. Its retire of `node_modules\novahiz` fails with `EBUSY` (the
+  installer's cwd *is* the package directory), the nested npm crashes, and
+  arborist's rollback runs `rm(new)` + `rename(.novahiz-OLD → novahiz)` —
+  the previous install comes back byte-for-byte with its original mtimes
+  while the outer npm reports exit 0 / "changed 1 package". The refresh is now
+  pinned to the novahiz home (`npm_config_global=false`, `--ignore-scripts`),
+  a directory the outer transaction never touches. This was the actual cause
+  of "the in-place install does not replace": it reproduces with **no OpenCode
+  restart at all** (proved end-to-end 2026-10-10, see tests below).
+
+- **The npm postinstall no longer writes the opencode config while npm is
+  still mid-transaction** (`install/install.mjs`, `install/lib.mjs`): a second,
+  independent failure mode — running `npm install -g novahiz` from an
+  OpenCode-owned shell restarted the OpenCode server during `postinstall`, and
+  the restart killed the process tree with npm still inside its reify
+  transaction. Depending on where the kill landed, the update either left
+  orphaned `.novahiz-*` retire directories and shims behind or aborted the
+  configuration pass. The installer now splits in two: the synchronous pass
+  only touches `NOVAHIZ_HOME` (the only zone never observed as the restart
+  trigger across three reproduced kills), while everything that writes the
+  OpenCode config — skills, plugin, agent, commands, `opencode.jsonc`,
+  provider skill packs — runs in a detached process that waits for the
+  installer and npm to exit first (`--deferred-opencode`, log:
+  `<novahiz-home>/install-deferred.log`). That child is spawned with
+  `cwd=novahiz-home` so it can never hold the package directory open (a
+  process whose cwd sits in `node_modules\novahiz` is what makes any npm
+  retire of it fail with `EBUSY` on Windows). Direct runs (`novahiz-install`,
+  CLI bootstrap) keep the historical fully synchronous behaviour, and
+  `--sync` forces that behaviour back under npm as an escape hatch.
+  Regression tests: `tests/install-defer.test.ts`.
+
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-10
+
+Patch: `novahiz upgrade` always reported "up to date" on the npm channel.
+
+### Fixed
+
+- **`novahiz upgrade` reads the published version again**
+  (`src/commands/upgrade.ts`): the `npm view` call ran with `stdio: "ignore"`,
+  which makes `spawnSync` return `stdout: null` — `latest` was always empty,
+  `compareVersions(local, "")` always won, and the command printed
+  `up to date (npm latest: )` even when a newer release existed, so `--apply`
+  could never trigger. The call now captures stdout (`"pipe"`), with a
+  regression test spawning `npm --version` locally (no network). Inherited
+  since 0.7.1.
+
 ## [0.8.0] - 2026-10-09
 
 Minor release: total Impeccable coverage on the design roadmap, a repair

package/README.md

@@ -2,9 +2,9 @@
 
 > **Couche d'application sans dépendance pour les agents de code IA** — classe les prompts, attribue des roadmaps d'exécution, bloque les éditions non sûres tant que les bonnes skills ne sont pas chargées, et persiste les décisions d'une session à l'autre — tout cela de façon déterministe, sans appel de modèle.
 
-17 catégories, 99 skills, 13 gate rules, 8 MCP providers — tout déterministe, tout local, tout JSON.
+17 catégories, 94 skills, 13 gate rules, 8 MCP providers — tout déterministe, tout local, tout JSON.
 
-> **Version 0.6.0** — publiée sur npm (`npm install -g --allow-scripts=novahiz novahiz` installe et configure tout : core, plugin, agent, skills packs et Playwright MCP). `CHANGELOG.md` et `scripts/` sont dans le tarball.
+> **Version 0.8.0** — publiée sur npm (`npm install -g --allow-scripts=novahiz novahiz` installe et configure tout : core, plugin, agent, skills packs et Playwright MCP). `CHANGELOG.md` et `scripts/` sont dans le tarball.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────┐
@@ -35,7 +35,7 @@
                  └─ tier, skills ──────│         └─ block : charger les skills nommées, retry une fois
 ```
 
-**17 catégories**, **99 skills**, **13 gate rules**, **8 MCP providers** — tout déterministe, tout local, tout JSON.
+**17 catégories**, **94 skills**, **13 gate rules**, **8 MCP providers** — tout déterministe, tout local, tout JSON.
 
 ---
 
@@ -66,7 +66,7 @@ npm antérieur à 11.16 exécute les scripts par défaut : `npm install -g novah
 Puis vérifiez :
 
 ```bash
-novahiz doctor   # Santé : 15 checks (17 avec --deep)
+novahiz doctor   # Santé : 17 checks (22 avec --deep)
 novahiz classify "fix the auth bug"
 ```
 
@@ -197,6 +197,8 @@ Huit catégories (`code`, `debug`, `browser`, `design-ui`, `database-supabase`,
 
 Clarify renvoie le travail au plan quand une réponse change l'architecture ; converge le renvoie aux tâches quand il trouve un écart. `flutter` et `expo` gardent les six mêmes étapes et insèrent leurs skills qualité autour d'implement. Le **tier** du classifier filtre la suite : `trivial` n'exécute presque rien, `lite` garde implement et converge, `full` parcourt toute la roadmap. Référence complète : [docs/ROADMAPS.md](docs/ROADMAPS.md).
 
+La roadmap `design-ui` porte en plus la couverture totale du playbook Impeccable : 23 étapes `skill` optionnelles couvrant l'intégralité des commandes officielles (`init`, `document`, `shape`, `critique`, ciblées `layout` → `generate`, `audit`, `harden`, `polish`, boucle `detect → verify`), avec les libellés des descriptions publiées sur [impeccable.style/cheatsheet](https://impeccable.style/cheatsheet). Elles forment une checklist pour l'agent ; l'application des règles design reste portée par `R14-impeccable`. `impeccable-live` est volontairement hors roadmap (session navigateur en direct, pas un chemin de code).
+
 ```mermaid
 flowchart LR
     subgraph "Fonctionnalité (code)"
@@ -310,7 +312,7 @@ Deux pièces complémentaires : la session consomme moins sans perdre en puissan
 
 ## Skills installées
 
-Novahiz livre 99 skills couvrant toutes les catégories :
+Novahiz livre 94 skills couvrant toutes les catégories — 46 dans le cœur du dépôt, les autres dans les packs officiels installés par défaut au setup :
 
 | Catégorie | Skills | Objectif |
 |-----------|--------|----------|
@@ -344,7 +346,9 @@ Novahiz auto-enregistre les serveurs MCP externes selon la catégorie du prompt
 | novahiz-scheduler | `mcp/clepsydre/index.mjs` (local, zéro dépendance) | Apache-2.0 | devops |
 | dart | `dart mcp-server` (Dart SDK) | BSD-3-Clause | code, debug, design-ui, flutter |
 
-Packs de skills (installés depuis les dépôts officiels, jamais vendorés) : `flutter/agent-plugins` (25 skills), `dart-lang/skills` (15 skills), `expo/skills` (19 skills, le groupe `expo-*` seulement ; les services payants `eas-*` exclus), `pbakaus/impeccable` (1 skill, la skill design upstream `impeccable`). Voir [docs/PROVIDERS.md](docs/PROVIDERS.md).
+Packs de skills (installés depuis les dépôts officiels, jamais vendorés, et livrés **par défaut** au setup via `providers.autoInstall`) : `flutter/agent-plugins` (10 skills), `dart-lang/skills` (15 skills), `expo/skills` (19 skills, le groupe `expo-*` seulement ; les services payants `eas-*` exclus), `pbakaus/impeccable` (1 skill, la skill design upstream `impeccable`).
+
+**`git` est requis** par le CLI officiel des skills : sans lui, l'installation des packs échoue silencieusement et les skills manquent au premier lancement. `novahiz doctor` le nomme (ligne `git (skill packs)`), et **`/novahiz-skills-update`** — ou `novahiz deps --install` — réinstalle proprement tous les packs depuis leurs providers officiels. Voir [docs/PROVIDERS.md](docs/PROVIDERS.md).
 
 Dépôts upstream et provenance complète des providers MCP et plugins opencode : [docs/PROVIDERS.md](docs/PROVIDERS.md), [docs/HARNESSES.md](docs/HARNESSES.md), [NOTICE.md](NOTICE.md).
 
@@ -374,7 +378,7 @@ Voir [docs/CONFIGURATION.md](docs/CONFIGURATION.md) pour toutes les options.
 | Commande | Objectif |
 |----------|----------|
 | `novahiz init` | Installation en une passe |
-| `novahiz doctor` | Diagnostic de santé 15-check (17 avec `--deep`) |
+| `novahiz doctor` | Diagnostic de santé 17-check (22 avec `--deep`) |
 | `novahiz status` | Classification + état du gate actuels |
 | `novahiz classify <text>` | Classer un prompt |
 | `novahiz gate` | Vérifier si une édition est autorisée |

package/dist/commands/upgrade.js

@@ -64,8 +64,12 @@ function readLocalVersion(root) {
         return "unknown";
     }
 }
-/** npm sous Windows est npm.cmd : spawnSync a besoin du shell, sinon ENOENT. */
-function runNpm(args, stdio) {
+/** npm sous Windows est npm.cmd : spawnSync a besoin du shell, sinon ENOENT.
+ *  `pipe` capture stdout/stderr (obligatoire pour `npm view` : `ignore`
+ *  retourne stdout=null et `latest` restait toujours vide), `inherit` pour
+ *  les sorties visibles de l'utilisateur (installation). Exporte pour le
+ *  test de regression. */
+export function runNpm(args, stdio) {
     const result = spawnSync("npm", args, {
         encoding: "utf8",
         stdio,
@@ -79,7 +83,7 @@ function runNpm(args, stdio) {
 }
 function npmFlow(parsed, root) {
     const local = readLocalVersion(root);
-    const view = runNpm(["view", "novahiz", "version"], "ignore");
+    const view = runNpm(["view", "novahiz", "version"], "pipe");
     if (view.status !== 0) {
         process.stderr.write(`novahiz upgrade: npm view failed (${view.stderr.trim() || `exit ${view.status}`}).\n`);
         process.exitCode = 1;

package/install/install.mjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-import { cpSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import {
   copyFileWithBackup,
   copyInto,
   defaultConfig,
+  deferOpencodePhase,
   detectedHarnesses,
+  findNpmAncestorPid,
   loadManifest,
   mergeBackups,
   mergeCreated,
@@ -21,6 +24,7 @@ import {
   saveManifest,
   skillNamesIn,
   spawnHost,
+  waitForDeferredPhase,
   which,
   writeJson
 } from "./lib.mjs";
@@ -65,6 +69,10 @@ const CORE_ITEMS = [
 async function main() {
   const flags = parseArgs(process.argv.slice(2));
   const dryRun = Boolean(flags["dry-run"]);
+  // Phase opencode rejetee hors du cycle de vie npm (voir lib.mjs) : sous
+  // postinstall, le passage synchronise n'ecrit plus que dans NOVAHIZ_HOME —
+  // jamais dans le dossier de config opencode que le serveur surveille.
+  const deferOpencode = deferOpencodePhase(flags);
   const force = Boolean(flags.force);
   const withSkills = !flags["no-skills"];
   const root = repoRoot(import.meta.url);
@@ -95,6 +103,42 @@ async function main() {
     }
   }
 
+  // Phase differee, spawn des le debut du postinstall : l'enfant attendra la
+  // mort de ce postinstall puis de npm avant d'ecrire quoi que ce soit dans
+  // la config opencode. Detache tot (detached + unref) : un redemarrage
+  // opencode qui tuerait npm ne l'atteint plus — la configuration rejoint
+  // alors la nouvelle version au lieu de rester bloquee a l'ancienne.
+  const deferLogPath = deferOpencode && !dryRun ? join(home, "install-deferred.log") : null;
+  if (deferLogPath) {
+    mkdirSync(home, { recursive: true });
+    const npmAncestor = findNpmAncestorPid();
+    const logFd = openSync(deferLogPath, "a");
+    // argv[1] du parent = ce meme script : l'enfant doit le recevoir, sinon
+    // node interprete --yes comme une option sienne ("bad option: --yes").
+    const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2), "--deferred-opencode"], {
+      // cwd = home, NOT the inherited package dir: a process whose cwd sits
+      // inside node_modules\novahiz makes any npm retire of that directory
+      // fail with EBUSY on Windows (that is what let the nested-update
+      // rollback restore the old package). The child lives for minutes, so
+      // it must never hold the package dir. Consequence: with an explicit
+      // `--scope project`, configDir resolves against home instead of the
+      // caller's cwd (postinstall never passes --scope).
+      cwd: home,
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: {
+        ...process.env,
+        NOVAHIZ_DEFERRED: "1",
+        NOVAHIZ_WAIT_PARENT_PID: String(process.pid),
+        NOVAHIZ_WAIT_PID: npmAncestor === null ? "" : String(npmAncestor),
+      },
+      windowsHide: true,
+    });
+    child.unref();
+    closeSync(logFd);
+    note(`Opencode config phase deferred (npm still running) - log: ${deferLogPath}`);
+  }
+
   const harnessDirs = { opencode: configDir };
   const harnessPackages = { opencode: "opencode-ai" };
   const detected = detectedHarnesses(harnessDirs);
@@ -184,7 +228,7 @@ async function main() {
     }
   }
 
-  if (!dryRun) {
+  if (!dryRun && !deferOpencode) {
     for (const name of configured) {
       if (!existsSync(harnessDirs[name])) mkdirSync(harnessDirs[name], { recursive: true });
     }
@@ -222,10 +266,14 @@ async function main() {
   }
 
   ui.step("Skills");
-  if (withSkills && !configured.includes("opencode")) {
+  if (deferOpencode) {
+    note("Opencode skills copy deferred to the post-npm phase.");
+    ui.finishStep("skip", "deferred");
+  }
+  if (!deferOpencode && withSkills && !configured.includes("opencode")) {
     note("Skipping opencode skills copy (opencode not selected).");
   }
-  if (withSkills && configured.includes("opencode")) {
+  if (!deferOpencode && withSkills && configured.includes("opencode")) {
     const skillsSource = existsSync(join(home, "skills")) ? join(home, "skills") : join(root, "skills");
     if (existsSync(skillsSource)) {
       // Dedup only against roots the catalog actually scans (see
@@ -272,10 +320,14 @@ async function main() {
   // du modele de config, une entree fichier y declenchait l'avertissement
   // "configured plugin path must be a directory" a chaque demarrage.
   ui.step("Plugin, agent & commands");
+  if (deferOpencode) {
+    note("Plugin, agent & commands deferred to the post-npm phase.");
+    ui.finishStep("skip", "deferred");
+  }
   for (const pluginFile of ["novahiz-plugin.ts", "novahiz-token-economy.ts"]) {
     const pluginSource = join(home, "adapters", "opencode", pluginFile);
     const pluginTarget = join(pluginsDir, pluginFile);
-    if (configured.includes("opencode") && existsSync(pluginSource)) {
+    if (!deferOpencode && configured.includes("opencode") && existsSync(pluginSource)) {
       note(`Installing opencode plugin in ${pluginTarget}`);
       if (!dryRun) {
         const result = copyFileWithBackup(pluginSource, pluginTarget, true);
@@ -289,7 +341,7 @@ async function main() {
     ? join(home, "adapters", "opencode", "agent", "novahiz.md")
     : join(root, "adapters", "opencode", "agent", "novahiz.md");
   const agentTarget = join(configDir, "agent", "novahiz.md");
-  if (configured.includes("opencode") && existsSync(agentSource)) {
+  if (!deferOpencode && configured.includes("opencode") && existsSync(agentSource)) {
     note(`Installing Novahiz agent in ${agentTarget}`);
     if (!dryRun) {
       const result = copyFileWithBackup(agentSource, agentTarget, true);
@@ -302,7 +354,7 @@ async function main() {
     ? join(home, "adapters", "opencode", "commands")
     : join(root, "adapters", "opencode", "commands");
   const commandsTarget = join(configDir, "commands");
-  if (configured.includes("opencode") && existsSync(commandsSource)) {
+  if (!deferOpencode && configured.includes("opencode") && existsSync(commandsSource)) {
     note(`Installing Novahiz commands in ${commandsTarget}`);
     if (!dryRun) {
       const result = copyInto(commandsSource, commandsTarget, true);
@@ -373,7 +425,9 @@ async function main() {
       env: { ...process.env, NOVAHIZ_HOME: home }
     });
     if (check.stdout) ui.raw(check.stdout);
-    if (autoInstall) {
+    if (autoInstall && deferOpencode) {
+      note("Dependency/provider install deferred to the post-npm phase (skills and commands write into the opencode config).");
+    } else if (autoInstall) {
       note("Installing dependencies and providers (MCP, skills, commands)");
       const result = spawnSync(process.execPath, [cli, "deps", "--install", "--yes"], {
         encoding: "utf8",
@@ -492,7 +546,9 @@ async function main() {
     { id: "flutter-skills", repo: "flutter/agent-plugins" },
     { id: "dart-skills", repo: "dart-lang/skills" },
   ];
-  if (!dryRun && flags["flutter-skills"]) {
+  if (!dryRun && flags["flutter-skills"] && deferOpencode) {
+    note("\nFlutter/Dart skill packs deferred to the post-npm phase.");
+  } else if (!dryRun && flags["flutter-skills"]) {
     note("\nInstalling official Flutter/Dart skill packs...");
     for (const pack of skillPacks) {
       note(`  ${pack.repo}...`);
@@ -540,7 +596,10 @@ async function main() {
   if (!configured.includes("opencode")) {
     note("Skipping opencode.jsonc (opencode not selected).");
   }
-  if (!dryRun && configured.includes("opencode")) {
+  if (!dryRun && deferOpencode && configured.includes("opencode")) {
+    note("\nopencode.jsonc generation deferred to the post-npm phase.");
+  }
+  if (!dryRun && !deferOpencode && configured.includes("opencode")) {
     const configPath = join(configDir, "opencode.jsonc");
     if (!existsSync(configPath)) {
       note(`\nCreating ${configPath}`);
@@ -682,19 +741,35 @@ async function main() {
 
   ui.step("Finalize");
   if (!dryRun) {
-    // Auto-update dependencies
+    // Auto-update dependencies (scoped to novahiz home, NEVER the global prefix).
+    //
+    // npm exports its config to lifecycle scripts (npm_config_*, envExport
+    // default true), so running under `npm install -g` leaks
+    // npm_config_global=true into this process. Without the explicit override
+    // below, `npm update` here silently becomes a SECOND reify of the global
+    // prefix while npm's own transaction is still open: its retire of
+    // node_modules\novahiz gets EBUSY (this process's cwd IS the package dir),
+    // the nested npm crashes, and arborist's rollback does
+    // rm(new) + rename(.novahiz-OLD -> novahiz) — the previous install comes
+    // back byte-for-byte with its original mtimes while the outer npm reports
+    // exit 0 / "changed 1 package". That is the "in-place install does not
+    // replace" bug. Forcing npm_config_global=false keeps this refresh in
+    // home (home/package.json), which shares no directory with the outer
+    // transaction. --ignore-scripts so nothing in home can re-enter the
+    // installer (home/package.json carries the postinstall script too).
     note("Checking for dependency updates...");
     const pkgPath = join(home, "package.json");
     if (existsSync(pkgPath)) {
+      const homeEnv = { ...process.env, NOVAHIZ_HOME: home, npm_config_global: "false" };
       const npmCheck = spawnHost("npm", ["outdated", "--json"], {
         cwd: home,
-        env: { ...process.env, NOVAHIZ_HOME: home }
+        env: homeEnv
       });
       if (npmCheck.stdout && npmCheck.stdout.trim().length > 2) {
         note("Updates available, installing...");
-        const npmUpdate = spawnHost("npm", ["update"], {
+        const npmUpdate = spawnHost("npm", ["update", "--ignore-scripts"], {
           cwd: home,
-          env: { ...process.env, NOVAHIZ_HOME: home }
+          env: homeEnv
         });
         if (npmUpdate.stdout) ui.raw(npmUpdate.stdout);
         if (npmUpdate.status !== 0 && npmUpdate.stderr) process.stderr.write(npmUpdate.stderr);
@@ -704,6 +779,7 @@ async function main() {
       }
     }
     const summary = [`Novahiz installed in ${home}.`];
+    if (deferLogPath) summary.push(`opencode config phase: deferred - see ${deferLogPath} (runs once npm exits).`);
     if (configured.length > 0) summary.push("Restart opencode to activate the plugin and MCP server.");
     summary.push("Gate can be disabled with the NOVAHIZ_GATE=off environment variable.");
     summary.push("Update anytime: `novahiz upgrade` (npm) or `/novahiz-upgrade` inside OpenCode.");
@@ -716,6 +792,14 @@ async function main() {
   }
 }
 
+// Entree de la phase differee (NOVAHIZ_DEFERRED=1) : on attend la mort du
+// postinstall puis de npm avant le moindre passage complet — pendant ce
+// temps, npm finalise sa transaction reify sans risque d'etre tue par un
+// redemarrage opencode.
+if (process.env.NOVAHIZ_DEFERRED === "1") {
+  await waitForDeferredPhase();
+}
+
 main().catch((error) => {
   process.stderr.write(`${String(error)}\n`);
   // postinstall (`npm install novahiz`) runs --dry-run: an unexpected crash

package/install/lib.d.mts

@@ -0,0 +1,90 @@
+// Declarations pour install/lib.mjs (module JS pur, consomme aussi par les
+// tests TypeScript). Garde le contrat en phase avec lib.mjs — toute change de
+// signature se reflete ici (typecheck = preuve que les deux coincident).
+import type { SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
+
+export interface BackupEntry {
+  path: string;
+  backup: string;
+}
+
+export interface CopyFileResult {
+  created: string | null;
+  backup: BackupEntry | null;
+}
+
+export interface CopyIntoResult {
+  created: string[];
+  backups: BackupEntry[];
+  total: number;
+}
+
+export interface NovahizManifest {
+  version?: string;
+  installedAt?: string;
+  harness?: string;
+  harnesses?: string[];
+  configDir?: string;
+  home?: string;
+  coreCopied?: boolean;
+  configCreated?: boolean;
+  created?: string[];
+  backups?: BackupEntry[];
+}
+
+export interface NovahizConfig {
+  dbPath: string;
+  skillRoots: string[];
+  gate: { enabled: boolean; mode: string; envEscape: string; tools: string[] };
+  classify: { minScore: number; maxCategories: number; fallbackCategory: string };
+  providers: { autoRegister: boolean; autoInstall: boolean; disabled: string[] };
+}
+
+export interface DeferredWaitOptions {
+  /** Cadence de sonde entre deux verifications de vie (defaut 2000 ms). */
+  pollMs?: number;
+  /** Plafond inclusif par pid (defaut 10 min) : la fonction rend toujours la main. */
+  timeoutMs?: number;
+  /** Patience fixe quand npm n'a pas pu etre identifie (defaut 30000 ms). */
+  graceMs?: number;
+  /** Sonde de vie injectable pour les tests (defaut pidAlive). */
+  isAlive?: (pid: number) => boolean;
+  log?: (message: string) => void;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export declare function parseArgs(argv: string[]): Record<string, string | boolean>;
+export declare function expandHome(value: string): string;
+export declare function repoRoot(metaUrl: string): string;
+export declare function opencodeConfigDir(env?: NodeJS.ProcessEnv): string;
+export declare function NovahizHome(flags?: Record<string, unknown>, env?: NodeJS.ProcessEnv): string;
+export declare function listFiles(root: string): string[];
+export declare function skillNamesIn(roots: string[]): Set<string>;
+export declare function copyFileWithBackup(srcPath: string, destPath: string, useBackup?: boolean): CopyFileResult;
+export declare function copyInto(srcDir: string, destDir: string, useBackup?: boolean): CopyIntoResult;
+export declare function readJson(path: string): unknown;
+export declare function readJson<T>(path: string, fallback: T): T;
+export declare function writeJson(path: string, value: unknown): void;
+export declare function playwrightBrowserFlag(platform?: string): string;
+export declare function defaultConfig(): NovahizConfig;
+export declare function loadManifest(home: string): NovahizManifest;
+export declare function unsafeHostToken(tokens: string[]): string | null;
+export declare function spawnHost(cmd: string, args: string[], opts?: SpawnSyncOptions): SpawnSyncReturns<string>;
+export declare function saveManifest(home: string, manifest: NovahizManifest): void;
+export declare function mergeCreated(previous?: string[], next?: string[]): string[];
+export declare function mergeBackups(previous?: BackupEntry[], next?: BackupEntry[]): BackupEntry[];
+export declare function pruneEmptyDirs(paths: string[], stops?: string[]): void;
+export declare function detectedHarnesses(dirs: Record<string, string>, whichFn?: (cmd: string) => boolean): string[];
+export declare function which(cmd: string): boolean;
+export declare function nodeVersionOk(minimum?: [number, number, number]): boolean;
+
+// --- Phase opencode differee (postinstall npm) ------------------------------
+export declare function deferOpencodePhase(flags?: Record<string, unknown>, env?: NodeJS.ProcessEnv): boolean;
+export declare function parsePid(value: unknown): number | null;
+export declare function pidAlive(pid: number): boolean;
+export declare function findNpmAncestorPid(startPid?: number): number | null;
+export declare function waitForPids(
+  pids: ReadonlyArray<number | null | undefined>,
+  opts?: DeferredWaitOptions,
+): Promise<void>;
+export declare function waitForDeferredPhase(env?: NodeJS.ProcessEnv, opts?: DeferredWaitOptions): Promise<void>;

package/install/lib.mjs

@@ -319,3 +319,150 @@ export function nodeVersionOk(minimum = [22, 18, 0]) {
   }
   return true;
 }
+
+// --- Phase opencode differee (postinstall npm) ------------------------------
+//
+// Bug reproduit le 2026-10-10 (enquete npm, memoire slot-005) : quand
+// install.mjs tourne comme script postinstall, ses ecritures dans le dossier
+// de config opencode (skills, plugin, agent, commands, opencode.jsonc) font
+// redemarrer le serveur opencode, qui tue alors son arbre de processus —
+// npm compris, encore en pleine transaction reify. Le remplacement en place
+// est interrompu : rollback vers l'ancien paquet (version et mtimes
+// preserves a la milliseconde) ou dossiers .novahiz-* orphelins.
+//
+// Le correctif se pose sur deux piliers :
+//   1. la phase opencode part en processus detache (detached + unref) qui
+//      attend la mort du postinstall puis de npm avant la moindre ecriture —
+//      un redemarrage opencode arrive alors que la transaction est finie ;
+//   2. le passage synchronise ne touche plus qu'au NOVAHIZ_HOME, seule zone
+//      jamais observee comme declencheur lors des trois kills reproduits.
+
+const deferDefaultLog = (message) => process.stdout.write(`${message}\n`);
+const deferSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * La phase opencode doit-elle sortir du cycle de vie npm ?
+ *
+ * - `npm_lifecycle_event` present (postinstall) -> oui, sauf :
+ * - `--deferred-opencode` / `NOVAHIZ_DEFERRED=1` (le passage detache
+ *   lui-meme) -> non : la phase deferree ne se defererait pas a l'infini ;
+ * - `--sync` (repli d'urgence vers l'ancien comportement) -> non ;
+ * - hors npm (novahiz-install direct, bootstrap CLI) -> non : le
+ *   comportement historique entierement synchrone est conserve.
+ */
+export function deferOpencodePhase(flags = {}, env = process.env) {
+  if (flags.sync === true) return false;
+  if (flags["deferred-opencode"] === true) return false;
+  if (env.NOVAHIZ_DEFERRED === "1") return false;
+  return Boolean(env.npm_lifecycle_event);
+}
+
+/** pid utilisable : entier strictement positif, sinon null. */
+export function parsePid(value) {
+  const pid = Number.parseInt(String(value ?? ""), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+/** Le processus existe-t-il encore ? EPERM = oui (proprietaire different). */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return Boolean(error) && error.code === "EPERM";
+  }
+}
+
+/**
+ * PID du processus npm de l'installation en cours : on remonte la chaine des
+ * ParentProcessId jusqu'au premier ancetre dont la ligne de commande
+ * reference `npm-cli.js`. Le chemin de notre propre processus contient bien
+ * `\npm\` (paquet installe globalement dans Roaming\npm), jamais
+ * `npm-cli.js` : le filtre ne peut pas se retenir lui-meme.
+ * null = pas de npm au-dessus (ou plateforme non interrogeable) — l'appelant
+ * bascule alors sur une patience fixe.
+ */
+export function findNpmAncestorPid(startPid = process.pid) {
+  if (process.platform === "win32") {
+    const script =
+      `$cur = Get-CimInstance Win32_Process -Filter "ProcessId=${startPid}"; ` +
+      "while ($cur) { " +
+      "if ($cur.CommandLine -and $cur.CommandLine -match 'npm-cli\\.js') { Write-Output $cur.ProcessId; break }; " +
+      "if (-not $cur.ParentProcessId -or $cur.ParentProcessId -eq $cur.ProcessId) { break }; " +
+      "$cur = Get-CimInstance Win32_Process -Filter \"ProcessId=$($cur.ParentProcessId)\" -ErrorAction SilentlyContinue; " +
+      "}";
+    const result = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8" });
+    if (result.status === 0) {
+      const pid = parsePid((result.stdout ?? "").trim());
+      if (pid !== null && pid !== startPid) return pid;
+    }
+    return null;
+  }
+  const result = spawnSync("ps", ["-o", "pid=", "-o", "ppid=", "-o", "command=", "-ax"], { encoding: "utf8" });
+  if (result.status !== 0) return null;
+  const rows = new Map();
+  for (const line of String(result.stdout ?? "").split("\n")) {
+    const match = line.trim().match(/^(\d+)\s+(\d+)\s+([\s\S]*)$/);
+    if (match) rows.set(Number.parseInt(match[1], 10), { ppid: Number.parseInt(match[2], 10), cmd: match[3] });
+  }
+  let current = startPid;
+  const seen = new Set();
+  while (current && rows.has(current) && !seen.has(current)) {
+    seen.add(current);
+    const row = rows.get(current);
+    if (current !== startPid && /npm-cli\.js/.test(row.cmd)) return current;
+    current = row.ppid;
+  }
+  return null;
+}
+
+/**
+ * Attend la mort de chaque pid (cadence pollMs, plafond timeoutMs par pid).
+ * Le plafond est inclusif : la fonction rend TOUJOURS la main — un pid
+ * rebelle ne doit jamais bloquer la phase differee indefiniment.
+ */
+export async function waitForPids(pids, opts = {}) {
+  const pollMs = opts.pollMs ?? 2000;
+  const timeoutMs = opts.timeoutMs ?? 10 * 60 * 1000;
+  const isAlive = opts.isAlive ?? pidAlive;
+  const log = opts.log ?? deferDefaultLog;
+  const wait = opts.sleep ?? deferSleep;
+  for (const pid of pids) {
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    if (!isAlive(pid)) {
+      log(`novahiz defer: pid ${pid} already exited`);
+      continue;
+    }
+    const deadline = Date.now() + timeoutMs;
+    log(`novahiz defer: waiting for pid ${pid} to exit...`);
+    while (isAlive(pid)) {
+      if (Date.now() >= deadline) {
+        log(`novahiz defer: pid ${pid} still alive after ${timeoutMs}ms - proceeding anyway`);
+        break;
+      }
+      await wait(pollMs);
+    }
+  }
+}
+
+/**
+ * Entree de la phase differee : attend que le postinstall (notre createur)
+ * ET npm soient sortis avant d'ecrire la moindre chose, puis rend la main.
+ * npm non identifie (chaine d'ancetres atypique, pnpm...) -> patience fixe :
+ * npm sort quelques secondes apres la fin du script de lifecycle.
+ */
+export async function waitForDeferredPhase(env = process.env, opts = {}) {
+  const log = opts.log ?? deferDefaultLog;
+  const wait = opts.sleep ?? deferSleep;
+  const parentPid = parsePid(env.NOVAHIZ_WAIT_PARENT_PID);
+  const npmPid = parsePid(env.NOVAHIZ_WAIT_PID);
+  log(`novahiz defer: opencode phase detached - parent ${parentPid ?? "(none)"}, npm ${npmPid ?? "(unknown)"}`);
+  await waitForPids(parentPid === null ? [] : [parentPid], opts);
+  if (npmPid !== null) {
+    await waitForPids([npmPid], opts);
+  } else {
+    await wait(opts.graceMs ?? 30000);
+  }
+  log("novahiz defer: npm exited - running the full pass (opencode config included)");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novahiz",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Enforce AI agent skills before every file edit: prompt classifier, skill catalog, and pre-edit gate.",
   "type": "module",
   "license": "Apache-2.0",

package/src/commands/upgrade.ts

@@ -71,8 +71,12 @@ function readLocalVersion(root: string): string {
   }
 }
 
-/** npm sous Windows est npm.cmd : spawnSync a besoin du shell, sinon ENOENT. */
-function runNpm(args: string[], stdio: "inherit" | "ignore"): { status: number; stdout: string; stderr: string } {
+/** npm sous Windows est npm.cmd : spawnSync a besoin du shell, sinon ENOENT.
+ *  `pipe` capture stdout/stderr (obligatoire pour `npm view` : `ignore`
+ *  retourne stdout=null et `latest` restait toujours vide), `inherit` pour
+ *  les sorties visibles de l'utilisateur (installation). Exporte pour le
+ *  test de regression. */
+export function runNpm(args: string[], stdio: "inherit" | "pipe"): { status: number; stdout: string; stderr: string } {
   const result = spawnSync("npm", args, {
     encoding: "utf8",
     stdio,
@@ -87,7 +91,7 @@ function runNpm(args: string[], stdio: "inherit" | "ignore"): { status: number;
 
 function npmFlow(parsed: Parsed, root: string): void {
   const local = readLocalVersion(root);
-  const view = runNpm(["view", "novahiz", "version"], "ignore");
+  const view = runNpm(["view", "novahiz", "version"], "pipe");
   if (view.status !== 0) {
     process.stderr.write(`novahiz upgrade: npm view failed (${view.stderr.trim() || `exit ${view.status}`}).\n`);
     process.exitCode = 1;