onbuzz 4.5.0 → 4.6.1

package/src/interfaces/webServer.js

@@ -31,6 +31,7 @@ import { getVisualEditorServer, getVisualEditorPort, getVisualEditorBaseUrl, set
 import { getCredentialVault } from '../services/credentialVault.js';
 import { getGalleryService } from '../services/galleryService.js';
 import { getUserDataPaths } from '../utilities/userDataDir.js';
+import { projectActiveRuns } from '../utilities/flowRunFilters.js';
 
 // Connect visual editor server to bridge (enables element selection forwarding)
 setBridgeGetter(getVisualEditorBridge);
@@ -43,6 +44,14 @@ import { initFileExplorerModule } from '../modules/fileExplorer/index.js';
 
 // Import FlowExecutor for flow pipeline execution
 import FlowExecutor from '../core/flowExecutor.js';
+// Flow definition gate — rejects malformed flows BEFORE persistence/execution.
+import { validateFlowDefinition } from '../core/flowSchema.js';
+// Phase 4: disk checkpoint store backs resume/restart of failed runs.
+import { FlowCheckpointStore } from '../core/flowCheckpointStore.js';
+// Phase 5: editor lint — soft warnings (unbound placeholders, etc.)
+import { lintFlow } from '../core/flowLint.js';
+// Phase 6: append-only flow version archive (rollback support).
+import { FlowVersionStore } from '../core/flowVersionStore.js';
 
 // Scheduler visualizer routes (extracted for testability)
 import { registerSchedulerRoutes } from './schedulerRoutes.js';
@@ -536,6 +545,39 @@ class WebServer {
       // WebServer has broadcastToSession method that FlowExecutor will use
       this.flowExecutor.setWebSocketManager(this);
 
+      // Phase 4: wire a disk checkpoint store so failed/interrupted
+      // flow runs can be resumed instead of starting over from scratch.
+      // Stored under the user data dir alongside agent state so the
+      // data survives `npm i -g` updates and follows the user across
+      // working-directory changes. (Earlier code read `dataPaths?.dataDir`
+      // which doesn't exist on getUserDataPaths() — that fell through to
+      // process.cwd() and dropped checkpoints into whatever directory the
+      // process happened to start in. Use `state` instead, grouping with
+      // agents/, operations/, models/, skills/.)
+      try {
+        const dataPaths = getUserDataPaths();
+        const checkpointDir = path.join(dataPaths?.state || process.cwd(), 'flow-checkpoints');
+        const store = new FlowCheckpointStore({ baseDir: checkpointDir });
+        this.flowExecutor.setCheckpointStore(store);
+        this.logger.info('FlowExecutor checkpoint store enabled', { baseDir: checkpointDir });
+      } catch (err) {
+        // Non-fatal: continue without resumability rather than failing init.
+        this.logger.warn('Failed to enable flow checkpoint store (non-fatal)', { error: err.message });
+      }
+
+      // Phase 6: wire a version store so every flow save records an
+      // immutable snapshot. Used by /api/flows/:id/versions and
+      // /api/flows/:id/rollback. Stored alongside checkpoints under
+      // user data dir (see comment above for path-fix history).
+      try {
+        const dataPaths = getUserDataPaths();
+        const versionDir = path.join(dataPaths?.state || process.cwd(), 'flow-versions');
+        this.flowVersionStore = new FlowVersionStore({ baseDir: versionDir });
+        this.logger.info('Flow version store enabled', { baseDir: versionDir });
+      } catch (err) {
+        this.logger.warn('Failed to enable flow version store (non-fatal)', { error: err.message });
+      }
+
       // Wire FlowExecutor into jobDoneTool so it can signal completion directly
       const toolsRegistry = this.orchestrator?.toolsRegistry;
       if (toolsRegistry) {
@@ -543,6 +585,14 @@ class WebServer {
         if (jobDoneTool && typeof jobDoneTool.setFlowExecutor === 'function') {
           jobDoneTool.setFlowExecutor(this.flowExecutor);
         }
+        // Wire FlowExecutor into platformControlTool so its execute-flow
+        // and dry-run-flow actions can reach the executor. Without this,
+        // an agent with `flows: 'all'` permission would still get
+        // "FlowExecutor not available" when calling execute-flow.
+        const platformControlTool = toolsRegistry.getTool('platformcontrol');
+        if (platformControlTool && typeof platformControlTool.setFlowExecutor === 'function') {
+          platformControlTool.setFlowExecutor(this.flowExecutor);
+        }
       }
 
       this.logger.info('FlowExecutor initialized successfully');
@@ -4249,9 +4299,37 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           });
         }
 
+        // If the resilient state loader recovered from missing/empty/
+        // corrupt files, broadcast each recovery as a UI toast so the
+        // operator sees what was salvaged. The reports were attached to
+        // the restored agent in stateManager.restoreAgent.
+        const recoveries = Array.isArray(agent._restoreRecoveries) ? agent._restoreRecoveries : [];
+        if (recoveries.length > 0 && this.wsManager) {
+          for (const r of recoveries) {
+            this.wsManager.broadcast({
+              type: 'state-file-recovery',
+              level: r.kind === 'unrepairable' ? 'error'
+                   : r.kind === 'partial'      ? 'warning'
+                   : 'info',
+              agentId: agent.id,
+              agentName: agent.name,
+              recovery: {
+                kind: r.kind,
+                label: r.label,
+                message: r.message,
+                archivePath: r.archivePath || null,
+              },
+            });
+          }
+        }
+        // Strip the recovery payload before logging/serializing back to
+        // the client — it's an internal hint, not part of the agent shape.
+        delete agent._restoreRecoveries;
+
         this.logger.info('Agent imported successfully', {
           agentId: agent.id,
-          name: agent.name
+          name: agent.name,
+          recoveryCount: recoveries.length,
         });
 
         res.json({
@@ -4264,7 +4342,12 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
             capabilities: agent.capabilities,
             lastActivity: agent.lastActivity
           },
-          message: `Agent ${agent.name} imported successfully`
+          message: `Agent ${agent.name} imported successfully`,
+          // Surfaced to the importer too so a non-WS client (curl) sees
+          // them in the response body.
+          ...(recoveries.length > 0 ? { recoveries: recoveries.map(r => ({
+            kind: r.kind, label: r.label, message: r.message,
+          })) } : {}),
         });
       } catch (error) {
         this.logger.error('Failed to import agent', {
@@ -4723,10 +4806,15 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       try {
         const { name, description, nodes, edges, variables } = req.body;
 
-        if (!name) {
+        // Schema gate: reject malformed flows BEFORE they reach persistence
+        // (avoids "saved but unexecutable" states). 400 with structured
+        // errors so the editor can highlight specific problems inline.
+        const validation = validateFlowDefinition({ name, nodes: nodes || [], edges: edges || [], variables });
+        if (!validation.ok) {
           return res.status(400).json({
             success: false,
-            error: 'Flow name is required'
+            error: 'Flow definition is invalid',
+            details: validation.errors
           });
         }
 
@@ -4739,6 +4827,20 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           variables
         }, projectDir);
 
+        // Phase 6: record initial version (v1). Best-effort — the flow
+        // is already saved; failing to version is a non-fatal warning.
+        // Stamp the version number back onto the flow record so runs
+        // can record which definition produced their output.
+        if (this.flowVersionStore && flow?.id) {
+          try {
+            const v = await this.flowVersionStore.recordVersion(flow.id, flow);
+            const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+            await this.orchestrator.stateManager.updateFlow(flow.id, { version: v.version }, projectDir);
+            flow.version = v.version;
+          }
+          catch (e) { this.logger.warn('flow version record failed', { error: e.message }); }
+        }
+
         // Broadcast flow created event
         if (this.wsManager) {
           this.wsManager.broadcast({
@@ -4794,6 +4896,35 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
         const { name, description, nodes, edges, variables } = req.body;
         const projectDir = this.orchestrator.config.project?.directory || process.cwd();
 
+        // PUT supports partial updates (e.g. just `{ nodes, edges }`
+        // when the user clicks Save in the editor). Load the existing
+        // flow and merge the patch before validating, so the schema
+        // gate sees the full resulting record — not just the diff.
+        const existing = await this.orchestrator.stateManager.getFlow(flowId, projectDir);
+        if (!existing) {
+          return res.status(404).json({ success: false, error: `Flow ${flowId} not found` });
+        }
+        const merged = {
+          ...existing,
+          ...(name        !== undefined ? { name }        : {}),
+          ...(description !== undefined ? { description } : {}),
+          ...(nodes       !== undefined ? { nodes }       : {}),
+          ...(edges       !== undefined ? { edges }       : {}),
+          ...(variables   !== undefined ? { variables }   : {}),
+        };
+
+        // Same schema gate as POST. Editing a flow into an invalid state
+        // is just as bad as creating one — both should be caught here, not
+        // 90s into a future execution.
+        const validation = validateFlowDefinition(merged);
+        if (!validation.ok) {
+          return res.status(400).json({
+            success: false,
+            error: 'Flow definition is invalid',
+            details: validation.errors
+          });
+        }
+
         const flow = await this.orchestrator.stateManager.updateFlow(flowId, {
           name,
           description,
@@ -4802,6 +4933,17 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           variables
         }, projectDir);
 
+        // Phase 6: record a new version snapshot on every PUT and
+        // stamp the new version number onto the live record.
+        if (this.flowVersionStore && flow?.id) {
+          try {
+            const v = await this.flowVersionStore.recordVersion(flow.id, flow);
+            await this.orchestrator.stateManager.updateFlow(flow.id, { version: v.version }, projectDir);
+            flow.version = v.version;
+          }
+          catch (e) { this.logger.warn('flow version record failed', { error: e.message }); }
+        }
+
         // Broadcast flow updated event
         if (this.wsManager) {
           this.wsManager.broadcast({
@@ -4956,6 +5098,140 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
 
+    // Phase 6: list versions of a flow (lightweight metadata only).
+    this.app.get('/api/flows/:flowId/versions', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const versions = await this.flowVersionStore.listVersions(req.params.flowId);
+        res.json({ success: true, data: versions });
+      } catch (error) {
+        this.logger.error('list versions failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 6: read a specific version snapshot (full flow definition).
+    this.app.get('/api/flows/:flowId/versions/:version', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const v = parseInt(req.params.version, 10);
+        if (!Number.isFinite(v) || v < 1) {
+          return res.status(400).json({ success: false, error: 'version must be a positive integer' });
+        }
+        const snap = await this.flowVersionStore.loadVersion(req.params.flowId, v);
+        if (!snap) return res.status(404).json({ success: false, error: 'version not found' });
+        res.json({ success: true, data: snap });
+      } catch (error) {
+        this.logger.error('load version failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 6: rollback — restore version N as the live flow record.
+    // Body: { version: N }. Records ANOTHER new version after rollback
+    // so history stays append-only ("rolled back to v3" produces v(N+1)).
+    this.app.post('/api/flows/:flowId/rollback', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const { flowId } = req.params;
+        const target = parseInt(req.body?.version, 10);
+        if (!Number.isFinite(target) || target < 1) {
+          return res.status(400).json({ success: false, error: 'body.version must be a positive integer' });
+        }
+        const snap = await this.flowVersionStore.loadVersion(flowId, target);
+        if (!snap) return res.status(404).json({ success: false, error: `version ${target} not found` });
+
+        // Validate the target snapshot before promoting it. A flow that
+        // passed validation when first saved may now be invalid against
+        // a newer schema — surfacing that here is better than at execute.
+        const validation = validateFlowDefinition(snap.flow);
+        if (!validation.ok) {
+          return res.status(400).json({
+            success: false,
+            error: `version ${target} fails current validation`,
+            details: validation.errors,
+          });
+        }
+
+        const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+        const restored = await this.orchestrator.stateManager.updateFlow(flowId, {
+          name:        snap.flow.name,
+          description: snap.flow.description,
+          nodes:       snap.flow.nodes,
+          edges:       snap.flow.edges,
+          variables:   snap.flow.variables,
+        }, projectDir);
+
+        // Append a new version entry tagging the rollback
+        try {
+          await this.flowVersionStore.recordVersion(flowId, {
+            ...restored,
+            _rollbackOf: target,
+          });
+        } catch (e) {
+          this.logger.warn('post-rollback version record failed', { error: e.message });
+        }
+
+        if (this.wsManager) {
+          this.wsManager.broadcast({ type: 'flow-updated', flow: restored });
+        }
+        res.json({ success: true, data: restored, rolledBackTo: target });
+      } catch (error) {
+        this.logger.error('rollback failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 5: dry-run / lint an unsaved flow definition.
+    // Posted body IS the flow definition (so the editor can lint
+    // unsaved drafts). Combines schema gate + lint warnings into a
+    // single report so the editor can highlight everything inline.
+    this.app.post('/api/flows/dry-run', async (req, res) => {
+      try {
+        const flow = req.body || {};
+        const validation = validateFlowDefinition(flow);
+        const lint = lintFlow(flow);
+        res.json({
+          success: true,
+          ok: validation.ok && lint.errors.length === 0,
+          schemaErrors: validation.errors,
+          lintErrors: lint.errors,
+          lintWarnings: lint.warnings,
+        });
+      } catch (error) {
+        this.logger.error('Dry-run failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 4: resume a failed / interrupted flow run.
+    // Per-node checkpoints on disk let us skip already-completed nodes
+    // and re-run from the first non-completed one. The run record lives
+    // under runId regardless of the flow it belongs to, so this lookup
+    // does not require the flowId in the URL.
+    this.app.post('/api/flows/runs/:runId/resume', async (req, res) => {
+      try {
+        const { runId } = req.params;
+        const { sessionId } = req.body || {};
+        if (!this.flowExecutor) {
+          return res.status(503).json({ success: false, error: 'FlowExecutor not initialized' });
+        }
+        // Async: kick off and return immediately so the HTTP request
+        // doesn't sit open for minutes. Errors propagate via WebSocket
+        // (flow_run_failed) and the run record's status field.
+        this.flowExecutor.resumeFlow(runId, sessionId || null).catch(err => {
+          this.logger.error(`Resume flow failed for run ${runId}`, { error: err.message });
+        });
+        res.json({ success: true, runId, status: 'resuming' });
+      } catch (error) {
+        this.logger.error('Failed to resume flow run', { error: error.message, runId: req.params.runId });
+        const status = /not found/i.test(error.message) ? 404
+                     : /checkpoint store/i.test(error.message) ? 503
+                     : 500;
+        res.status(status).json({ success: false, error: error.message });
+      }
+    });
+
     // Stop a flow run
     this.app.post('/api/flows/:flowId/stop', async (req, res) => {
       try {
@@ -5010,6 +5286,30 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
 
+    // List all currently-active runs across every flow. Used by the
+    // FlowsPage to mark which cards are "running" without polling each
+    // flow individually. Active = status in {queued, pending, running,
+    // paused} — anything not yet terminal.
+    //
+    // Mounted ABOVE `/api/flows/:flowId/runs` so the literal `active`
+    // segment isn't captured as a flowId by Express's pattern matcher.
+    this.app.get('/api/flows/runs/active', async (req, res) => {
+      try {
+        const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+        const runIndex = await this.orchestrator.stateManager.loadFlowRunIndex(projectDir);
+        // Pre-load the flow index ONCE so the progress summary can
+        // resolve total node count + current step labels per run
+        // without N+1 lookups. The lookup callback is a closure over
+        // the flow map; the helper queries by id at call time only.
+        const flowIndex = await this.orchestrator.stateManager.loadFlowIndex(projectDir);
+        const flowLookup = (flowId) => (flowIndex && flowId) ? flowIndex[flowId] || null : null;
+        res.json({ success: true, data: projectActiveRuns(runIndex, flowLookup) });
+      } catch (error) {
+        this.logger.error('Failed to list active flow runs', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
     // List runs for a flow
     this.app.get('/api/flows/:flowId/runs', async (req, res) => {
       try {

package/src/modules/widget/galleryStore.js

@@ -157,13 +157,38 @@ export class GalleryStore {
   async _writeNow() {
     const dir = path.dirname(this.filePath);
     try { await fs.mkdir(dir, { recursive: true }); } catch { /* race-tolerant */ }
-    const tmp = this.filePath + '.tmp';
+    // Per-call unique tmp suffix so two concurrent writes (debounce+flush
+    // racing, or any future caller) can't trample each other's tmp file.
+    // The earlier static `.tmp` suffix produced ENOENT under parallel test
+    // load on Windows: writer A renamed first, writer B saw its own tmp
+    // disappear before its rename ran.
+    const tmp = `${this.filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
     const payload = JSON.stringify({
       schema: VERSION_SCHEMA,
       entries: Array.from(this._entries.values()),
     }, null, 2);
     await fs.writeFile(tmp, payload, 'utf-8');
-    await fs.rename(tmp, this.filePath);
+    // Windows-fs renames intermittently fail with EPERM / EBUSY when an
+    // antivirus scanner or another process briefly holds the destination
+    // open. A short retry loop covers both production users on Windows
+    // and the parallel-jest workers that surface this most often.
+    let lastErr;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        await fs.rename(tmp, this.filePath);
+        return;
+      } catch (err) {
+        lastErr = err;
+        // ENOENT means our tmp already vanished — give up; the source
+        // file is gone, retrying won't recreate it. Other transients
+        // (EPERM/EBUSY/EACCES) get a brief backoff.
+        if (err.code === 'ENOENT') break;
+        await new Promise(r => setTimeout(r, 20 * (attempt + 1)));
+      }
+    }
+    // Best-effort cleanup of stranded tmp; ignore failure.
+    try { await fs.unlink(tmp); } catch { /* ok */ }
+    throw lastErr;
   }
 
   /**

package/src/services/__tests__/apiKeyManager.test.js

@@ -120,6 +120,169 @@ describe('ApiKeyManager', () => {
     expect(manager.keys.vendorKeys.anthropic).toBe('anth-key');
   });
 
+  // Regression locks: the UI used to write display-only placeholder
+  // strings into the editable settings field; auto-save then echoed
+  // them here, overwriting real keys with strings like
+  // `lx_••••••••••••••••(server-managed)` and breaking every agent
+  // request with 401. loadFromDisk must scrub any placeholder that
+  // already snuck onto disk before the fix, so a poisoned persist
+  // file from an older build self-heals on next boot.
+  describe('loadFromDisk placeholder scrub (poisoned persist file)', () => {
+    /**
+     * Helper: prep a manager so loadFromDisk takes the happy path
+     * and returns deterministic decrypted data without going through
+     * the real crypto. Each call hands back the manager + a stub.
+     */
+    function primeForLoad(manager, decryptedJson) {
+      manager.persistenceFile = '/fake/api-keys.enc';
+      manager.encryptionKey = Buffer.alloc(32, 'k');
+      mockFs.readFile.mockResolvedValueOnce('encrypted-bytes-ignored');
+      mockFs.writeFile.mockResolvedValue(undefined);
+      manager._decrypt = jest.fn(() => decryptedJson);
+    }
+
+    test('scrubs bullet-string loxia key + re-persists', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: {
+          loxiaApiKey: 'lx_••••••••••••••••(server-managed)',
+          vendorKeys: { anthropic: 'sk-ant-real-key' },
+        },
+      }));
+      // Stub persist so we can observe it without going through crypto.
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBeNull();
+      // Real vendor keys preserved.
+      expect(manager.keys.vendorKeys.anthropic).toBe('sk-ant-real-key');
+      // Best-effort re-persist fired.
+      expect(manager.persist).toHaveBeenCalledTimes(1);
+      // Operator-visible warning logged so the scrub is observable.
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Scrubbing placeholder loxiaApiKey')
+      );
+    });
+
+    test('scrubs platform-managed sentinel and any placeholder vendor keys', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: {
+          loxiaApiKey: 'platform-managed',
+          vendorKeys: {
+            anthropic: '••••••••(server-managed)',
+            openai:    'sk-real-openai-key',
+            azure:     'foo[server-managed]bar',
+          },
+        },
+      }));
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBeNull();
+      // Placeholder vendors removed entirely (NOT just blanked) so the
+      // shape stays clean for downstream serialization.
+      expect(manager.keys.vendorKeys).not.toHaveProperty('anthropic');
+      expect(manager.keys.vendorKeys).not.toHaveProperty('azure');
+      // Real vendor preserved.
+      expect(manager.keys.vendorKeys.openai).toBe('sk-real-openai-key');
+      expect(manager.persist).toHaveBeenCalledTimes(1);
+    });
+
+    test('clean persist file: no scrub, no re-persist', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: {
+          loxiaApiKey: 'lx_real_loxia_key_abc123',
+          vendorKeys: { anthropic: 'sk-ant-real', openai: 'sk-real-openai' },
+        },
+      }));
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBe('lx_real_loxia_key_abc123');
+      expect(manager.keys.vendorKeys).toEqual({ anthropic: 'sk-ant-real', openai: 'sk-real-openai' });
+      // Nothing to scrub → no extra write.
+      expect(manager.persist).not.toHaveBeenCalled();
+    });
+
+    test('legacy globalKeys format: scrub still applies after migration', async () => {
+      primeForLoad(manager, JSON.stringify({
+        // No `version` / `keys` — old shape with `globalKeys` at root.
+        globalKeys: {
+          loxiaApiKey: 'lx_••••(server-managed)',
+          vendorKeys:  { anthropic: 'sk-ant-still-good' },
+        },
+      }));
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBeNull();
+      expect(manager.keys.vendorKeys.anthropic).toBe('sk-ant-still-good');
+      expect(manager.persist).toHaveBeenCalled();
+    });
+
+    test('persist failure during scrub is non-fatal (in-memory state still clean)', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: { loxiaApiKey: 'platform-managed', vendorKeys: {} },
+      }));
+      manager.persist = jest.fn().mockRejectedValue(new Error('disk full'));
+
+      // Should NOT throw — re-persist failure is tolerated.
+      await expect(manager.loadFromDisk()).resolves.toBeUndefined();
+      // In-memory state is clean even though disk wasn't updated.
+      expect(manager.keys.loxiaApiKey).toBeNull();
+    });
+  });
+
+  describe('placeholder rejection (server-managed key bug guard)', () => {
+    test('refuses bullet-string placeholder for loxia key, keeps existing', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'real-key-existing';
+      await manager.setSessionKeys('sess-1', {
+        loxiaApiKey: 'lx_••••••••••••••••(server-managed)'
+      });
+      expect(manager.keys.loxiaApiKey).toBe('real-key-existing');
+    });
+
+    test('refuses [server-managed] tag', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'real-key';
+      await manager.setSessionKeys('sess-1', {
+        loxiaApiKey: 'lx_abc[server-managed]'
+      });
+      expect(manager.keys.loxiaApiKey).toBe('real-key');
+    });
+
+    test('refuses platform-managed sentinel', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'real-key';
+      await manager.setSessionKeys('sess-1', { loxiaApiKey: 'platform-managed' });
+      expect(manager.keys.loxiaApiKey).toBe('real-key');
+    });
+
+    test('refuses placeholder vendor keys', async () => {
+      manager.persistenceFile = null;
+      manager.keys.vendorKeys = { anthropic: 'real-anth-key' };
+      await manager.setSessionKeys('sess-1', {
+        vendorKeys: { anthropic: '••••••••(server-managed)' }
+      });
+      expect(manager.keys.vendorKeys.anthropic).toBe('real-anth-key');
+    });
+
+    test('still accepts real keys (regression guard for the guard)', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'old';
+      await manager.setSessionKeys('sess-1', { loxiaApiKey: 'lx_brand_new_real_key' });
+      expect(manager.keys.loxiaApiKey).toBe('lx_brand_new_real_key');
+    });
+  });
+
   test('getSessionKeys returns keys regardless of sessionId', () => {
     manager.keys.loxiaApiKey = 'test-key';
     const keys = manager.getSessionKeys('any-session');