@ijfw/install 1.5.4 → 1.5.5

package/README.md

@@ -1,92 +1,60 @@
-# @ijfw/install
+# @ijfw/install — One-command installer for IJFW
 
-One-command installer for [IJFW](https://gitlab.com/therealseandonahoe/ijfw) -- the AI
-efficiency layer for 15 AI coding agents: Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, Qwen Code, Cline, Kimi Code, OpenClaw, Antigravity, and Aider.
+> Ferrox Labs · Local-first infrastructure for AI coding agents
+
+IJFW is Ferrox Labs' shared development infrastructure for AI-driven teams — shared memory across projects, smart model routing, cross-AI adversarial audits (Trident: Claude + Codex + Gemini in parallel), and a disciplined think-build-ship workflow. v1.5.5 closed 60 audit findings in a single milestone. This package wires it onto every AI coding agent on your machine.
+
+Full docs: [github.com/FerroxLabs/ijfw](https://github.com/FerroxLabs/ijfw)
+
+## Table of contents
+
+- [Install](#install)
+- [What it does](#what-it-does)
+- [Options](#options)
+- [Uninstall](#uninstall)
+- [Links](#links)
 
 ## Install
 
 ```bash
 npm install -g @ijfw/install
-ijfw demo
+ijfw install
 ```
 
-IJFW configures every agent on your machine. The options below let you customize the install location, branch, or skip specific steps -- all are optional.
+If no AI agents are detected, install Claude Code or Codex first, then re-run.
+
+## What it does
 
-### Options
+- Installs the IJFW source tree at `~/.ijfw/`
+- Wires the MCP server into 14 platforms via their config files
+- Adds Aider as a rules-only tier — 15 agents supported total
+- Sets up shared memory at `~/.ijfw/memory/` (plain markdown hot, SQLite FTS5 warm, optional vectors cold)
+- Runs an 8-gate preflight before declaring done
+
+## Options
 
 | Flag | Default | Notes |
 |------|---------|-------|
 | `--dir <path>` | `$IJFW_HOME` or `~/.ijfw` | Install location |
 | `--branch <name>` | latest released tag | Git branch or tag |
-| `--no-marketplace` | off | Skip settings.json edits |
-| `--yes` | off | Non-interactive |
+| `--no-marketplace` | enabled | Skip settings.json edits |
+| `--yes` | interactive | Non-interactive run |
 
-### Uninstall
+## Uninstall
 
 ```bash
 ijfw uninstall          # preserves ~/.ijfw/memory/
 ijfw uninstall --purge  # removes memory too
 ```
 
-If `ijfw` isn't on your PATH (e.g. you uninstalled the global `@ijfw/install`
-package already), invoke the bin directly:
+If `ijfw` is no longer on your PATH, invoke the bin directly:
 
 ```bash
 npx -p @ijfw/install ijfw-uninstall
 ```
 
-Memory is preserved across re-runs by default.
-
-## Preflight
-
-Requires `node >=18` and `git` (used for the initial repo clone). The
-installer is Node-native end to end -- no bash, no WSL, no Git for Windows
-shell. On native Windows use the PowerShell installer (PS 5.1+), which
-delegates to Node directly:
-
-```powershell
-iwr https://gitlab.com/therealseandonahoe/ijfw/-/raw/main/installer/src/install.ps1 -OutFile install.ps1
-.\install.ps1 -Dir $env:USERPROFILE\.ijfw
-```
-
-## Extension CLI
-
-IJFW ships a full extension system for installing and sandboxing third-party skills.
-
-```bash
-# Publisher key management
-ijfw extension keygen <author>              # Generate an Ed25519 publisher keypair
-ijfw extension trust <keyId> <publicKey>   # Add a publisher to your trusted store
-ijfw extension trust-registry [<url>]      # Pull + apply the hosted publisher registry
-ijfw extension untrust <keyId>             # Remove a publisher from your trusted store
-ijfw extension trusted                     # List all trusted publishers
-
-# Extension lifecycle
-ijfw extension add <source> [flags]        # Install an extension (npm name, local path, or https git URL)
-  --allow-unsigned                         #   Accept extensions with no signature
-  --accept-untrusted                       #   Accept extensions signed by an untrusted publisher (prompts on TTY)
-  --activate                               #   Auto-activate after install
-ijfw extension activate <name>             # Activate an installed extension (enforces declared permissions)
-ijfw extension deactivate                  # Deactivate the current extension
-
-# Admin / registry maintainer (rare)
-ijfw extension rotate-keys <oldKeyId> <newKeyId>   # Produce a signed rotation token
-ijfw extension keygen-meta <author>                # Generate the registry meta-keypair
-ijfw extension sign-registry <path>                # Sign a registry JSON file in place
-ijfw extension verify-registry <path>              # Verify a registry JSON signature
-ijfw extension registry-status                     # Show registry cache age + signature status
-```
-
-The rotation flow and registry maintainer docs live in `docs/REGISTRY-MAINTAINER.md`.
-
-## Build (contributors)
-
-```bash
-cd installer
-npm install
-npm run build   # outputs dist/install.js + dist/uninstall.js
-npm test
-npm run pack:check
-```
+## Links
 
-Tarball target: **<100 KB**.
+- Source, issues, and docs: [github.com/FerroxLabs/ijfw](https://github.com/FerroxLabs/ijfw)
+- npm package: [@ijfw/install](https://www.npmjs.com/package/@ijfw/install)
+- License: MIT

package/dist/hub-index-snippet.json

@@ -1,14 +1,14 @@
 {
   "name": "ijfw",
   "displayName": "IJFW — AI Efficiency Layer",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "One install, every AI coding agent, zero config. Unifies 15 CLIs under a shared MCP memory layer so context follows you across Claude, Codex, Gemini, Cursor, Windsurf, and 10 more.",
   "author": "Sean Donahoe",
   "icon": "assets/ijfw-logo.svg",
   "dist": {
-    "tarball": "extensions/ijfw-1.5.4.zip",
-    "integrity": "sha512-VzLLJg/kN1vP4kp6uSe26PJi92JoxT0rgLyulG7JLFuqr9AetZKIQBSBD/d4qWMP5q0k7Mn0J4eI7uZl27pfFw==",
-    "unpackedSize": 3205
+    "tarball": "extensions/ijfw-1.5.5.zip",
+    "integrity": "sha512-vm3ot0+GhXYy0/HcStB/xmFjZhSXWG7jzSLuIPe43/Dla8qhyR9gsCwBI/8+RsUJqMXiPgc0GuxrgwW2f5DDWA==",
+    "unpackedSize": 3312
   },
   "engines": {
     "wayland": ">=0.6.0"

package/dist/ijfw.js

@@ -2110,7 +2110,7 @@ __export(upgrade_smoke_exports, {
   severity: () => severity11
 });
 import { spawnSync as spawnSync11 } from "node:child_process";
-import { mkdtempSync as mkdtempSync3, rmSync as rmSync3, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5, readFileSync as readFileSync4, existsSync as existsSync4 } from "node:fs";
+import { mkdtempSync as mkdtempSync3, rmSync as rmSync3, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5, readFileSync as readFileSync4, existsSync as existsSync4, cpSync } from "node:fs";
 import { join as join10, resolve as resolve2 } from "node:path";
 import { tmpdir as tmpdir3 } from "node:os";
 async function run11(ctx) {
@@ -2199,30 +2199,94 @@ async function run11(ctx) {
         durationMs: Date.now() - t0
       };
     }
-    const settingsPath = join10(claudeDir, "settings.json");
-    if (existsSync4(settingsPath)) {
-      let settings;
-      try {
-        settings = JSON.parse(readFileSync4(settingsPath, "utf8"));
-      } catch (e) {
-        return {
-          name: "upgrade-smoke",
-          status: "FAIL",
-          message: "upgrade-smoke: settings.json is not valid JSON",
-          details: [e.message],
-          durationMs: Date.now() - t0
-        };
+    const targetIjfwHome = join10(fakeHome, ".ijfw");
+    mkdirSync4(targetIjfwHome, { recursive: true });
+    for (const sub of ["claude", "mcp-server"]) {
+      const src = join10(ctx.repoRoot, sub);
+      if (existsSync4(src)) {
+        cpSync(src, join10(targetIjfwHome, sub), { recursive: true });
       }
-      const hasWrongKey = JSON.stringify(settings).includes("ijfw-core");
-      if (hasWrongKey) {
-        return {
-          name: "upgrade-smoke",
-          status: "FAIL",
-          message: 'upgrade-smoke: settings.json still uses deprecated "ijfw-core" key',
-          details: [`Found "ijfw-core" in: ${settingsPath}`],
-          durationMs: Date.now() - t0
-        };
+    }
+    const installerPkgSrc = join10(ctx.repoRoot, "installer", "package.json");
+    if (existsSync4(installerPkgSrc)) {
+      mkdirSync4(join10(targetIjfwHome, "installer"), { recursive: true });
+      cpSync(installerPkgSrc, join10(targetIjfwHome, "installer", "package.json"));
+    }
+    const runInstaller = spawnSync11(installerBin, ["--yes"], {
+      encoding: "utf8",
+      cwd: installDir,
+      timeout: 12e4,
+      env: {
+        ...cleanEnv,
+        HOME: fakeHome,
+        USERPROFILE: fakeHome,
+        IJFW_HOME: targetIjfwHome,
+        // Hermetic: install.js refuses any network attempt under this flag
+        // (TR-001). The gate's contract is "the installer either completes
+        // without network or fails clearly". The marketplace merge step
+        // (which is what we actually want to verify) does NOT need network.
+        CI: "1",
+        IJFW_SKIP_NETWORK: "1"
+      },
+      shell: process.platform === "win32"
+    });
+    if (runInstaller.status !== 0 || runInstaller.signal) {
+      const stderrLines = (runInstaller.stderr || "").split("\n").filter(Boolean);
+      const lastStderrLine = stderrLines.length > 0 ? stderrLines[stderrLines.length - 1].slice(0, 200) : "(no stderr)";
+      let cat;
+      if (runInstaller.signal) {
+        cat = `killed by ${runInstaller.signal}`;
+      } else if (runInstaller.status === 137 || runInstaller.status === 124) {
+        cat = `timed out (exit ${runInstaller.status})`;
+      } else if (runInstaller.status === null) {
+        cat = "timed out (status null)";
+      } else {
+        cat = `exited ${runInstaller.status}`;
       }
+      return {
+        name: "upgrade-smoke",
+        status: "FAIL",
+        message: `upgrade-smoke: installer ${cat}. Last stderr line: ${lastStderrLine}`,
+        details: ((runInstaller.stdout || "") + (runInstaller.stderr || "")).split("\n").filter(Boolean).slice(0, 15),
+        durationMs: Date.now() - t0
+      };
+    }
+    const settingsPath = join10(claudeDir, "settings.json");
+    if (!existsSync4(settingsPath)) {
+      return {
+        name: "upgrade-smoke",
+        status: "FAIL",
+        message: "upgrade-smoke: installer did not write ~/.claude/settings.json",
+        details: [
+          `expected: ${settingsPath}`,
+          "The installer ran (exit 0) but the marketplace merge never produced settings.json.",
+          "This is the false-pass shape TR-001 retired \u2014 the gate must observe the write.",
+          ...((runInstaller.stdout || "") + (runInstaller.stderr || "")).split("\n").filter(Boolean).slice(0, 8)
+        ],
+        durationMs: Date.now() - t0
+      };
+    }
+    let settings;
+    try {
+      settings = JSON.parse(readFileSync4(settingsPath, "utf8"));
+    } catch (e) {
+      return {
+        name: "upgrade-smoke",
+        status: "FAIL",
+        message: "upgrade-smoke: settings.json is not valid JSON",
+        details: [e.message],
+        durationMs: Date.now() - t0
+      };
+    }
+    const hasWrongKey = JSON.stringify(settings).includes("ijfw-core");
+    if (hasWrongKey) {
+      return {
+        name: "upgrade-smoke",
+        status: "FAIL",
+        message: 'upgrade-smoke: settings.json still uses deprecated "ijfw-core" key',
+        details: [`Found "ijfw-core" in: ${settingsPath}`],
+        durationMs: Date.now() - t0
+      };
     }
     const marketplaceSrc = join10(installerDir, "src", "marketplace.js");
     if (existsSync4(marketplaceSrc)) {

package/dist/install.js

@@ -73,20 +73,44 @@ function writeAtomic(path3, contents, opts = {}) {
   }
 }
 function backup(path3, ts) {
+  const res = backupDetailed(path3, ts);
+  return res.ok && res.path ? res.path : null;
+}
+function backupDetailed(path3, ts) {
+  let st;
   try {
-    const st = statSync(path3);
-    if (!st.isFile()) return null;
-  } catch {
-    return null;
+    st = statSync(path3);
+  } catch (err) {
+    if (err && err.code === "ENOENT") return { ok: true, path: null, reason: "absent" };
+    return { ok: false, reason: "stat-failed", error: err };
+  }
+  if (!st.isFile()) {
+    return { ok: true, path: null, reason: "not-a-file" };
   }
   const dst = `${path3}.bak.${ts}`;
   try {
     copyFileSync(path3, dst);
     printInfo(`backup: ${basename(path3)}.bak.${ts}`);
-    return dst;
-  } catch {
+    return { ok: true, path: dst };
+  } catch (err) {
+    return { ok: false, reason: "copy-failed", error: err };
+  }
+}
+function requireBackup(path3, ts) {
+  if (!ts) return null;
+  const res = backupDetailed(path3, ts);
+  if (res.ok) return res.path;
+  if (process.env.IJFW_FORCE_NO_BACKUP === "1") {
+    const why2 = res.error && res.error.message ? res.error.message : res.reason;
+    printInfo(`backup: forced past failure for ${basename(path3)} (${why2})`);
     return null;
   }
+  const why = res.error && res.error.message ? res.error.message : res.reason;
+  const err = new Error(
+    `Refusing to merge into existing config without backup: ${path3} (${why}). Re-run with IJFW_FORCE_NO_BACKUP=1 to proceed.`
+  );
+  err.code = "BACKUP_REQUIRED";
+  throw err;
 }
 function safeChecksum(path3) {
   try {
@@ -244,7 +268,7 @@ function readJsonOrEmpty(path3) {
 }
 function mergeJson(dst, serverJs, ts) {
   mkdirSync2(dirname3(dst), { recursive: true });
-  if (ts) backup(dst, ts);
+  requireBackup(dst, ts);
   const doc = readJsonOrEmpty(dst);
   if (!doc.mcpServers || typeof doc.mcpServers !== "object") doc.mcpServers = {};
   const isWin = IS_WIN;
@@ -272,7 +296,7 @@ function mergeJson(dst, serverJs, ts) {
 }
 function mergeToml(dst, serverJs, ts) {
   mkdirSync2(dirname3(dst), { recursive: true });
-  if (ts) backup(dst, ts);
+  requireBackup(dst, ts);
   let text = "";
   try {
     text = existsSync3(dst) ? readFileSync2(dst, "utf8") : "";
@@ -560,7 +584,8 @@ import {
   statSync as statSync2,
   copyFileSync as copyFileSync2,
   cpSync,
-  chmodSync as chmodSync2
+  chmodSync as chmodSync2,
+  rmSync
 } from "node:fs";
 import { join as join4, dirname as dirname4, isAbsolute } from "node:path";
 import { platform } from "node:os";
@@ -935,10 +960,31 @@ async function installWayland(ctx) {
     const pluginDst = join4(ctx.home, ".wayland", "plugins", "ijfw");
     ensureDir(pluginDst);
     let entries;
+    let readdirErr = null;
     try {
       entries = readdirSync(pluginSrc);
-    } catch {
+    } catch (err) {
       entries = [];
+      readdirErr = err;
+    }
+    if (readdirErr) {
+      ctx.log.warn(`Wayland plugin tree readdir failed: ${readdirErr.message || readdirErr}`);
+    }
+    const srcNames = new Set(entries.filter((n) => n !== "__pycache__"));
+    let dstEntries = [];
+    try {
+      dstEntries = readdirSync(pluginDst);
+    } catch {
+    }
+    for (const name of dstEntries) {
+      if (name === "__pycache__") continue;
+      if (!srcNames.has(name)) {
+        try {
+          rmSync(join4(pluginDst, name), { recursive: true, force: true });
+        } catch (err) {
+          ctx.log.warn(`Wayland plugin: could not remove stale ${name}: ${err.message || err}`);
+        }
+      }
     }
     for (const name of entries) {
       if (name === "__pycache__") continue;
@@ -986,10 +1032,31 @@ async function installHermes(ctx) {
     const pluginDst = join4(ctx.home, ".hermes", "plugins", "ijfw");
     ensureDir(pluginDst);
     let entries;
+    let readdirErr = null;
     try {
       entries = readdirSync(pluginSrc);
-    } catch {
+    } catch (err) {
       entries = [];
+      readdirErr = err;
+    }
+    if (readdirErr) {
+      ctx.log.warn(`Hermes plugin tree readdir failed: ${readdirErr.message || readdirErr}`);
+    }
+    const srcNames = new Set(entries.filter((n) => n !== "__pycache__"));
+    let dstEntries = [];
+    try {
+      dstEntries = readdirSync(pluginDst);
+    } catch {
+    }
+    for (const name of dstEntries) {
+      if (name === "__pycache__") continue;
+      if (!srcNames.has(name)) {
+        try {
+          rmSync(join4(pluginDst, name), { recursive: true, force: true });
+        } catch (err) {
+          ctx.log.warn(`Hermes plugin: could not remove stale ${name}: ${err.message || err}`);
+        }
+      }
     }
     for (const name of entries) {
       if (name === "__pycache__") continue;
@@ -1181,18 +1248,27 @@ function installOpenclaw(ctx) {
   }
   const dst = path.join(ctx.home, ".openclaw", "openclaw.json");
   const serverJs = ctx.serverJsNative || ctx.serverJs;
+  let cliRegistered = false;
   if (commandExists("openclaw")) {
     try {
       const payload = JSON.stringify({ command: "node", args: [serverJs] });
-      execFileSync("openclaw", ["mcp", "set", "ijfw-memory", payload], { stdio: "ignore" });
-      printOk(`Registered ijfw-memory via 'openclaw mcp set' (${dst})`);
-      return { status: "ok" };
-    } catch {
+      execFileSync("openclaw", ["mcp", "set", "ijfw-memory", payload], {
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8"
+      });
+      cliRegistered = true;
+    } catch (err) {
+      const msg = err && err.stderr ? String(err.stderr).trim() : err && err.message || String(err);
+      printInfo(`openclaw CLI registration failed (${msg}); falling back to file-write merge.`);
     }
   }
   ensureDir2(path.dirname(dst));
   openclawMerge(dst, serverJs);
-  printOk(`Merged MCP into ${dst} (openclaw mcp.servers schema)`);
+  if (cliRegistered) {
+    printOk(`Registered ijfw-memory via 'openclaw mcp set' AND file-write merge (${dst})`);
+  } else {
+    printOk(`Merged MCP into ${dst} (openclaw mcp.servers schema)`);
+  }
   return { status: "ok" };
 }
 function installAider(ctx) {
@@ -1294,6 +1370,14 @@ function linkPlugin({ repoRoot, ijfwHome, ts }) {
         } catch {
         }
       } else if (st.isDirectory()) {
+        try {
+          fs2.rmSync(pluginDst, { recursive: true, force: true });
+        } catch (err) {
+          process.stderr.write(
+            `[ijfw] linkPlugin: could not clear ${pluginDst} for mirror (${err && err.message ? err.message : err}); falling back to merge.
+`
+          );
+        }
         fs2.cpSync(pluginSrc, pluginDst, { recursive: true });
         printOk(`Plugin tree mirrored to ${pluginDst}`);
         return;
@@ -1369,12 +1453,20 @@ function seedState({ ijfwHome, repoRoot, nodeBin: _nodeBin }) {
     }
   } catch {
   }
-  let installedVer = "0.0.0";
+  const pkgPath = path2.join(repoRoot, "installer", "package.json");
+  let installedVer;
   try {
-    const pkgPath = path2.join(repoRoot, "installer", "package.json");
     const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf8"));
-    installedVer = pkg.version || "0.0.0";
-  } catch {
+    installedVer = pkg.version;
+  } catch (err) {
+    throw new Error(
+      `Preflight: installer/package.json missing or unreadable at ${pkgPath} (${err && err.message ? err.message : err}). Repo tree incomplete; rerun bootstrap from a clean clone.`
+    );
+  }
+  if (!installedVer || typeof installedVer !== "string") {
+    throw new Error(
+      `Preflight: installer/package.json at ${pkgPath} has no usable "version" field. Rerun bootstrap from a clean clone.`
+    );
   }
   const nowTs = Math.floor(Date.now() / 1e3);
   const state = {
@@ -1484,7 +1576,14 @@ function patchPluginMcpJson({ ijfwHome, repoRoot, nodeBin, serverJs }) {
   d.mcpServers["ijfw-memory"].command = nodeBin;
   d.mcpServers["ijfw-memory"].args = [serverJs];
   const envSep = process.platform === "win32" ? ";" : ":";
-  const commonPaths = process.platform === "win32" ? [nodeDir, "C:\\Windows\\System32"] : [nodeDir, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+  let commonPaths;
+  if (process.platform === "win32") {
+    commonPaths = [nodeDir, "C:\\Windows\\System32"];
+  } else if (process.platform === "darwin") {
+    commonPaths = [nodeDir, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+  } else {
+    commonPaths = [nodeDir, "/usr/local/bin", "/usr/bin", "/bin"];
+  }
   const dedup = [...new Set(commonPaths.filter((x) => x && fs2.existsSync(x)))];
   d.mcpServers["ijfw-memory"].env = { PATH: dedup.join(envSep) };
   try {
@@ -1857,7 +1956,7 @@ var init_install_flow = __esm({
 
 // src/install.js
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync5, rmSync, mkdirSync as mkdirSync4, realpathSync as realpathSync2, renameSync as renameSync3 } from "node:fs";
+import { existsSync as existsSync5, rmSync as rmSync2, mkdirSync as mkdirSync4, realpathSync as realpathSync2, renameSync as renameSync3, readdirSync as readdirSync2, cpSync as cpSync2 } from "node:fs";
 import { resolve as resolve4, join as join5, dirname as dirname5 } from "node:path";
 import { homedir as homedir3, platform as platform2 } from "node:os";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
@@ -2017,7 +2116,7 @@ function triggerColdScan(projectRoot, options = {}) {
 }
 
 // src/install.js
-var DEFAULT_REPO = "https://gitlab.com/therealseandonahoe/ijfw.git";
+var DEFAULT_REPO = "https://github.com/FerroxLabs/ijfw.git";
 var DEFAULT_BRANCH = "main";
 function parseArgs(argv) {
   const out = { yes: false, dir: null, noMarketplace: false, branch: DEFAULT_BRANCH, branchExplicit: false, purge: false };
@@ -2037,7 +2136,11 @@ function parseArgs(argv) {
   }
   return out;
 }
+function skipNetwork() {
+  return process.env.IJFW_SKIP_NETWORK === "1";
+}
 function latestTagFromGithub() {
+  if (skipNetwork()) return null;
   try {
     const res = spawnSync2("git", ["ls-remote", "--tags", "--refs", "--sort=-v:refname", DEFAULT_REPO], {
       encoding: "utf8",
@@ -2051,7 +2154,7 @@ function latestTagFromGithub() {
     return null;
   }
 }
-function resolveBranchOrTag({ branch, branchExplicit, _tagLookup } = {}) {
+function resolveBranchOrTag({ branch, branchExplicit, _tagLookup, _logger } = {}) {
   if (branchExplicit) return branch;
   const lookup = _tagLookup || latestTagFromGithub;
   let tag = null;
@@ -2060,7 +2163,15 @@ function resolveBranchOrTag({ branch, branchExplicit, _tagLookup } = {}) {
   } catch {
     tag = null;
   }
-  return tag || branch || DEFAULT_BRANCH;
+  if (!tag) {
+    const log = _logger || console.warn;
+    const eff = branch || DEFAULT_BRANCH;
+    log(
+      `  note: could not resolve latest tag from upstream (network or rate-limit?). Using branch "${eff}" instead. Pin a specific version with --branch vX.Y.Z if needed.`
+    );
+    return eff;
+  }
+  return tag;
 }
 function printHelp() {
   console.log(`ijfw-install -- IJFW installer
@@ -2128,6 +2239,14 @@ function runCheck(cmd, args, opts) {
   return { status: r.status, stdout: r.stdout || "", stderr: r.stderr || "", spawnError: r.error?.code, signal: r.signal };
 }
 function cloneOrPull(dir, branch) {
+  if (skipNetwork()) {
+    if (existsSync5(dir)) {
+      return "skipped-network";
+    }
+    throw new Error(
+      `IJFW_SKIP_NETWORK=1 set but cloneOrPull needs network: target directory ${dir} does not exist. Pre-seed the directory before setting IJFW_SKIP_NETWORK, or unset the env var.`
+    );
+  }
   if (!existsSync5(dir)) {
     mkdirSync4(dir, { recursive: true });
     const r = spawnSync2("git", ["clone", "--depth", "1", "--branch", branch, DEFAULT_REPO, dir], { stdio: "inherit" });
@@ -2143,7 +2262,11 @@ function cloneOrPull(dir, branch) {
     if (remoteStatus === 0) {
       const STALE_PATTERNS = [
         /^https:\/\/github\.com\/seandonahoe\/ijfw(\.git)?\/?$/i,
-        /^https:\/\/github\.com\/therealseandonahoe\/ijfw(\.git)?\/?$/i
+        /^https:\/\/github\.com\/therealseandonahoe\/ijfw(\.git)?\/?$/i,
+        // V155 rebrand: GitLab was the canonical source through v1.5.4;
+        // users who installed from gitlab.com need their origin migrated
+        // forward to FerroxLabs/ijfw on GitHub on next `ijfw-install`.
+        /^https:\/\/gitlab\.com\/therealseandonahoe\/ijfw(\.git)?\/?$/i
       ];
       const currentOrigin = (stdout || "").trim();
       if (STALE_PATTERNS.some((re) => re.test(currentOrigin))) {
@@ -2161,23 +2284,63 @@ function cloneOrPull(dir, branch) {
       return "updated";
     }
   }
+  const RESTORE_ALLOWLIST = [
+    "memory",
+    "sessions",
+    "install.log",
+    ".session-counter",
+    // v1.5.x additions:
+    "ijfw",
+    // visible brain layer (wiki + facts)
+    "state",
+    // state.json, deploy-failures.jsonl, .dream-state-v2.json
+    "cache",
+    // npm-view-cache and friends
+    "logs",
+    // post-tool-use logs, jsonl observations
+    "run",
+    // runtime lock files / pid markers
+    ".ijfw"
+    // internal — recall counter, indexes, layout version
+  ];
   const backupDir = dir + ".bak." + Date.now();
   renameSync3(dir, backupDir);
   try {
     const r = spawnSync2("git", ["clone", "--depth", "1", "--branch", branch, DEFAULT_REPO, dir], { stdio: "inherit" });
     if (r.status !== 0) throw new Error(`IJFW repo fetch did not complete (exit ${r.status}) -- check network access and retry.`);
-    for (const item of ["memory", "sessions", "install.log", ".session-counter"]) {
+    let restoredCount = 0;
+    for (const item of RESTORE_ALLOWLIST) {
       const src = join5(backupDir, item);
       if (existsSync5(src)) {
         const dst = join5(dir, item);
-        if (existsSync5(dst)) rmSync(dst, { recursive: true, force: true });
-        renameSync3(src, dst);
+        if (existsSync5(dst)) rmSync2(dst, { recursive: true, force: true });
+        try {
+          cpSync2(src, dst, { recursive: true, dereference: false });
+          rmSync2(src, { recursive: true, force: true });
+          restoredCount++;
+        } catch (cpErr) {
+          const msg = cpErr && cpErr.message ? cpErr.message : String(cpErr);
+          throw new Error(
+            `IJFW restore: cpSync failed for "${item}" (${msg}). Your data is still intact under: ${backupDir}. Move it back into ${dir} manually after diagnosing the copy failure.`
+          );
+        }
       }
     }
-    rmSync(backupDir, { recursive: true, force: true });
+    let backupResidual = [];
+    try {
+      backupResidual = readdirSync2(backupDir);
+    } catch {
+    }
+    if (backupResidual.length === 0) {
+      rmSync2(backupDir, { recursive: true, force: true });
+    } else {
+      console.warn(
+        `  [!] restored ${restoredCount} known dirs; backup retained at ${backupDir} (contains: ${backupResidual.slice(0, 8).join(", ")}${backupResidual.length > 8 ? ", ..." : ""}). Remove manually after verifying.`
+      );
+    }
     return "updated";
   } catch (err) {
-    if (existsSync5(dir)) rmSync(dir, { recursive: true, force: true });
+    if (existsSync5(dir)) rmSync2(dir, { recursive: true, force: true });
     renameSync3(backupDir, dir);
     throw err;
   }
@@ -2208,8 +2371,13 @@ async function main() {
   const sigint = () => {
     if (createdThisRun && existsSync5(target)) {
       try {
-        rmSync(target, { recursive: true, force: true });
-      } catch {
+        rmSync2(target, { recursive: true, force: true });
+      } catch (err) {
+        const msg = err && err.message ? err.message : String(err);
+        console.warn(
+          `
+  [!] partial install at ${target} could not be cleaned (${msg}) \u2014 run \`rm -rf "${target}"\` (or Remove-Item -Recurse -Force on Windows) before retrying.`
+        );
       }
     }
     process.exit(130);

package/docs/GUIDE.md

@@ -502,7 +502,7 @@ cat ~/.ijfw/dashboard.port
 
 ### Still stuck
 
-Every install writes a log to `~/.ijfw/install.log`. Every session writes observations to `~/.ijfw/observations.jsonl`. Open an issue at [gitlab.com/therealseandonahoe/ijfw/-/issues](https://gitlab.com/therealseandonahoe/ijfw/-/issues) with both files redacted and attached.
+Every install writes a log to `~/.ijfw/install.log`. Every session writes observations to `~/.ijfw/observations.jsonl`. Open an issue at [github.com/FerroxLabs/ijfw/issues](https://github.com/FerroxLabs/ijfw/issues) with both files redacted and attached.
 
 ---
 
@@ -545,7 +545,7 @@ Yes. `.ijfw/team/` is git-committed by default. Decisions, patterns, and stack c
 </p>
 
 <p align="center">
-<a href="https://gitlab.com/therealseandonahoe/ijfw">gitlab.com/therealseandonahoe/ijfw</a>
+<a href="https://github.com/FerroxLabs/ijfw">github.com/FerroxLabs/ijfw</a>
 &nbsp;|&nbsp;
 <a href="https://www.npmjs.com/package/@ijfw/install">npm</a>
 &nbsp;|&nbsp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/install",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "One-command installer for IJFW -- the AI efficiency layer. One install, every AI coding agent, zero config.",
   "type": "module",
   "bin": {
@@ -51,13 +51,19 @@
   ],
   "license": "MIT",
   "author": "Sean Donahoe",
-  "homepage": "https://gitlab.com/therealseandonahoe/ijfw",
+  "contributors": [
+    {
+      "name": "Ferrox Labs",
+      "url": "https://ferroxlabs.com"
+    }
+  ],
+  "homepage": "https://github.com/FerroxLabs/ijfw",
   "bugs": {
-    "url": "https://gitlab.com/therealseandonahoe/ijfw/-/issues"
+    "url": "https://github.com/FerroxLabs/ijfw/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/therealseandonahoe/ijfw.git"
+    "url": "git+https://github.com/FerroxLabs/ijfw.git"
   },
   "publishConfig": {
     "access": "public"

package/scripts/hub-extension/install.js.tmpl

@@ -10,11 +10,16 @@
 'use strict';
 
 const { spawnSync } = require('child_process');
+const os = require('os');
+
+// V155-066: use os.tmpdir() instead of hardcoded /tmp so the hook works on
+// Windows (where /tmp does not exist) and on hosts whose /tmp is read-only.
+const packDest = os.tmpdir();
 
 // Phase 1: pre-fetch (network) — pull package into npm cache.
 const fetchResult = spawnSync(
   'npm',
-  ['pack', '@ijfw/install@{{VERSION}}', '--silent', '--prefer-offline', '--pack-destination', '/tmp'],
+  ['pack', '@ijfw/install@{{VERSION}}', '--silent', '--prefer-offline', '--pack-destination', packDest],
   { stdio: 'pipe', timeout: 60_000 },
 );
 if (fetchResult.status !== 0) {

package/scripts/pack-hub-extension.js

@@ -29,7 +29,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { tmpdir as osTmpdir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -103,25 +103,72 @@ const WINDOWS_SYSTEM_DIRS = [
  * @param {string} absPath  Already-resolved absolute path.
  * @returns {boolean}
  */
+/**
+ * canonicalizeAtomic — resolve a path through realpath even when the leaf
+ * does not yet exist. Walks up to the deepest existing ancestor, realpaths
+ * that, then reattaches the remaining suffix. Handles the macOS
+ * /var ↔ /private/var symlink AND the "not-yet-created subdir" case in one
+ * pass. Mirrors the same helper in path-guard.js. (V155-036 / L1-02 recur)
+ */
+function canonicalizeAtomic(p) {
+  try { return realpathSync(p); } catch { /* fall through */ }
+  const parts = p.split(/[/\\]/);
+  const sep = p.includes('\\') && !p.includes('/') ? '\\' : '/';
+  let suffix = [];
+  while (parts.length > 0) {
+    suffix.unshift(parts.pop());
+    const head = parts.join(sep) || sep;
+    try {
+      const real = realpathSync(head);
+      return suffix.length > 0 ? `${real}${sep}${suffix.join(sep)}` : real;
+    } catch { /* keep walking up */ }
+  }
+  return p; // give up; return the input
+}
+
 function isSystemPath(absPath) {
   // Reject bare filesystem roots: '/', 'C:\', 'D:\', etc.
   if (/^[A-Za-z]:\\?$/.test(absPath) || absPath === '/') return true;
 
+  // V155-036: pre-canonicalize BOTH sides via the deepest-existing-ancestor
+  // walk so the macOS /var → /private/var symlink doesn't slip through when
+  // the requested output dir doesn't exist yet (the prior realpathSync on
+  // absPath silently kept the unresolved form, which then matched the
+  // /private prefix in the blocklist).
+  const tmp = osTmpdir();
+  const tmpReal = canonicalizeAtomic(tmp);
+  const absReal = canonicalizeAtomic(absPath);
+
   // OS temp-dir whitelist — overrides the system-prefix blocklist.
-  // Resolve both sides so macOS /var → /private/var symlinks compare cleanly.
-  try {
-    const tmp = osTmpdir();
-    const tmpReal = realpathSync(tmp);
-    const absReal = (() => { try { return realpathSync(absPath); } catch { return absPath; } })();
-    if (absReal === tmpReal || absReal.startsWith(tmpReal + '/') || absReal.startsWith(tmpReal + '\\')
-        || absPath === tmp || absPath.startsWith(tmp + '/') || absPath.startsWith(tmp + '\\')) {
-      return false;
-    }
-  } catch { /* fall through to blocklist */ }
+  if (
+    absReal === tmpReal ||
+    absReal.startsWith(tmpReal + '/') ||
+    absReal.startsWith(tmpReal + '\\') ||
+    absPath === tmp ||
+    absPath.startsWith(tmp + '/') ||
+    absPath.startsWith(tmp + '\\')
+  ) {
+    return false;
+  }
 
-  const lc = absPath.toLowerCase();
-  const allBlocked = [...POSIX_SYSTEM_DIRS, ...WINDOWS_SYSTEM_DIRS];
-  for (const blocked of allBlocked) {
+  // V155-059: gate the system-prefix lists by platform so cross-platform
+  // false positives go away. macOS users packing under /Library/MyProjects
+  // shouldn't trip the Windows blocklist, and Windows users shouldn't trip
+  // the POSIX blocklist. Prefer runtime-derived Windows prefixes when set.
+  const isWin = process.platform === 'win32';
+  const dynamicWinDirs = isWin
+    ? [
+        process.env.windir,
+        process.env.ProgramFiles,
+        process.env['ProgramFiles(x86)'],
+      ].filter((s) => typeof s === 'string' && s.length > 0)
+    : [];
+  const blockedForPlatform = isWin
+    ? [...WINDOWS_SYSTEM_DIRS, ...dynamicWinDirs]
+    : [...POSIX_SYSTEM_DIRS];
+
+  const lc = absReal.toLowerCase();
+  for (const blocked of blockedForPlatform) {
     const bl = blocked.toLowerCase();
     if (lc === bl || lc.startsWith(bl + '/') || lc.startsWith(bl + '\\')) {
       return true;

package/src/install.ps1

@@ -94,10 +94,25 @@ function Invoke-CloneOrPull($target, $branch) {
     if ($LASTEXITCODE -eq 0) {
       # Self-heal stale origin URLs across host migrations (1.2.9 parity with install.js).
       # Without this, Windows users on the pre-GitLab origin still 404 on every upgrade.
+      # V155-012: only rewrite ORIGINS THAT MATCH KNOWN STALE PATTERNS. Previously
+      # this clobbered SSH remotes, forks, and any user-customized origin — anyone
+      # working on the IJFW source itself ended up silently retargeted to upstream.
+      # Port the install.js STALE_PATTERNS allowlist verbatim (case-insensitive).
       $currentOrigin = ($currentOriginRaw | Out-String).Trim()
-      if ($currentOrigin -and $currentOrigin -ne $DEFAULT_REPO) {
+      $stalePatterns = @(
+        '^https://github\.com/seandonahoe/ijfw(\.git)?/?$',
+        '^https://github\.com/therealseandonahoe/ijfw(\.git)?/?$'
+      )
+      $isStale = $false
+      foreach ($pat in $stalePatterns) {
+        if ($currentOrigin -imatch $pat) { $isStale = $true; break }
+      }
+      if ($currentOrigin -and $isStale) {
         Write-Host "  origin migration: $currentOrigin -> $DEFAULT_REPO"
         & git -C $target remote set-url origin $DEFAULT_REPO
+        if ($LASTEXITCODE -ne 0) {
+          Write-Warning "  origin migration failed -- could not repoint $currentOrigin to $DEFAULT_REPO"
+        }
       }
       # fetch + hard checkout avoids ff-only failures from local divergence.
       & git -C $target fetch --depth 1 origin $branch
@@ -118,7 +133,13 @@ function Invoke-CloneOrPull($target, $branch) {
   try {
     & git clone --depth 1 --branch $branch $DEFAULT_REPO $target
     if ($LASTEXITCODE -ne 0) { throw "Could not reach the IJFW repo (exit $LASTEXITCODE). Check your network connection and retry." }
-    foreach ($item in @('memory', 'sessions', 'install.log', '.session-counter')) {
+    # V155-013: expanded restore allowlist + retain backup if residual content remains
+    # so the operator can recover anything the allowlist doesn't know about.
+    $restoreAllowlist = @(
+      'memory', 'sessions', 'install.log', '.session-counter',
+      'ijfw', 'state', 'cache', 'logs', 'run', '.ijfw'
+    )
+    foreach ($item in $restoreAllowlist) {
       $src = Join-Path $backupDir $item
       if (Test-Path $src) {
         $dst = Join-Path $target $item
@@ -126,7 +147,13 @@ function Invoke-CloneOrPull($target, $branch) {
         Move-Item -LiteralPath $src -Destination $dst -Force
       }
     }
-    Remove-Item -Recurse -Force -LiteralPath $backupDir
+    $residual = Get-ChildItem -LiteralPath $backupDir -Force -ErrorAction SilentlyContinue
+    if (-not $residual -or $residual.Count -eq 0) {
+      Remove-Item -Recurse -Force -LiteralPath $backupDir -ErrorAction SilentlyContinue
+    } else {
+      $sample = ($residual | Select-Object -First 8 | ForEach-Object { $_.Name }) -join ', '
+      Write-Warning "  restored known dirs; backup retained at $backupDir (contains: $sample). Remove manually after verifying."
+    }
     return "updated"
   } catch {
     if (Test-Path $target) { Remove-Item -Recurse -Force -LiteralPath $target }