@kynetic-ai/spec 0.11.0 → 0.12.0

package/dist/daemon/routes/tasks.ts

@@ -34,6 +34,8 @@ import {
 } from '../../parser/index.js';
 import { commitIfShadow } from '../../parser/shadow.js';
 import type { PubSubManager } from '../websocket/pubsub';
+import { getRelatedSessionsForTask } from './session-related.js';
+import { resolveRefTitle, resolveRefEntries } from './ref-resolution.js';
 
 interface TasksRouteOptions {
   pubsub: PubSubManager;
@@ -110,6 +112,7 @@ export function createTasksRoutes(options: TasksRouteOptions) {
 
         // AC: @api-contract ac-2 - Return with status, priority, spec_ref, notes count
         // AC: @web-dashboard ac-1 - Include depends_on for blocked task computation
+        // AC: @ui-api-ref-resolution ac-1 - Include spec_title resolved server-side
         const items = paginated.map((task) => ({
           _ulid: task._ulid,
           slugs: task.slugs,
@@ -118,6 +121,7 @@ export function createTasksRoutes(options: TasksRouteOptions) {
           status: task.status,
           priority: task.priority,
           spec_ref: task.spec_ref,
+          spec_title: resolveRefTitle(index, task.spec_ref),
           meta_ref: task.meta_ref,
           tags: task.tags,
           depends_on: task.depends_on || [],
@@ -158,7 +162,8 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         const ctx = await initContext(projectContext.path);
         const tasks = await loadAllTasks(ctx);
         const items = await loadAllItems(ctx);
-        const index = new ReferenceIndex(tasks, items);
+        const plans = await loadPlans(ctx);
+        const index = new ReferenceIndex(tasks, items, [], plans);
 
         // AC: @api-contract ac-5, @trait-api-endpoint ac-2 - Resolve ref via ReferenceIndex
         const result = index.resolve(params.ref);
@@ -184,6 +189,7 @@ export function createTasksRoutes(options: TasksRouteOptions) {
 
         // AC: @api-contract ac-5 - Return full task with notes, todos, dependencies
         // AC: @ui-task-board ac-3 - Include type, description, blocked_by, vcs_refs, plan_ref, session_ref
+        // AC: @ui-api-ref-resolution ac-1, ac-2 - Include resolved titles for refs
         return {
           _ulid: task._ulid,
           slugs: task.slugs,
@@ -192,17 +198,21 @@ export function createTasksRoutes(options: TasksRouteOptions) {
           status: task.status,
           priority: task.priority,
           spec_ref: task.spec_ref,
+          spec_title: resolveRefTitle(index, task.spec_ref),
           meta_ref: task.meta_ref,
           tags: task.tags,
           description: task.description,
           derivation: task.derivation,
           depends_on: task.depends_on,
+          resolved_depends_on: resolveRefEntries(index, task.depends_on),
           blocked_by: task.blocked_by || [],
+          resolved_blocked_by: resolveRefEntries(index, task.blocked_by),
           context: task.context || [],
           vcs_refs: (task.vcs_refs || []).map((v) =>
             typeof v === 'string' ? v : v.type ? `${v.type}:${v.ref}` : v.ref
           ),
           plan_ref: task.plan_ref,
+          plan_title: resolveRefTitle(index, task.plan_ref),
           session_ref: task.session_id,
           notes: task.notes,
           notes_count: task.notes?.length || 0,
@@ -223,6 +233,37 @@ export function createTasksRoutes(options: TasksRouteOptions) {
       }
     )
 
+    .get(
+      '/:ref/sessions',
+      async ({ params, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const tasks = await loadAllTasks(ctx);
+        const items = await loadAllItems(ctx);
+        const result = await getRelatedSessionsForTask({
+          taskRef: params.ref,
+          tasks,
+          items,
+          sessionsDir: ctx.sessionsDir,
+        });
+
+        if ('error' in result) {
+          return errorResponse(404, result.error);
+        }
+
+        return {
+          items: result.sessions,
+          total: result.sessions.length,
+          offset: 0,
+          limit: result.sessions.length,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
+    )
+
     // AC: @api-contract ac-6 - Start task
     .post(
       '/:ref/start',
@@ -274,12 +315,15 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         await commitIfShadow(ctx.shadow, `task: start ${params.ref}`);
 
         // AC: @api-contract ac-6, @trait-api-endpoint ac-5 - WebSocket broadcast
+        // AC: @ui-api-aggregation ac-4 - Include title and old/new status
         // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
         pubsub.broadcast('tasks:updates', 'task_updated', {
           ref: params.ref,
           ulid: task._ulid,
           action: 'start',
-          status: 'in_progress',
+          title: task.title,
+          old_status: task.status,
+          new_status: 'in_progress',
         }, projectContext.path);
 
         // AC: @api-contract ac-6 - Return updated task
@@ -346,11 +390,15 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         await commitIfShadow(ctx.shadow, `task: add note to ${params.ref}`);
 
         // AC: @api-contract ac-7 - WebSocket broadcast
+        // AC: @ui-api-aggregation ac-4 - Include title (no status change for notes)
         // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
         pubsub.broadcast('tasks:updates', 'task_updated', {
           ref: params.ref,
           ulid: task._ulid,
           action: 'note_added',
+          title: task.title,
+          old_status: null,
+          new_status: null,
           note_ulid: note._ulid,
         }, projectContext.path);
 
@@ -409,11 +457,14 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
         await commitIfShadow(ctx.shadow, `task: submit ${params.ref}`);
 
+        // AC: @ui-api-aggregation ac-4 - Include title and old/new status
         pubsub.broadcast('tasks:updates', 'task_updated', {
           ref: params.ref,
           ulid: task._ulid,
           action: 'submit',
-          status: 'pending_review',
+          title: task.title,
+          old_status: task.status,
+          new_status: 'pending_review',
         }, projectContext.path);
 
         return updatedTask;
@@ -456,11 +507,14 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
         await commitIfShadow(ctx.shadow, `task: complete ${params.ref}`);
 
+        // AC: @ui-api-aggregation ac-4 - Include title and old/new status
         pubsub.broadcast('tasks:updates', 'task_updated', {
           ref: params.ref,
           ulid: task._ulid,
           action: 'complete',
-          status: 'completed',
+          title: task.title,
+          old_status: task.status,
+          new_status: 'completed',
         }, projectContext.path);
 
         return updatedTask;
@@ -508,11 +562,14 @@ export function createTasksRoutes(options: TasksRouteOptions) {
         await syncSpecImplementationStatus(ctx, updatedTask, tasks, items, index);
         await commitIfShadow(ctx.shadow, `task: block ${params.ref}`);
 
+        // AC: @ui-api-aggregation ac-4 - Include title and old/new status
         pubsub.broadcast('tasks:updates', 'task_updated', {
           ref: params.ref,
           ulid: task._ulid,
           action: 'block',
-          status: 'blocked',
+          title: task.title,
+          old_status: task.status,
+          new_status: 'blocked',
         }, projectContext.path);
 
         return updatedTask;

package/dist/daemon/routes/triage.ts

@@ -25,6 +25,9 @@ import { Elysia, t } from 'elysia';
 import { ulid } from 'ulidx';
 import {
   initContext,
+  loadAllTasks,
+  loadAllItems,
+  ReferenceIndex,
   loadTriageRecords,
   saveTriageRecord,
   findTriageRecordByRef,
@@ -34,6 +37,7 @@ import {
   getAuthor,
   type LoadedTriageRecord,
 } from '../../parser/index.js';
+import { resolveRefEntries } from './ref-resolution.js';
 import { commitIfShadow } from '../../parser/shadow.js';
 import { normalizeRefInput } from '../../schema/index.js';
 import type { TriageAction } from '../../schema/index.js';
@@ -87,8 +91,27 @@ export function createTriageRoutes(options: TriageRouteOptions) {
 
         const paginated = filtered.slice(offset, offset + limit);
 
+        // AC: @ui-api-ref-resolution ac-2 - Resolve evidence_refs titles
+        const hasEvidenceRefs = paginated.some((r) => r.evidence_refs?.length > 0);
+        let refIndex: ReferenceIndex | null = null;
+        if (hasEvidenceRefs) {
+          try {
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            refIndex = new ReferenceIndex(tasks, items);
+          } catch {
+            // Non-critical
+          }
+        }
+        const enriched = refIndex
+          ? paginated.map((r) => ({
+              ...r,
+              resolved_evidence_refs: resolveRefEntries(refIndex!, r.evidence_refs),
+            }))
+          : paginated;
+
         return {
-          items: paginated,
+          items: enriched,
           total,
           offset,
           limit,
@@ -223,6 +246,7 @@ export function createTriageRoutes(options: TriageRouteOptions) {
     )
 
     // GET single triage record
+    // AC: @ui-api-ref-resolution ac-2 - Resolve evidence_refs titles
     .get(
       '/:ref',
       async ({ params, error: errorResponse, projectContext }) => {
@@ -240,6 +264,21 @@ export function createTriageRoutes(options: TriageRouteOptions) {
           });
         }
 
+        // AC: @ui-api-ref-resolution ac-2 - Resolve evidence_refs
+        if (record.evidence_refs?.length > 0) {
+          try {
+            const tasks = await loadAllTasks(ctx);
+            const items = await loadAllItems(ctx);
+            const refIndex = new ReferenceIndex(tasks, items);
+            return {
+              ...record,
+              resolved_evidence_refs: resolveRefEntries(refIndex, record.evidence_refs),
+            };
+          } catch {
+            // Non-critical
+          }
+        }
+
         return record;
       },
       {

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';
@@ -29,6 +30,10 @@ 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 {
@@ -43,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 {
@@ -61,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));
@@ -91,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.
@@ -201,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
@@ -240,7 +297,13 @@ 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())
@@ -248,6 +311,12 @@ export async function createServer(options: ServerOptions) {
     // 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
     .use(createAgentDispatchRoutes({ pubsub: pubsubManager }))
@@ -255,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.
@@ -275,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;
@@ -364,6 +410,7 @@ 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',
@@ -416,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());
 
@@ -427,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';