@mrpatronz/nexusflow 0.2.19 → 1.3.1

package/dist/server.js

@@ -29,7 +29,9 @@ import { findSessions, getSessionTranscript } from './utils/session-finder.js';
 import { scanSystemSpecs } from './utils/system-scanner.js';
 import { getWorkspaceRepos, commitAndPush, getRepoStatus } from './utils/multi-git.js';
 import { syncWorkspace } from './core/sync.js';
-import { detectAllServices, detectOrchestrationTools, startServices, stopServices, loadRunningState, } from './orchestration/index.js';
+import { refreshWorkspace } from './core/refresh.js';
+import { addSchedule, loadSchedules, nextDueAt, parseInterval, removeSchedule, runJob, setScheduleEnabled, startScheduler, } from './core/scheduler.js';
+import { detectAllServices, detectOrchestrationTools, startServices, stopServices, loadRunningState, getPm2List, } from './orchestration/index.js';
 import { checkForUpdates, getCurrentVersion, getToolsStatus } from './utils/update-check.js';
 import { getWorkflowTemplates, saveWorkflowTemplate, deleteWorkflowTemplate } from './utils/workflows.js';
 import { suggestWorkflow } from './utils/workflow-advisor.js';
@@ -42,8 +44,86 @@ const guiPath = path.join(__dirname, 'gui');
 export const app = new Hono();
 // Allowed editor binaries/scripts to prevent command injection
 const ALLOWED_EDITORS = new Set(['code', 'code-insiders', 'cursor', 'antigravity', 'agy', 'idea', 'charm', 'webstorm', 'subl', 'nano', 'vim', 'nvim', 'emacs']);
-// Enable CORS for frontend dev server
-app.use('/api/*', cors());
+// ─── Path containment guards ──────────────────────────────────────────────
+// The server exposes state-changing routes keyed by a workspace `:id` taken
+// straight from the URL. Without containment checks, `..%2f..` sequences let a
+// caller read/write/delete files outside the workspaces root. Every handler
+// that turns an id (or repo name) into a filesystem path must go through these.
+/** Thrown when a requested path escapes its permitted base directory. */
+export class PathAccessError extends Error {
+    constructor(message = 'Invalid workspace path') {
+        super(message);
+        this.name = 'PathAccessError';
+    }
+}
+/** Resolve `target` and assert it stays within `baseDir` (or equals it). */
+function assertWithin(baseDir, target) {
+    const base = path.resolve(baseDir);
+    const resolved = path.resolve(target);
+    // Trailing separator prevents a sibling like `feat-secret` from passing the
+    // prefix test for base `feat`.
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new PathAccessError();
+    }
+    return resolved;
+}
+/** Safe workspace directory for a route `:id`, contained within workspacesDir. */
+export function resolveWorkspacePath(workspacesDir, id) {
+    return assertWithin(workspacesDir, path.join(workspacesDir, id));
+}
+/** Safe sub-repo path for a repo name, contained within the workspace. */
+export function resolveRepoPath(workspacePath, repoName) {
+    return assertWithin(workspacePath, path.join(workspacePath, repoName));
+}
+/** Consistent error response; path-containment violations map to 400. */
+function errorResponse(c, error) {
+    if (error instanceof PathAccessError) {
+        return c.json({ error: error.message }, 400);
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return c.json({ error: msg }, 500);
+}
+/**
+ * Restrict the self-update download to GitHub release hosts over HTTPS so a
+ * cross-origin caller cannot make the server fetch and later execute an
+ * arbitrary binary.
+ */
+export function isAllowedUpdateUrl(candidate) {
+    try {
+        const url = new URL(candidate);
+        if (url.protocol !== 'https:')
+            return false;
+        const host = url.hostname.toLowerCase();
+        return (host === 'github.com' ||
+            host.endsWith('.github.com') ||
+            host === 'githubusercontent.com' ||
+            host.endsWith('.githubusercontent.com'));
+    }
+    catch {
+        return false;
+    }
+}
+// Enable CORS for the local GUI only. This server can spawn processes, run
+// package installs and delete worktrees, so a wildcard origin would let any
+// web page the developer has open drive it cross-origin.
+app.use('/api/*', cors({
+    origin: (origin) => {
+        // No Origin header → same-origin or a non-browser client (CLI/desktop).
+        if (!origin)
+            return origin;
+        try {
+            const { hostname } = new URL(origin);
+            const isLocal = hostname === 'localhost' ||
+                hostname === '127.0.0.1' ||
+                hostname === '::1' ||
+                hostname === '[::1]';
+            return isLocal ? origin : null;
+        }
+        catch {
+            return null;
+        }
+    },
+}));
 // ─── API Endpoints ────────────────────────────────────────────────────────
 // 1. Get current configuration
 app.get('/api/config', async (c) => {
@@ -59,8 +139,7 @@ app.get('/api/config', async (c) => {
         return c.json({ config, exists });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // Get all registered storage adapters
@@ -70,8 +149,7 @@ app.get('/api/adapters', async (c) => {
         return c.json({ adapters });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 function isSafeLocalEndpoint(urlStr) {
@@ -107,8 +185,7 @@ app.post('/api/config', async (c) => {
         return c.json({ success: true, config: newConfig });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 3. Scan development directory for repositories
@@ -119,8 +196,7 @@ app.get('/api/repos', async (c) => {
         return c.json(repos);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 4. List existing workspaces
@@ -131,8 +207,7 @@ app.get('/api/workspaces', async (c) => {
         return c.json(workspaces);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // Severity ranking for picking the worst per-repo sync outcome in a workspace.
@@ -164,6 +239,9 @@ app.get('/api/workspaces/status', async (c) => {
     try {
         const config = await loadConfig();
         const workspaces = await listWorkspaces(config.workspacesDir);
+        // Fetch the PM2 process list once for the whole overview instead of
+        // spawning `npx pm2 jlist` per workspace (slow, especially on Windows).
+        const pm2List = await getPm2List();
         const entries = await Promise.all(workspaces.map(async (ws) => {
             const workspacePath = ws.workspacePath || path.join(config.workspacesDir, ws.branchName);
             const status = {
@@ -187,7 +265,7 @@ app.get('/api/workspaces/status', async (c) => {
                 }
                 // Running services (cached running-state, PM2-verified — same source as
                 // the Services tab; only workspaces that ever started services touch PM2).
-                const runningState = await loadRunningState(workspacePath);
+                const runningState = await loadRunningState(workspacePath, pm2List);
                 status.runningServices = runningState?.services?.length ?? 0;
                 // Sync state: worst-case classification + any repo pending validation.
                 const wsState = await loadWorkspaceState(workspacePath);
@@ -208,8 +286,7 @@ app.get('/api/workspaces/status', async (c) => {
         return c.json(byWorkspace);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 5. Detect available AI assistants
@@ -219,8 +296,7 @@ app.get('/api/ai-detect', async (c) => {
         return c.json(assistants);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 6. Detect available editors
@@ -230,8 +306,7 @@ app.get('/api/editor-detect', async (c) => {
         return c.json(editors);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 6.5. Local LLM test & recommendation
@@ -292,6 +367,16 @@ app.get('/api/local-llm/recommend', async (c) => {
     }
 });
 const creationJobs = new Map();
+// Keep a finished job around briefly so a late SSE reconnect can still read its
+// final state, then drop it so the map doesn't grow unbounded.
+const FINISHED_JOB_TTL_MS = 5 * 60 * 1000;
+function scheduleJobCleanup(jobId) {
+    const job = creationJobs.get(jobId);
+    if (!job || job.cleanupTimer)
+        return;
+    job.cleanupTimer = setTimeout(() => creationJobs.delete(jobId), FINISHED_JOB_TTL_MS);
+    job.cleanupTimer.unref?.();
+}
 function updateJobStep(jobId, stepId, status, message, extraData) {
     const job = creationJobs.get(jobId);
     if (!job)
@@ -331,10 +416,13 @@ function updateJobStep(jobId, stepId, status, message, extraData) {
     for (const listener of job.listeners) {
         listener(eventPayload);
     }
+    if (job.status === 'completed' || job.status === 'failed') {
+        scheduleJobCleanup(jobId);
+    }
 }
 async function runCreationJob(jobId, body, config) {
     try {
-        const workspacePath = path.join(config.workspacesDir, body.branchName);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, body.branchName);
         const job = creationJobs.get(jobId);
         if (job) {
             job.workspacePath = workspacePath;
@@ -420,8 +508,7 @@ app.post('/api/workspace', async (c) => {
         return c.json({ success: true, jobId });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 7.5. Create workspace SSE stream
@@ -451,23 +538,33 @@ app.get('/api/workspace/create-stream/:jobId', async (c) => {
         if (job.status === 'completed' || job.status === 'failed') {
             return;
         }
-        const listener = async (event) => {
-            try {
-                await stream.writeSSE({
-                    event: event.type,
-                    data: JSON.stringify(event.data),
-                });
-            }
-            catch (err) {
+        // Keep the connection open until the job finishes, driven by job events
+        // rather than polling.
+        await new Promise((resolve) => {
+            const listener = async (event) => {
+                try {
+                    await stream.writeSSE({
+                        event: event.type,
+                        data: JSON.stringify(event.data),
+                    });
+                }
+                catch {
+                    job.listeners.delete(listener);
+                    resolve();
+                    return;
+                }
+                if (event.data?.status === 'completed' || event.data?.status === 'failed') {
+                    job.listeners.delete(listener);
+                    resolve();
+                }
+            };
+            job.listeners.add(listener);
+            // Guard against the job finishing between the initial state write and now.
+            if (job.status === 'completed' || job.status === 'failed') {
                 job.listeners.delete(listener);
+                resolve();
             }
-        };
-        job.listeners.add(listener);
-        // Keep connection alive until job finishes
-        while (job.status === 'running') {
-            await new Promise((resolve) => setTimeout(resolve, 1000));
-        }
-        job.listeners.delete(listener);
+        });
     });
 });
 // 7.6. Delete workspace
@@ -475,13 +572,12 @@ app.delete('/api/workspace/:id', async (c) => {
     try {
         const id = decodeURIComponent(c.req.param('id'));
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         await deleteWorkspace(workspacePath);
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 7.7. Add repo to workspace
@@ -490,13 +586,12 @@ app.post('/api/workspace/:id/repo', async (c) => {
         const id = decodeURIComponent(c.req.param('id'));
         const { repoPath } = await c.req.json();
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         await addRepoToWorkspace(workspacePath, repoPath);
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 7.8. Suggest workflow strategy based on feature description & selected repos
@@ -511,8 +606,7 @@ app.post('/api/workspace/suggest-workflow', async (c) => {
         });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 8. Open workspace in editor
@@ -547,8 +641,7 @@ app.post('/api/open-editor', async (c) => {
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 9. Get status of running services in all/specific workspace
@@ -556,7 +649,7 @@ app.get('/api/workspace/:id/services', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         // Detect all services
         const services = await detectAllServices(workspacePath);
         // Detect existing tools
@@ -570,8 +663,7 @@ app.get('/api/workspace/:id/services', async (c) => {
         });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 10. Start services in workspace
@@ -580,14 +672,13 @@ app.post('/api/workspace/:id/services/start', async (c) => {
         const id = c.req.param('id');
         const { services } = await c.req.json();
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const logDir = path.join(workspacePath, '.nexusflow-logs');
         await startServices(services, workspacePath, logDir);
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 11. Stop services in workspace
@@ -595,13 +686,12 @@ app.post('/api/workspace/:id/services/stop', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         await stopServices(workspacePath);
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 12. Get service logs
@@ -610,7 +700,7 @@ app.get('/api/workspace/:id/services/logs/:serviceName', async (c) => {
         const id = c.req.param('id');
         const serviceName = c.req.param('serviceName');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const logFile = path.join(workspacePath, '.nexusflow-logs', `${serviceName}.log`);
         let content = '';
         try {
@@ -630,8 +720,7 @@ app.get('/api/workspace/:id/services/logs/:serviceName', async (c) => {
         return c.json({ logs: content });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13. Get git changes in workspace sub-repositories
@@ -639,7 +728,7 @@ app.get('/api/workspace/:id/changes', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         // Load feature config to get repo paths
         const feature = await loadFeatureConfig(workspacePath);
         if (!feature) {
@@ -709,8 +798,7 @@ app.get('/api/workspace/:id/changes', async (c) => {
         return c.json({ changes: results });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13_diff. Get git diff for a specific file in workspace sub-repositories
@@ -723,13 +811,9 @@ app.get('/api/workspace/:id/changes/diff', async (c) => {
             return c.json({ error: 'Missing repo or file query parameter.' }, 400);
         }
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
-        const worktreePath = path.join(workspacePath, repoName);
-        // Security check: ensure path is within workspace directory
-        const resolvedPath = path.resolve(worktreePath);
-        if (!resolvedPath.startsWith(path.resolve(workspacePath))) {
-            return c.json({ error: 'Invalid repository path.' }, 400);
-        }
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
+        // Contained within the workspace; rejects `..` and sibling-prefix escapes.
+        const worktreePath = resolveRepoPath(workspacePath, repoName);
         let diff = '';
         // Check git status for the file to know if it's untracked
         try {
@@ -761,8 +845,7 @@ app.get('/api/workspace/:id/changes/diff', async (c) => {
         return c.json({ diff });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13a. Get workspace knowledge (nexusflow-knowledge.md)
@@ -770,7 +853,7 @@ app.get('/api/workspace/:id/knowledge', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const knowledgeFile = path.join(workspacePath, 'nexusflow-knowledge.md');
         let content = '';
         try {
@@ -782,8 +865,7 @@ app.get('/api/workspace/:id/knowledge', async (c) => {
         return c.json({ content });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13b. Update workspace knowledge (nexusflow-knowledge.md)
@@ -792,14 +874,13 @@ app.put('/api/workspace/:id/knowledge', async (c) => {
         const id = c.req.param('id');
         const { content } = await c.req.json();
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const knowledgeFile = path.join(workspacePath, 'nexusflow-knowledge.md');
         await fs.writeFile(knowledgeFile, content, 'utf-8');
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13c. Get workspace plan (nexusflow-plan.md)
@@ -807,7 +888,7 @@ app.get('/api/workspace/:id/plan', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const planFile = path.join(workspacePath, 'nexusflow-plan.md');
         let content = '';
         try {
@@ -819,8 +900,7 @@ app.get('/api/workspace/:id/plan', async (c) => {
         return c.json({ content });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13d. Sync all repositories in workspace
@@ -828,7 +908,7 @@ app.post('/api/workspace/:id/sync', async (c) => {
     try {
         const id = c.req.param('id');
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const report = await syncWorkspace(workspacePath);
         const results = report.repos.map((repo) => ({
             repoName: repo.name,
@@ -845,8 +925,7 @@ app.post('/api/workspace/:id/sync', async (c) => {
         });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 13e. Commit changes in all repositories in workspace
@@ -855,7 +934,7 @@ app.post('/api/workspace/:id/commit', async (c) => {
         const id = c.req.param('id');
         const { message } = await c.req.json();
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const repos = await getWorkspaceRepos(workspacePath);
         const results = [];
         for (const repo of repos) {
@@ -874,8 +953,7 @@ app.post('/api/workspace/:id/commit', async (c) => {
         return c.json({ results });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 14. Resume session in workspace (copies CLI resume command and opens editor)
@@ -883,7 +961,7 @@ app.post('/api/workspace/:id/resume', async (c) => {
     try {
         const id = decodeURIComponent(c.req.param('id'));
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         // Load feature config to get repo paths
         const feature = await loadFeatureConfig(workspacePath);
         if (!feature) {
@@ -956,8 +1034,7 @@ app.post('/api/workspace/:id/resume', async (c) => {
         return c.json({ success: true, resumeCommand, workspacePath });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 15. List past AI sessions for a workspace
@@ -965,7 +1042,7 @@ app.get('/api/workspace/:id/sessions', async (c) => {
     try {
         const id = decodeURIComponent(c.req.param('id'));
         const config = await loadConfig();
-        const workspacePath = path.join(config.workspacesDir, id);
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, id);
         const feature = await loadFeatureConfig(workspacePath);
         if (!feature) {
             return c.json({ error: 'Workspace configuration not found.' }, 404);
@@ -974,8 +1051,7 @@ app.get('/api/workspace/:id/sessions', async (c) => {
         return c.json({ sessions });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 16. Fetch transcript for a specific AI session
@@ -987,8 +1063,7 @@ app.get('/api/session/:assistant/:sessionId/transcript', async (c) => {
         return c.json({ messages });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 17. Check for NexusFlow updates
@@ -1002,8 +1077,7 @@ app.get('/api/update-status', async (c) => {
         return c.json(status);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 17.5. Check tools updates status
@@ -1014,8 +1088,7 @@ app.get('/api/updates/tools', async (c) => {
         return c.json(status);
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // 17.6. Install updates for a specific tool
@@ -1043,8 +1116,7 @@ app.post('/api/updates/install', async (c) => {
         }
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 let downloadedInstallerPath = null;
@@ -1055,6 +1127,9 @@ app.post('/api/updates/download', async (c) => {
         if (!downloadUrl) {
             return c.json({ error: 'Download URL is required' }, 400);
         }
+        if (!isAllowedUpdateUrl(downloadUrl)) {
+            return c.json({ error: 'Download URL is not an allowed update host' }, 400);
+        }
         const tempDir = os.tmpdir();
         const fileName = 'NexusFlowSetup_Update.exe';
         const targetPath = path.join(tempDir, fileName);
@@ -1112,8 +1187,7 @@ app.get('/api/workflows/templates', async (c) => {
         return c.json({ templates });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // Save or update custom teamwork template
@@ -1127,8 +1201,7 @@ app.post('/api/workflows/templates', async (c) => {
         return c.json({ success: true, template });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // Delete custom teamwork template
@@ -1147,8 +1220,7 @@ app.delete('/api/workflows/templates/:id', async (c) => {
         return c.json({ success: true });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
     }
 });
 // Analyze teamwork template rules via selected AI coding assistant harness
@@ -1218,8 +1290,83 @@ and suffix it with:
         return c.json({ analysis, suggestedImprovement });
     }
     catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return c.json({ error: msg }, 500);
+        return errorResponse(c, error);
+    }
+});
+// ─── Schedules: recurring workspace jobs (sync/refresh) ─────────────────
+// List all scheduled jobs (with computed next-due time)
+app.get('/api/schedules', async (c) => {
+    const store = await loadSchedules();
+    const jobs = store.jobs.map((job) => ({
+        ...job,
+        nextDueAt: nextDueAt(job)?.toISOString() ?? null,
+    }));
+    return c.json({ jobs });
+});
+// Create a scheduled job
+app.post('/api/schedules', async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const task = body.task === 'refresh' ? 'refresh' : body.task === 'sync' ? 'sync' : null;
+    if (!task) {
+        return c.json({ error: 'task must be "sync" or "refresh"' }, 400);
+    }
+    const intervalMinutes = typeof body.intervalMinutes === 'number' && body.intervalMinutes > 0
+        ? Math.floor(body.intervalMinutes)
+        : parseInterval(String(body.every ?? ''));
+    if (!intervalMinutes) {
+        return c.json({ error: 'Provide intervalMinutes (> 0) or every (e.g. "30m", "2h", "1d")' }, 400);
+    }
+    const config = await loadConfig();
+    const workspacePath = body.workspacePath
+        ? String(body.workspacePath)
+        : body.workspaceId
+            ? path.join(config.workspacesDir, String(body.workspaceId))
+            : null;
+    if (!workspacePath) {
+        return c.json({ error: 'Provide workspacePath or workspaceId' }, 400);
+    }
+    const feature = await loadFeatureConfig(workspacePath);
+    if (!feature) {
+        return c.json({ error: `No NexusFlow workspace found at ${workspacePath}` }, 404);
+    }
+    const job = await addSchedule({ workspacePath, task, intervalMinutes });
+    return c.json({ job }, 201);
+});
+// Enable/disable a scheduled job
+app.post('/api/schedules/:id/enabled', async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const job = await setScheduleEnabled(c.req.param('id'), Boolean(body.enabled));
+    if (!job)
+        return c.json({ error: 'Schedule not found' }, 404);
+    return c.json({ job });
+});
+// Run a scheduled job immediately
+app.post('/api/schedules/:id/run', async (c) => {
+    const store = await loadSchedules();
+    const job = store.jobs.find((j) => j.id === c.req.param('id'));
+    if (!job)
+        return c.json({ error: 'Schedule not found' }, 404);
+    const result = await runJob(job);
+    return c.json({ result });
+});
+// Delete a scheduled job
+app.delete('/api/schedules/:id', async (c) => {
+    const removed = await removeSchedule(c.req.param('id'));
+    if (!removed)
+        return c.json({ error: 'Schedule not found' }, 404);
+    return c.json({ ok: true });
+});
+// Refresh a workspace's context files on demand (cache-aware)
+app.post('/api/workspace/:id/refresh', async (c) => {
+    try {
+        const config = await loadConfig();
+        const workspacePath = resolveWorkspacePath(config.workspacesDir, c.req.param('id'));
+        const body = await c.req.json().catch(() => ({}));
+        const report = await refreshWorkspace(workspacePath, { force: Boolean(body.force) });
+        return c.json({ report });
+    }
+    catch (error) {
+        return errorResponse(c, error);
     }
 });
 // Legacy pack endpoint removed.
@@ -1233,16 +1380,30 @@ app.get('/', async (c) => {
         return c.text('GUI dashboard built assets not found. Run "npm run build" first.', 404);
     }
 });
-// Serve static assets from GUI build folder
-app.use('/*', serveStatic({ root: path.relative(process.cwd(), guiPath) }));
-export function startServer(port = 3000) {
+// Serve static assets from GUI build folder. Use the absolute build path
+// (serveStatic joins root + request path) so asset serving does not depend on
+// the server's cwd — a cwd on another drive made the old cwd-relative path
+// resolve wrong and serve a blank GUI, e.g. under `ui --daemon`.
+app.use('/*', serveStatic({ root: guiPath }));
+export function startServer(port = 3000, opts = {}) {
     return new Promise((resolve, reject) => {
-        const server = serve({ fetch: app.fetch, port }, (info) => {
+        const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, (info) => {
+            // The dashboard server doubles as the host for recurring workspace
+            // jobs (nexusflow schedule ...); jobs are re-read from disk each tick.
+            startScheduler({ log: (message) => console.log(`[scheduler] ${message}`) });
             resolve({ port: info.port, server });
         });
         server.on('error', (e) => {
             if (e.code === 'EADDRINUSE') {
-                resolve(startServer(port + 1));
+                // Callers that own their backend (desktop/extension) pass strictPort so
+                // they can rely on the port they requested instead of chasing a silent
+                // increment they'd never find.
+                if (opts.strictPort) {
+                    reject(new Error(`Port ${port} is already in use.`));
+                }
+                else {
+                    resolve(startServer(port + 1, opts));
+                }
             }
             else {
                 reject(e);