fraim 2.0.363-next.0 → 2.0.363

package/dist/src/cli/utils/managed-agent-install.js

@@ -186,7 +186,7 @@ async function installManagedAgent(option, systemPath, deps) {
     if (!(await verifyPrefix(prefix))) {
         throw new Error(option.label + ' managed installed target failed verification. Standard install: ' + (standardInstallError || 'not requested'));
     }
-    (0, persist_shell_path_1.persistShellPath)();
+    await (0, persist_shell_path_1.persistShellPath)({ signal: option.signal });
     (0, managed_agent_paths_1.invalidateAgentCommandRecovery)();
     return { outcome: 'managed' };
 }

package/dist/src/cli/utils/persist-shell-path.js

@@ -8,9 +8,13 @@ exports.persistShellPath = persistShellPath;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
-const child_process_1 = require("child_process");
+const background_command_1 = require("./background-command");
 const script_sync_utils_1 = require("./script-sync-utils");
 const managed_agent_paths_1 = require("./managed-agent-paths");
+// Unconfirmed cleanup means the old writer may still be running. Both setup
+// and managed installs must stop retrying until this process is restarted.
+let cleanupFailure;
+let registrationQueue = Promise.resolve();
 // Issue #1285: pure command-string builder extracted from persistShellPath()
 // so the generated PowerShell command's directory order (the current
 // versioned dir added before the legacy flat dir, per `bins`' own order —
@@ -24,14 +28,25 @@ function buildPersistShellPathWindowsCommand(bins) {
         `$ErrorActionPreference = 'Stop'`,
         ...assignments,
         `$cur = [Environment]::GetEnvironmentVariable('PATH', 'User')`,
+        `$originalPath = $cur`,
         `$parts = @($cur -split ';' | Where-Object { $_ })`,
         ...removals,
         ...additions,
         `$cur = ($parts | Select-Object -Unique) -join ';'`,
-        `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
+        `if ($cur -cne $originalPath) { [Environment]::SetEnvironmentVariable('PATH', $cur, 'User') }`,
     ].join('; ');
 }
-function persistShellPath() {
+function persistShellPath(options = {}) {
+    // Configuration and separate agent installs share the same User PATH. Queue
+    // each caller with its own cancellation signal rather than overlapping writes.
+    const operation = registrationQueue.then(() => registerShellPath(options));
+    registrationQueue = operation.catch(() => undefined);
+    return operation;
+}
+async function registerShellPath(options) {
+    if (cleanupFailure)
+        throw cleanupFailure;
+    options.signal?.throwIfAborted();
     const marker = '# FRAIM managed binaries';
     const legacyExportLine = 'export PATH=”$HOME/.fraim/node/bin:$PATH”';
     // The stable CLI shim must outrank old prefix installs already on inherited PATH.
@@ -51,23 +66,34 @@ function persistShellPath() {
     const stanza = `\n${marker}\n${exportLine}\n`;
     if (process.platform === 'win32') {
         const psCmd = buildPersistShellPathWindowsCommand(bins);
-        // Issue #1692: a sandboxed test run (row detection on load, node row
-        // success, fraim row success all reach this function) must never write
+        // Issue #1692: a sandboxed test run must never write
         // its temp fake-home bin dirs into the real, registry-backed Windows
         // User PATH. FRAIM_TEST_SANDBOX is already the canonical "this process
         // is a sandboxed test run" signal set by every test runner (see
         // getUserFraimDirPath() in project-fraim-paths.ts) rather than a
         // dedicated flag for this call site.
         if (process.env.FRAIM_TEST_SANDBOX !== '1') {
-            const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8', timeout: 10000, windowsHide: true });
+            const result = await (0, background_command_1.runBackgroundCommand)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], {
+                signal: options.signal, timeoutMs: 10000,
+            });
             if (result.error || result.status !== 0) {
-                throw new Error(`Could not register managed binaries on the User PATH: ${result.error?.message || result.stderr}`);
+                const details = result.error?.message || result.stderr.trim() || `PowerShell exited with status ${result.status}`;
+                if (result.outcome === 'cleanup-failed') {
+                    cleanupFailure = Object.assign(new Error(`Could not stop Windows PATH registration: ${details}. Close the failed PowerShell process and restart FRAIM before trying again.`), {
+                        code: result.outcome,
+                    });
+                    throw cleanupFailure;
+                }
+                throw Object.assign(new Error(`Could not register managed binaries on the User PATH: ${details}`), {
+                    code: result.outcome,
+                });
             }
         }
         // Fall through to write POSIX profile files for Git Bash (VS Code
         // integrated terminal, Claude Code, etc.) which do not inherit the
         // Windows user PATH written above.
     }
+    options.signal?.throwIfAborted();
     // Test runners isolate FRAIM_USER_DIR but may leave os.homedir() unchanged.
     const sandboxDir = process.env.FRAIM_USER_DIR ? path_1.default.resolve(process.env.FRAIM_USER_DIR) : null;
     const profileHome = process.env.FRAIM_TEST_SANDBOX === '1'
@@ -107,7 +133,9 @@ function persistShellPath() {
             if (content.includes(marker)) {
                 if (!content.includes(exportLine)) {
                     // Replace stale runtime directories or an older shim ordering.
-                    fs_1.default.writeFileSync(profile, content.replace(/export PATH=[\u201D"][^\u201D"]*\.fraim[^\u201D"]*[\u201D"]/, exportLine), 'utf8');
+                    const updated = content.replace(/export PATH=[\u201D"][^\u201D"]*\.fraim[^\u201D"]*[\u201D"]/, exportLine);
+                    if (updated !== content)
+                        fs_1.default.writeFileSync(profile, updated, 'utf8');
                 }
                 continue;
             }

package/dist/src/first-run/server.js

@@ -141,6 +141,15 @@ class FirstRunServer {
             res.json({ status: 'ok', service: 'fraim-first-run' });
         });
         this.registerRoutes();
+        const apiErrorHandler = (error, req, res, next) => {
+            if (!req.path.startsWith('/api/first-run/') || res.headersSent)
+                return next(error);
+            const status = error?.type === 'entity.parse.failed' ? 400 : 500;
+            res.status(status).json({ error: status === 400
+                    ? 'Invalid JSON request.'
+                    : error instanceof Error ? error.message : 'First-run request failed.' });
+        };
+        this.app.use(apiErrorHandler);
     }
     async start(port) {
         this.sessionService.resumePendingOperations();

package/dist/src/first-run/session-service.js

@@ -168,6 +168,7 @@ class FirstRunSessionService {
         this.operationAbort = new AbortController(); }
     cancelPendingOperations() { this.operationAbort.abort(); }
     constructor(options) {
+        this.rowOperations = new Map();
         this.operationAbort = new AbortController();
         // Issue #646: the key may be absent when first-run is launched by the macOS
         // installer (.dmg) instead of `fraim first-run --key=…`. In that case the
@@ -175,6 +176,7 @@ class FirstRunSessionService {
         this.key = options.key || '';
         this.headless = options.headless === true;
         this.embeddedDesktop = options.embeddedDesktop === true;
+        this.registerShellPath = options.registerShellPath ?? persist_shell_path_1.persistShellPath;
         this.fakeMode = getFakeStateMode();
         this.fakeStderr =
             process.env.FRAIM_FIRST_RUN_FAKE_STDERR ??
@@ -182,6 +184,10 @@ class FirstRunSessionService {
         this.requestToken = crypto_1.default.randomUUID();
         this.state = options.resume ? (0, install_state_1.loadFirstRunState)() || (0, install_state_1.createInitialFirstRunState)(options.key) : (0, install_state_1.createInitialFirstRunState)(options.key);
         this.state.rows = normalizeRows(this.state.rows);
+        const interrupted = this.getRow('fraim');
+        if (interrupted.status === 'in-progress') {
+            this.setRowError(interrupted, 'Setting up FRAIM on this machine', 'Setup was interrupted before it completed. Try again.', [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
+        }
         if (options.projectRoot) {
             this.state.workspacePath = path_1.default.resolve(options.projectRoot);
             (0, install_state_1.saveFirstRunState)(this.state);
@@ -261,7 +267,10 @@ class FirstRunSessionService {
             gitRow.verb = 'optional — only needed for code delivery workflows';
         }
         const fraimRow = this.getRow('fraim');
-        if (this.embeddedDesktop || commandVersion('npx') !== null) {
+        if (fraimRow.status === 'error' || fraimRow.status === 'in-progress') {
+            // A prior config is not evidence that the current setup attempt completed.
+        }
+        else if (this.embeddedDesktop || commandVersion('npx') !== null) {
             // Only mark ok if setup has previously completed (config.json is written after autoConfigureMCP).
             // Without this, the wizard skips runFraimRow entirely and autoConfigureMCP never runs for IDEs.
             const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
@@ -273,7 +282,6 @@ class FirstRunSessionService {
                 fraimRow.status = 'pending';
                 fraimRow.verb = "we'll configure your IDEs";
             }
-            (0, persist_shell_path_1.persistShellPath)();
         }
         else {
             fraimRow.status = 'pending';
@@ -473,6 +481,19 @@ class FirstRunSessionService {
      * order, until every row is `ok` or surfaces an error.
      */
     async runRow(rowId, request = {}) {
+        const existing = this.rowOperations.get(rowId);
+        if (existing)
+            return existing;
+        const operation = this.executeRow(rowId, request);
+        this.rowOperations.set(rowId, operation);
+        try {
+            return await operation;
+        }
+        finally {
+            this.rowOperations.delete(rowId);
+        }
+    }
+    async executeRow(rowId, request) {
         const row = this.getRow(rowId);
         if (row.status === 'ok') {
             return this.respond(`${row.label} already ready.`, true);
@@ -523,7 +544,6 @@ class FirstRunSessionService {
                 this.persist();
                 return this.respond('FRAIM installer repair is required.', false);
             }
-            (0, persist_shell_path_1.persistShellPath)();
             row.status = 'ok';
             row.verb = 'Node and FRAIM launchers ready';
             this.persist();
@@ -533,7 +553,6 @@ class FirstRunSessionService {
         // If node is missing here something is severely wrong; fall through to error.
         const ver = commandVersion('node');
         if (ver) {
-            (0, persist_shell_path_1.persistShellPath)();
             row.status = 'ok';
             row.verb = `${ver} installed`;
             this.persist();
@@ -581,22 +600,21 @@ class FirstRunSessionService {
             this.persist();
             return this.respond('Fake-mode fraim ok.', true);
         }
-        // FRAIM_SKIP_SYNC signals an isolated/test environment. Skip all external
-        // writes (MCP config files, global config.json, slash commands) so tests
-        // that auto-trigger this path cannot corrupt the real user config.
-        if (process.env.FRAIM_SKIP_SYNC) {
-            row.status = 'ok';
-            row.verb = 'Ready.';
-            this.persist();
-            return this.respond('FRAIM configured.', true);
-        }
         try {
-            if (this.embeddedDesktop && (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)()) || !fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)()))) {
+            if (!process.env.FRAIM_SKIP_SYNC && this.embeddedDesktop && (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)()) || !fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)()))) {
                 throw new Error('Stable FRAIM launchers are missing. Re-run the native installer in repair mode.');
             }
-            if (!this.embeddedDesktop)
+            if (!process.env.FRAIM_SKIP_SYNC && !this.embeddedDesktop)
                 (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
-            (0, persist_shell_path_1.persistShellPath)();
+            await this.registerShellPath({ signal: this.operationAbort.signal });
+            // Tests isolate PATH with FRAIM_TEST_SANDBOX; this flag skips remote sync
+            // and IDE/global configuration while retaining the setup lifecycle.
+            if (process.env.FRAIM_SKIP_SYNC) {
+                row.status = 'ok';
+                row.verb = 'Ready.';
+                this.persist();
+                return this.respond('FRAIM configured.', true);
+            }
             const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
             if (detectedIDEs.length > 0) {
                 await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, detectedIDEs.map((ide) => ide.name));
@@ -835,6 +853,9 @@ class FirstRunSessionService {
         };
     }
     async finishAgentRecruiting() {
+        const existing = this.rowOperations.get('fraim');
+        if (existing)
+            return existing;
         this.updateAgentSummaryRow();
         const readyCount = this.state.setupResult?.detectedSurfaceCount || 0;
         if (readyCount < 1) {
@@ -846,7 +867,7 @@ class FirstRunSessionService {
         fraimRow.verb = 'configuring FRAIM for local AI agents';
         this.persist();
         appendInstallLog(`agent-recruiting-complete ready=${readyCount}`);
-        return this.runFraimRow();
+        return this.runRow('fraim');
     }
     openTerminalWithCommand(command) {
         if (process.platform === 'win32') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.363-next.0",
+  "version": "2.0.363",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {

package/public/first-run/index.html

@@ -15,7 +15,8 @@
     </header>
 
     <section class="card">
-      <ul class="checklist" id="checklist" data-testid="setup-checklist" aria-label="FRAIM setup checklist">
+      <div id="checklist" data-testid="setup-checklist">
+      <ul class="checklist" aria-label="FRAIM setup checklist">
         <!-- Skeleton rows shown until the async session-load completes.
              Replaced wholesale by script.js once /api/first-run/session returns. -->
         <li class="row skeleton-row" data-row-id="node" data-row-status="pending"><span class="icon" aria-hidden="true">.</span><span class="label">Node.js</span><span class="verb" data-testid="row-verb">checking...</span></li>
@@ -23,6 +24,7 @@
         <li class="row skeleton-row" data-row-id="agent" data-row-status="pending"><span class="icon" aria-hidden="true">.</span><span class="label">Locally installed AI agents</span><span class="verb" data-testid="row-verb">checking...</span></li>
         <li class="row skeleton-row" data-row-id="fraim" data-row-status="pending"><span class="icon" aria-hidden="true">.</span><span class="label">FRAIM</span><span class="verb" data-testid="row-verb">checking...</span></li>
       </ul>
+      </div>
       <div class="actions">
         <button id="primary-button" class="primary-button" data-testid="primary-button">Set up FRAIM</button>
       </div>

package/public/first-run/script.js

@@ -8,6 +8,7 @@
 
   const state = {
     session: null,
+    sessionLoadInFlight: false,
     activeStep: 'prereqs',
     configureInFlight: false,
     configureError: null,
@@ -45,8 +46,19 @@
       body: body !== undefined ? JSON.stringify(body) : undefined,
     });
     if (response.status === 204) return null;
-    const json = await response.json();
-    if (!response.ok) throw new Error(json && json.error ? json.error : `Request failed (status ${response.status}).`);
+    let json;
+    try {
+      json = await response.json();
+    } catch {
+      throw new Error(response.ok
+        ? 'FRAIM returned an invalid response. Please try again.'
+        : `Request failed (status ${response.status}). Please try again.`);
+    }
+    if (!response.ok) {
+      throw new Error(json && typeof json.error === 'string' && json.error.trim()
+        ? json.error
+        : `Request failed (status ${response.status}). Please try again.`);
+    }
     return json;
   }
 
@@ -632,6 +644,46 @@
     }
   }
 
+  function renderSessionLoadFailure(message) {
+    CHECKLIST_EL.className = 'setup-shell setup-shell--single';
+    CHECKLIST_EL.innerHTML = '';
+    PRIMARY_BUTTON.style.display = 'none';
+    setHeader('Set up FRAIM', 'Retry to check your machine and continue setup.');
+    setStatus('');
+
+    const pane = document.createElement('div');
+    pane.className = 'setup-pane';
+    const heading = document.createElement('h2');
+    heading.textContent = 'Could not load setup';
+    const error = document.createElement('div');
+    error.className = 'ready-strip ready-strip--error';
+    error.setAttribute('role', 'alert');
+    error.textContent = message;
+    const retry = button('Retry', 'primary');
+    retry.addEventListener('click', () => startSessionLoad(retry));
+    pane.append(heading, error, retry);
+    CHECKLIST_EL.appendChild(pane);
+  }
+
+  async function startSessionLoad(retryButton) {
+    if (state.sessionLoadInFlight) return;
+    state.sessionLoadInFlight = true;
+    PRIMARY_BUTTON.disabled = true;
+    if (retryButton) {
+      retryButton.disabled = true;
+      retryButton.textContent = 'Retrying…';
+    }
+    try {
+      await loadSession();
+      setStatus('');
+    } catch (err) {
+      renderSessionLoadFailure(err.message || 'Could not load setup. Please try again.');
+    } finally {
+      state.sessionLoadInFlight = false;
+      PRIMARY_BUTTON.disabled = false;
+    }
+  }
+
   // Issue #646: when first-run was launched without a key (the no-terminal macOS
   // installer path), gate the whole wizard behind a paste-your-key step.
   function renderKeyEntry() {
@@ -717,11 +769,13 @@
   }
 
   PRIMARY_BUTTON.addEventListener('click', () => {
+    if (!state.session) {
+      startSessionLoad();
+      return;
+    }
     state.activeStep = chooseActiveStep();
     render();
   });
 
-  loadSession().catch((err) => {
-    setStatus(err.message || 'Could not load first-run.', 'error');
-  });
+  startSessionLoad();
 }());

package/public/first-run/styles.css

@@ -430,6 +430,9 @@ body {
   grid-template-columns: minmax(190px, 0.85fr) minmax(0, 2fr);
   gap: 20px;
 }
+.setup-shell--single {
+  grid-template-columns: minmax(0, 1fr);
+}
 .setup-steps {
   display: flex;
   flex-direction: column;
@@ -619,6 +622,7 @@ body {
   color: var(--muted);
 }
 .ready-strip--error {
+  overflow-wrap: anywhere;
   background: #fff1f2;
   border-color: #fb7185;
   color: #9f1239;