@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/daemon/server.ts

@@ -16,6 +16,7 @@ import { PubSubManager } from './websocket/pubsub';
 import { HeartbeatManager } from './websocket/heartbeat';
 import { WebSocketHandler } from './websocket/handler';
 import { handleWebSocketClose } from './websocket/lifecycle';
+import { resolveWebSocketProject } from './websocket/project-resolution';
 import type { ConnectionData, ConnectedEvent } from './websocket/types';
 import { PidFileManager } from './pid';
 import { projectContextMiddleware } from './middleware/project-context';
@@ -27,6 +28,12 @@ import { createValidationRoutes } from './routes/validation';
 import { createProjectsRoutes } from './routes/projects';
 import { createTriageRoutes } from './routes/triage';
 import { createAgentDispatchRoutes, getDispatchEngine, stopAllEngines } from './routes/agent-dispatch';
+import { createSessionRoutes } from './routes/sessions';
+import { createPlansRoutes } from './routes/plans';
+import { createAggregationRoutes } from './routes/aggregation';
+import { createRefsRoutes } from './routes/refs';
+import { ShadowSyncScheduler } from './shadow-sync';
+import { SessionSyncScheduler } from './session-sync';
 import { join } from 'path';
 
 export interface ServerOptions {
@@ -41,10 +48,9 @@ export interface ServerOptions {
  * Tries multiple locations in order:
  * 1. Explicit webUiDir option
  * 2. WEB_UI_DIR environment variable
- * 3. packages/web-ui/build in current working directory (monorepo dev)
- * 4. web-ui/build in current working directory
- * 5. Bundled dist/web-ui/ relative to this module (npm package installs)
+ * 3. Bundled dist/web-ui/ relative to this module (npm package installs)
  *
+ * AC: @daemon-web-ui-bundle ac-4, ac-5
  * Exported for testing only.
  */
 export function resolveWebUiPath(webUiDir?: string): string | null {
@@ -59,20 +65,7 @@ export function resolveWebUiPath(webUiDir?: string): string | null {
     return envPath;
   }
 
-  // 3. Monorepo development: packages/web-ui/build from cwd
-  // The daemon is spawned with cwd set to project root
-  const monorepoPath = join(process.cwd(), 'packages', 'web-ui', 'build');
-  if (existsSync(monorepoPath)) {
-    return monorepoPath;
-  }
-
-  // 4. Alternate location: web-ui/build in cwd
-  const altPath = join(process.cwd(), 'web-ui', 'build');
-  if (existsSync(altPath)) {
-    return altPath;
-  }
-
-  // 5. Bundled assets: dist/web-ui/ relative to daemon module location
+  // 3. Bundled assets: dist/web-ui/ relative to daemon module location
   // Covers npm package installs where no local web UI build exists.
   // import.meta.url resolves to dist/daemon/server.js → sibling is dist/web-ui/
   const selfDir = dirname(fileURLToPath(import.meta.url));
@@ -89,6 +82,66 @@ let pubsubManager: PubSubManager;
 let heartbeatManager: HeartbeatManager;
 let wsHandler: WebSocketHandler;
 let projectManager: import('./project-context').ProjectContextManager | undefined;
+let shadowSyncScheduler: ShadowSyncScheduler | undefined;
+const sessionSyncSchedulers: Map<string, SessionSyncScheduler> = new Map();
+
+/**
+ * Start a session sync scheduler for a project if it has session branch configured.
+ * Safe to call multiple times — skips if scheduler already exists for that project.
+ */
+async function startSessionSyncForProject(
+  projectPath: string,
+  pubsub: PubSubManager,
+): Promise<void> {
+  if (sessionSyncSchedulers.has(projectPath)) {
+    return;
+  }
+
+  const { loadProjectConfig } = await import('../parser/config.js');
+  const { config } = await loadProjectConfig(projectPath);
+  const specDir = join(projectPath, config.shadow.directory);
+
+  // AC: @multi-directory-daemon ac-31, @manifest-discovery ac-6
+  // Use discovery API instead of hardcoding kynetic.yaml
+  const { findManifestInDir, readYamlFile } = await import('../parser/yaml.js');
+  const manifestPath = await findManifestInDir(specDir);
+  if (!manifestPath) {
+    // No manifest found — gracefully skip session sync for this project
+    return;
+  }
+  const manifest = await readYamlFile<{ sessions?: { storage?: string; branch?: string } }>(manifestPath);
+
+  if (manifest?.sessions?.storage === 'branch') {
+    const syncInterval = config.shadow.sync_interval;
+
+    if (syncInterval > 0) {
+      const { resolveSessionBranchConfig } = await import('../parser/session-branch.js');
+      const sessionConfig = resolveSessionBranchConfig(projectPath, manifest);
+
+      if (sessionConfig) {
+        const scheduler = new SessionSyncScheduler({
+          worktreeDir: sessionConfig.worktreeDir,
+          intervalSeconds: syncInterval,
+          branchName: sessionConfig.branchName,
+          pubsub,
+        });
+        scheduler.start();
+        sessionSyncSchedulers.set(projectPath, scheduler);
+      }
+    }
+  }
+}
+
+/**
+ * Stop session sync scheduler for a specific project.
+ */
+function stopSessionSyncForProject(projectPath: string): void {
+  const scheduler = sessionSyncSchedulers.get(projectPath);
+  if (scheduler) {
+    scheduler.stop();
+    sessionSyncSchedulers.delete(projectPath);
+  }
+}
 
 /**
  * Middleware to enforce localhost-only connections.
@@ -199,10 +252,16 @@ export async function createServer(options: ServerOptions) {
     // AC-3: Enforce localhost-only connections
     .onRequest(localhostOnly());
 
+  // Shared callback for all registration paths (middleware, projects API, WebSocket)
+  const onProjectRegistered = async (projectPath: string) => {
+    await startSessionSyncForProject(projectPath, pubsubManager);
+  };
+
   // AC: @multi-directory-daemon ac-1, ac-2, ac-3 - Project context middleware
   const { manager: projectContextManager, middleware: projectMiddleware } = projectContextMiddleware({
     startupProject: startupProjectPath,
-    pubsub: pubsubManager
+    pubsub: pubsubManager,
+    onProjectRegistered,
   });
 
   // Store manager globally for shutdown
@@ -238,7 +297,25 @@ export async function createServer(options: ServerOptions) {
     .use(createValidationRoutes())
 
     // AC: @multi-directory-daemon ac-28, ac-29, ac-30 - Projects management endpoints
-    .use(createProjectsRoutes({ projectManager: projectContextManager }))
+    .use(createProjectsRoutes({
+      projectManager: projectContextManager,
+      onProjectRegistered,
+      onProjectUnregistered: (projectPath) => {
+        stopSessionSyncForProject(projectPath);
+      },
+    }))
+
+    // AC: @ui-session-stream ac-1, ac-4 - Session data endpoints
+    .use(createSessionRoutes())
+
+    // AC: @ui-plans-view ac-1 - Plans data endpoints
+    .use(createPlansRoutes())
+
+    // AC: @ui-api-aggregation ac-1, ac-2, ac-3 - Aggregation endpoints
+    .use(createAggregationRoutes())
+
+    // AC: @ui-api-ref-resolution ac-4, ac-5 - Lightweight ref index endpoint
+    .use(createRefsRoutes())
 
     // AC: @agent-dispatch-engine ac-4 - Agent dispatch API endpoints
     // AC: @daemon-agent-dispatch ac-3, ac-4 - Pass pubsub for WebSocket broadcast on invocation events
@@ -247,14 +324,6 @@ export async function createServer(options: ServerOptions) {
     // AC-4: WebSocket endpoint for real-time updates
     .ws<ConnectionData>('/ws', {
       beforeHandle({ request, store }) {
-        // AC: @multi-directory-daemon ac-21, ac-22, ac-23, ac-34 - Extract and validate project binding
-        // AC: @multi-directory-daemon ac-34 - Browser WebSocket API doesn't support custom headers,
-        // so we also accept project path as query parameter
-        const url = new URL(request.url, `http://${request.headers.get('host')}`);
-        const projectPath = request.headers.get('X-Kspec-Dir')
-                        || url.searchParams.get('project')
-                        || undefined;
-
         // IMPORTANT: Do NOT return a value from ws beforeHandle.
         // In Elysia 1.4 with derive middleware, returning a value short-circuits
         // the WebSocket upgrade and sends the value as an HTTP 200 response.
@@ -267,30 +336,15 @@ export async function createServer(options: ServerOptions) {
             return;
           }
 
-          let projectContext;
-          if (projectPath) {
-            // Explicit project specified
-            try {
-              projectContext = manager.getProject(projectPath);
-            } catch {
-              // AC: @multi-directory-daemon ac-4 - auto-register
-              projectContext = manager.registerProject(projectPath);
-            }
-          } else {
-            // AC: @multi-directory-daemon ac-22, ac-23 - Use default or reject
-            try {
-              projectContext = manager.getProject();
-            } catch (err: unknown) {
-              // AC: @multi-directory-daemon ac-23 - Reject when no default
-              if (err instanceof Error && err.message.includes('No default project configured')) {
-                throw new Error('No project specified');
-              }
-              throw err;
-            }
-          }
+          const { resolvedPath } = resolveWebSocketProject({
+            request,
+            manager,
+            fallbackPath: startupProjectPath,
+            onProjectRegistered,
+          });
 
           // Store resolved path for open() handler via WeakMap
-          wsProjectPaths.set(request, projectContext.path);
+          wsProjectPaths.set(request, resolvedPath);
         } catch (err: unknown) {
           console.error(`[daemon] WebSocket connection rejected: ${err instanceof Error ? err.message : String(err)}`);
           throw err;
@@ -355,7 +409,21 @@ export async function createServer(options: ServerOptions) {
 
     // SPA fallback routes for client-side routing
     // These catch paths like /tasks, /items, /inbox that don't have static files
-    const spaRoutes = ['/tasks', '/tasks/*', '/items', '/items/*', '/inbox', '/observations', '/triage'];
+    const spaRoutes = [
+      '/',
+      '/tasks', '/tasks/*',
+      '/items', '/items/*',
+      '/inbox',
+      '/observations',
+      '/triage',
+      '/validate',
+      '/sessions', '/sessions/*',
+      '/agents',
+      '/specs',
+      '/workflows',
+      '/plans',
+      '/settings',
+    ];
     for (const route of spaRoutes) {
       app.get(route, () => Bun.file(indexHtmlPath));
     }
@@ -395,6 +463,44 @@ export async function createServer(options: ServerOptions) {
     }
   }
 
+  // AC: @config-shadow ac-12 - Start periodic shadow sync if remote tracking configured
+  if (startupProjectPath) {
+    try {
+      const { loadProjectConfig } = await import('../parser/config.js');
+      const { config } = await loadProjectConfig(startupProjectPath);
+      const syncInterval = config.shadow.sync_interval;
+      const worktreeDir = join(startupProjectPath, config.shadow.directory);
+
+      if (syncInterval > 0) {
+        shadowSyncScheduler = new ShadowSyncScheduler({
+          worktreeDir,
+          intervalSeconds: syncInterval,
+          shadowOptions: {
+            branchName: config.shadow.branch,
+            directory: config.shadow.directory,
+            remote: config.shadow.remote?.value,
+            remoteType: config.shadow.remote?.type,
+          },
+          pubsub: pubsubManager,
+        });
+        shadowSyncScheduler.start();
+      }
+    } catch (error) {
+      console.error('[daemon] Failed to initialize shadow sync scheduler:', error);
+    }
+  }
+
+  // AC: @session-branch-worktree ac-sync - Start periodic session branch sync if configured
+  // Session sync runs independently from kspec-meta sync — failures in one do not affect the other
+  if (startupProjectPath) {
+    try {
+      await startSessionSyncForProject(startupProjectPath, pubsubManager);
+    } catch (error) {
+      // Session sync init failure does not block daemon startup
+      console.error('[daemon] Failed to initialize session sync scheduler:', error);
+    }
+  }
+
   // AC: @daemon-server ac-13, ac-14 - Start heartbeat monitoring
   heartbeatManager.start(pubsubManager.getAllConnections());
 
@@ -406,6 +512,15 @@ export async function createServer(options: ServerOptions) {
       // Stop heartbeat monitoring
       heartbeatManager.stop();
 
+      // AC: @config-shadow ac-12 - Stop shadow sync scheduler
+      shadowSyncScheduler?.stop();
+
+      // AC: @session-branch-worktree ac-sync - Stop all session sync schedulers
+      for (const scheduler of sessionSyncSchedulers.values()) {
+        scheduler.stop();
+      }
+      sessionSyncSchedulers.clear();
+
       // AC: @agent-dispatch-engine ac-11 - Stop all dispatch engines before shutting down
       await stopAllEngines();
 

package/dist/daemon/session-sync.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export SessionSyncScheduler from its canonical location in src/parser/.
+ * The daemon server.ts imports from this file; the actual implementation
+ * lives in src/parser/session-sync-scheduler.ts so that both daemon runtime
+ * (via dist/parser/) and vitest tests can import the same production code.
+ *
+ * AC: @session-branch-worktree ac-sync
+ */
+
+export { SessionSyncScheduler } from '../parser/session-sync-scheduler.js';
+export type { SessionSyncSchedulerOptions, SessionSyncPubSub } from '../parser/session-sync-scheduler.js';

package/dist/daemon/shadow-sync.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export ShadowSyncScheduler from its canonical location in src/parser/.
+ * The daemon server.ts imports from this file; the actual implementation
+ * lives in src/parser/shadow-sync-scheduler.ts so that both daemon runtime
+ * (via dist/parser/) and vitest tests can import the same production code.
+ *
+ * AC: @config-shadow ac-12
+ */
+
+export { ShadowSyncScheduler } from '../parser/shadow-sync-scheduler.js';
+export type { ShadowSyncSchedulerOptions, ShadowSyncPubSub } from '../parser/shadow-sync-scheduler.js';

package/dist/daemon/watcher.ts

@@ -9,11 +9,11 @@
  * - ac-8: Fallback to Chokidar if Bun fs.watch fails
  */
 
-import { watch, type FSWatcher } from 'fs';
-import { readFile } from 'fs/promises';
+import { existsSync, watch, type FSWatcher } from 'fs';
+import { readFile, lstat } from 'fs/promises';
 import { parse as parseYaml } from 'yaml';
 import chokidar, { type FSWatcher as ChokidarWatcher } from 'chokidar';
-import { join } from 'path';
+import { join, relative } from 'path';
 
 export interface WatcherOptions {
   kspecDir: string;
@@ -39,6 +39,8 @@ export class KspecWatcher {
   private retryCount = 0;
   private maxRetries = 5;
   private baseBackoffMs = 1000;
+  private stopped = false;
+  private recoveryTimer: NodeJS.Timeout | null = null;
 
   constructor(private options: WatcherOptions) {}
 
@@ -46,6 +48,7 @@ export class KspecWatcher {
    * AC-4, AC-8: Start watching .kspec directory (with Chokidar fallback)
    */
   async start(): Promise<void> {
+    this.stopped = false;
     try {
       // Try Bun's native fs.watch first
       await this.startBunWatcher();
@@ -68,9 +71,14 @@ export class KspecWatcher {
         if (!filename || !filename.endsWith('.yaml')) return;
 
         const fullPath = join(this.options.kspecDir, filename);
+        // Guard against nested .kspec symlink loops (e.g. .kspec/.kspec -> .kspec)
+        if (this.isNestedKspecPath(fullPath)) return;
         this.handleFileChange(fullPath);
       }
     );
+    (this.watcher as FSWatcher).on('error', (error) => {
+      void this.handleWatcherError(error);
+    });
 
     console.log('[watcher] Watching .kspec directory with Bun fs.watch');
   }
@@ -81,6 +89,8 @@ export class KspecWatcher {
   private async startChokidarWatcher(): Promise<void> {
     this.watcher = chokidar.watch(join(this.options.kspecDir, '**/*.yaml'), {
       ignoreInitial: true,
+      followSymlinks: false,
+      ignored: (filePath: string) => this.isNestedKspecPath(filePath),
       awaitWriteFinish: {
         stabilityThreshold: 100,
         pollInterval: 50
@@ -123,6 +133,12 @@ export class KspecWatcher {
    */
   private async processFileChange(filePath: string): Promise<void> {
     try {
+      if (this.isNestedKspecPath(filePath)) return;
+
+      // Skip symlinks to prevent ELOOP errors
+      const stat = await lstat(filePath);
+      if (stat.isSymbolicLink()) return;
+
       const content = await readFile(filePath, 'utf-8');
 
       // AC-6: Validate YAML before broadcasting
@@ -143,13 +159,35 @@ export class KspecWatcher {
     }
   }
 
+  /**
+   * Ignore only recursive ".kspec" entries inside the watched root, not the
+   * root .kspec directory itself.
+   */
+  private isNestedKspecPath(filePath: string): boolean {
+    const relPath = relative(this.options.kspecDir, filePath);
+    if (!relPath || relPath === '' || relPath.startsWith('..')) return false;
+
+    const [firstSegment] = relPath.split(/[\\/]+/);
+    return firstSegment === '.kspec';
+  }
+
   /**
    * AC-7: Handle watcher errors with exponential backoff
    */
   private async handleWatcherError(error: Error): Promise<void> {
+    if (this.stopped) {
+      return;
+    }
+
     this.options.onError(error);
 
+    const nodeError = error as NodeJS.ErrnoException;
     if (this.retryCount >= this.maxRetries) {
+      if (nodeError.code === 'ENOENT' && !existsSync(this.options.kspecDir)) {
+        console.warn('[watcher] Watched .kspec directory no longer exists after recovery attempts; stopping watcher');
+        await this.stop();
+        return;
+      }
       console.error('[watcher] Max retries reached, giving up');
       return;
     }
@@ -159,29 +197,42 @@ export class KspecWatcher {
 
     console.log(`[watcher] Attempting recovery in ${backoffMs}ms (attempt ${this.retryCount}/${this.maxRetries})`);
 
-    setTimeout(async () => {
+    this.recoveryTimer = setTimeout(async () => {
+      this.recoveryTimer = null;
       try {
+        if (this.stopped) return;
         await this.stop();
+        this.stopped = false;
         await this.start();
         console.log('[watcher] Recovery successful');
       } catch (retryError) {
         console.error('[watcher] Recovery failed:', retryError);
         // Will retry again if under max retries
-        this.handleWatcherError(retryError as Error);
+        await this.handleWatcherError(retryError as Error);
       }
     }, backoffMs);
+    if (typeof this.recoveryTimer === 'object' && 'unref' in this.recoveryTimer) {
+      this.recoveryTimer.unref();
+    }
   }
 
   /**
    * Stop watching
    */
   async stop(): Promise<void> {
+    this.stopped = true;
+
     // Clear all debounce timers
     for (const timer of this.debounceTimers.values()) {
       clearTimeout(timer);
     }
     this.debounceTimers.clear();
 
+    if (this.recoveryTimer) {
+      clearTimeout(this.recoveryTimer);
+      this.recoveryTimer = null;
+    }
+
     // Close watcher
     if (this.watcher) {
       if (this.usingChokidar) {

package/dist/daemon/websocket/project-resolution.ts

@@ -0,0 +1,77 @@
+/**
+ * WebSocket Project Resolution
+ *
+ * Extracts and resolves the project path for a WebSocket connection request.
+ * Used by the WebSocket beforeHandle hook in server.ts.
+ *
+ * Task: @01KKBD6KH5F5MVC5BXV2NQG474
+ */
+
+import type { ProjectContextManager } from '../project-context';
+
+export interface ResolveWebSocketProjectOptions {
+  request: Request;
+  manager: ProjectContextManager;
+  fallbackPath: string;
+  onProjectRegistered?: (projectPath: string) => Promise<void>;
+}
+
+export interface ResolveWebSocketProjectResult {
+  resolvedPath: string;
+  wasRegistered: boolean;
+}
+
+/**
+ * Resolves the project path for a WebSocket connection request.
+ *
+ * Extracts the project path from X-Kspec-Dir header or ?project= query param,
+ * registers it if new, and fires onProjectRegistered for newly-registered projects
+ * so that session sync starts.
+ *
+ * AC: @multi-directory-daemon ac-21, ac-22, ac-23, ac-34
+ */
+export function resolveWebSocketProject(
+  options: ResolveWebSocketProjectOptions,
+): ResolveWebSocketProjectResult {
+  const { request, manager, fallbackPath, onProjectRegistered } = options;
+
+  // AC: @multi-directory-daemon ac-34 - Browser WebSocket API doesn't support custom headers,
+  // so we also accept project path as query parameter
+  const url = new URL(request.url, `http://${request.headers.get('host')}`);
+  const projectPath = request.headers.get('X-Kspec-Dir')
+                  || url.searchParams.get('project')
+                  || undefined;
+
+  if (!manager) {
+    return { resolvedPath: fallbackPath, wasRegistered: false };
+  }
+
+  let projectContext;
+  let wasRegistered = false;
+  if (projectPath) {
+    // Explicit project specified
+    // AC: @multi-directory-daemon ac-4 - auto-register
+    const result = manager.getOrRegisterProject(projectPath);
+    projectContext = result.context;
+    wasRegistered = result.wasRegistered;
+    if (result.wasRegistered && onProjectRegistered) {
+      // Start session sync for newly auto-registered project (don't block upgrade)
+      void onProjectRegistered(projectContext.path).catch((syncError) => {
+        console.error(`[daemon] Failed to start session sync for WebSocket-registered ${projectContext.path}:`, syncError);
+      });
+    }
+  } else {
+    // AC: @multi-directory-daemon ac-22, ac-23 - Use default or reject
+    try {
+      projectContext = manager.getProject();
+    } catch (err: unknown) {
+      // AC: @multi-directory-daemon ac-23 - Reject when no default
+      if (err instanceof Error && err.message.includes('No default project configured')) {
+        throw new Error('No project specified');
+      }
+      throw err;
+    }
+  }
+
+  return { resolvedPath: projectContext.path, wasRegistered };
+}

package/dist/export/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/export/json.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqBH,OAAO,KAAK,EAIV,WAAW,EAEX,aAAa,EACd,MAAM,YAAY,CAAC;AA+IpB;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,iBAAiB,UAAQ,GACxB,OAAO,CAAC,aAAa,CAAC,CAoDxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,CAazE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/export/json.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwBH,OAAO,KAAK,EAIV,WAAW,EAEX,aAAa,EACd,MAAM,YAAY,CAAC;AA4PpB;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,iBAAiB,UAAQ,GACxB,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,CAezE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}