tlc-claude-code 2.8.0 → 2.9.1

package/server/lib/orchestration/completion-checker.test.js

@@ -49,6 +49,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     });
     expect(fetch).not.toHaveBeenCalled();
@@ -74,6 +75,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [makeSession()],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     });
     expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
@@ -97,6 +99,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [{ ...makeSession(), reason: 'Tests failed' }],
+      actionable: [],
       stillRunning: 0,
     });
     expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
@@ -131,11 +134,70 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [completed],
       failures: [{ ...failed, reason: 'Rejected' }],
+      actionable: [],
       stillRunning: 1,
     });
     expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([running]);
   });
 
+  it.each([
+    ['stuck', { status: 'stuck', actionable: true, suggestedAction: 'retry' }],
+    ['budget_exhausted', { status: 'budget_exhausted', actionable: true, suggestedAction: 'retry' }],
+  ])('reports actionable monitor state %s', async (state, expected) => {
+    const activeSessionsPath = makeActiveSessionsPath();
+    const session = makeSession();
+    writeSessionsFile(activeSessionsPath, [session]);
+
+    const fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: state }),
+    });
+
+    const result = await checkCompletions({
+      activeSessionsPath,
+      orchestratorUrl: 'http://orchestrator.test',
+      fetch,
+    });
+
+    expect(result).toEqual({
+      completions: [],
+      failures: [],
+      actionable: [{ ...session, ...expected }],
+      stillRunning: 0,
+    });
+    expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
+  });
+
+  it.each([
+    ['crashed', 'session crashed and needs investigation'],
+    ['errored', 'session errored and needs investigation'],
+    ['loop_detected', 'session entered a loop and needs investigation'],
+    ['timed_out', 'session timed out and needs investigation'],
+  ])('reports failure monitor state %s', async (state, failureReason) => {
+    const activeSessionsPath = makeActiveSessionsPath();
+    const session = makeSession();
+    writeSessionsFile(activeSessionsPath, [session]);
+
+    const fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ status: state }),
+    });
+
+    const result = await checkCompletions({
+      activeSessionsPath,
+      orchestratorUrl: 'http://orchestrator.test',
+      fetch,
+    });
+
+    expect(result).toEqual({
+      completions: [],
+      failures: [{ ...session, status: state, actionable: false, failureReason }],
+      actionable: [],
+      stillRunning: 0,
+    });
+    expect(JSON.parse(fs.readFileSync(activeSessionsPath, 'utf8'))).toEqual([]);
+  });
+
   it('returns an error result when the orchestrator is unreachable', async () => {
     const activeSessionsPath = makeActiveSessionsPath();
     const session = makeSession();
@@ -152,6 +214,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: -1,
       error: 'orchestrator unreachable',
     });
@@ -170,6 +233,7 @@ describe('completion-checker', () => {
     expect(result).toEqual({
       completions: [],
       failures: [],
+      actionable: [],
       stillRunning: 0,
     });
     expect(fs.existsSync(activeSessionsPath)).toBe(false);

package/server/lib/orchestration/session-status.js

@@ -49,6 +49,24 @@ function buildSummary(session) {
   return titleCaseStatus(session.status);
 }
 
+function getSessionSkill(session) {
+  return session.metadata?.skill || session.skill || '-';
+}
+
+function getMonitorState(session) {
+  return session.monitorState || session.monitor?.state || session.metadata?.monitorState || '-';
+}
+
+function hasAlert(session) {
+  const monitorState = String(getMonitorState(session)).toLowerCase();
+  return ['stuck', 'errored', 'crashed'].includes(monitorState);
+}
+
+function formatSessionId(session) {
+  const id = session.id || '-';
+  return hasAlert(session) ? `[!] ${id}` : id;
+}
+
 /**
  * Format rows into an aligned CLI table.
  * @param {string[]} headers
@@ -108,11 +126,13 @@ function formatSessionStatus({ sessions } = {}) {
     sections.push([
       'Running Sessions',
       formatTable(
-        ['ID', 'Project', 'Status', 'Elapsed', 'Task'],
+        ['ID', 'Skill', 'Project', 'Status', 'Monitor', 'Elapsed', 'Task'],
         running.map((session) => [
-          session.id || '-',
+          formatSessionId(session),
+          getSessionSkill(session),
           session.project || '-',
           session.status || '-',
+          getMonitorState(session),
           formatElapsed(session.created_at),
           session.command || '-',
         ])
@@ -125,11 +145,13 @@ function formatSessionStatus({ sessions } = {}) {
     sections.push([
       'Completed Sessions',
       formatTable(
-        ['ID', 'Project', 'Status', 'Summary'],
+        ['ID', 'Skill', 'Project', 'Status', 'Monitor', 'Summary'],
         completed.map((session) => [
-          session.id || '-',
+          formatSessionId(session),
+          getSessionSkill(session),
           session.project || '-',
           session.status || '-',
+          getMonitorState(session),
           buildSummary(session),
         ])
       ),
@@ -144,4 +166,6 @@ module.exports = {
   formatSessionStatus,
   formatElapsed,
   buildSummary,
+  getSessionSkill,
+  getMonitorState,
 };

package/server/lib/orchestration/session-status.test.js

@@ -19,6 +19,8 @@ describe('session-status', () => {
           id: 'sess-101',
           project: 'alpha',
           status: 'running',
+          metadata: { skill: 'review' },
+          monitorState: 'idle',
           created_at: '2026-03-30T11:15:00Z',
           command: 'Implement API',
         },
@@ -27,7 +29,9 @@ describe('session-status', () => {
 
     expect(output).toContain('Running Sessions');
     expect(output).toContain('sess-101');
+    expect(output).toContain('review');
     expect(output).toContain('alpha');
+    expect(output).toContain('idle');
     expect(output).toContain('Implement API');
     expect(output).toContain('45m');
     expect(output).toContain('Attach: tlc-core attach sess-101');
@@ -40,6 +44,8 @@ describe('session-status', () => {
           id: 'sess-202',
           project: 'beta',
           status: 'completed',
+          metadata: { skill: 'build' },
+          monitor: { state: 'completed' },
           created_at: '2026-03-30T10:00:00Z',
           command: 'Add tests',
         },
@@ -48,7 +54,9 @@ describe('session-status', () => {
 
     expect(output).toContain('Completed Sessions');
     expect(output).toContain('sess-202');
+    expect(output).toContain('build');
     expect(output).toContain('beta');
+    expect(output).toContain('completed');
     expect(output).toContain('Completed: Add tests');
     expect(output).toContain('Attach: tlc-core attach sess-202');
   });
@@ -60,6 +68,8 @@ describe('session-status', () => {
           id: 'sess-run',
           project: 'gamma',
           status: 'running',
+          metadata: { skill: 'qa' },
+          monitorState: 'idle',
           created_at: '2026-03-30T11:50:00Z',
           command: 'Refactor worker',
         },
@@ -67,6 +77,8 @@ describe('session-status', () => {
           id: 'sess-done',
           project: 'delta',
           status: 'failed',
+          metadata: { skill: 'review' },
+          monitorState: 'errored',
           created_at: '2026-03-30T10:30:00Z',
           command: 'Fix flaky test',
         },
@@ -77,6 +89,7 @@ describe('session-status', () => {
     expect(output).toContain('Completed Sessions');
     expect(output).toContain('10m');
     expect(output).toContain('Failed: Fix flaky test');
+    expect(output).toContain('[!] sess-done');
   });
 
   it('returns null for empty sessions', () => {
@@ -91,6 +104,8 @@ describe('session-status', () => {
           id: 's-1',
           project: 'short',
           status: 'running',
+          metadata: { skill: 'lint' },
+          monitorState: 'idle',
           created_at: '2026-03-30T11:00:00Z',
           command: 'Task A',
         },
@@ -98,6 +113,8 @@ describe('session-status', () => {
           id: 'session-222',
           project: 'much-longer-project',
           status: 'running',
+          metadata: { skill: 'security-review' },
+          monitorState: 'stuck',
           created_at: '2026-03-30T11:30:00Z',
           command: 'Task B',
         },
@@ -107,7 +124,7 @@ describe('session-status', () => {
     const lines = output.split('\n');
     const header = lines.find((line) => line.startsWith('ID'));
     const firstRow = lines.find((line) => line.startsWith('s-1'));
-    const secondRow = lines.find((line) => line.startsWith('session-222'));
+    const secondRow = lines.find((line) => line.includes('session-222'));
 
     expect(header).toBeTruthy();
     expect(firstRow).toBeTruthy();
@@ -115,6 +132,7 @@ describe('session-status', () => {
 
     const projectStart = header.indexOf('Project');
     const statusStart = header.indexOf('Status');
+    const monitorStart = header.indexOf('Monitor');
     const elapsedStart = header.indexOf('Elapsed');
     const taskStart = header.indexOf('Task');
 
@@ -122,9 +140,34 @@ describe('session-status', () => {
     expect(secondRow.slice(projectStart, projectStart + 'much-longer-project'.length)).toBe('much-longer-project');
     expect(firstRow.slice(statusStart, statusStart + 'running'.length)).toBe('running');
     expect(secondRow.slice(statusStart, statusStart + 'running'.length)).toBe('running');
+    expect(firstRow.slice(monitorStart, monitorStart + 'idle'.length)).toBe('idle');
+    expect(secondRow.slice(monitorStart, monitorStart + 'stuck'.length)).toBe('stuck');
     expect(firstRow.slice(elapsedStart, elapsedStart + '1h 0m'.length)).toBe('1h 0m');
     expect(secondRow.slice(elapsedStart, elapsedStart + '30m'.length)).toBe('30m');
     expect(firstRow.slice(taskStart, taskStart + 'Task A'.length)).toBe('Task A');
     expect(secondRow.slice(taskStart, taskStart + 'Task B'.length)).toBe('Task B');
+    expect(secondRow.startsWith('[!] session-222')).toBe(true);
+  });
+
+  it('falls back to dashes when skill and monitor state are missing', () => {
+    const output = formatSessionStatus({
+      sessions: [
+        {
+          id: 'sess-303',
+          project: 'epsilon',
+          status: 'running',
+          created_at: '2026-03-30T11:45:00Z',
+          command: 'Inspect queue',
+        },
+      ],
+    });
+
+    const header = output.split('\n').find((line) => line.startsWith('ID'));
+    const row = output.split('\n').find((line) => line.startsWith('sess-303'));
+
+    expect(header).toBeTruthy();
+    expect(row).toBeTruthy();
+    expect(row).toContain('sess-303');
+    expect(row).toContain('  -  ');
   });
 });

package/server/lib/orchestration/skill-dispatcher.js

@@ -0,0 +1,270 @@
+const fs = require('fs/promises');
+const path = require('path');
+
+const DEFAULT_ORCHESTRATOR_URL = 'http://localhost:3100';
+const DEFAULT_ACTIVE_SESSIONS_PATH = '.tlc/.active-sessions.json';
+const TERMINAL_STATES = new Set([
+  'completed',
+  'failed',
+  'stuck',
+  'timed_out',
+  'budget_exhausted',
+  'crashed',
+  'errored',
+  'loop_detected',
+]);
+
+function normalizeBaseUrl(orchestratorUrl = DEFAULT_ORCHESTRATOR_URL) {
+  return String(orchestratorUrl).replace(/\/+$/, '');
+}
+
+async function readActiveSessions(activeSessionsPath) {
+  try {
+    const raw = await fs.readFile(activeSessionsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+async function appendActiveSession(activeSessionsPath, session) {
+  const existing = await readActiveSessions(activeSessionsPath);
+  await fs.mkdir(path.dirname(activeSessionsPath), { recursive: true });
+  await fs.writeFile(activeSessionsPath, JSON.stringify([...existing, session], null, 2));
+}
+
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function extractSessionId(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  return payload.sessionId || payload.id || null;
+}
+
+function extractStatusPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return { status: null, result: null };
+  }
+
+  return {
+    status: payload.status || null,
+    result: payload.result !== undefined ? payload.result : payload,
+  };
+}
+
+async function fetchSessionStatus(sessionId, { orchestratorUrl, fetch }) {
+  const response = await fetch(
+    `${normalizeBaseUrl(orchestratorUrl)}/sessions/${encodeURIComponent(sessionId)}/status`
+  );
+  const payload = await readJson(response);
+  return { response, payload };
+}
+
+/**
+ * Check whether the background orchestrator is reachable.
+ *
+ * @param {object} [options]
+ * @param {string} [options.orchestratorUrl='http://localhost:3100'] - Orchestrator base URL
+ * @param {Function} [options.fetch=globalThis.fetch] - Injectable fetch implementation
+ * @param {number} [options.timeout=2000] - Health-check timeout in milliseconds
+ * @returns {Promise<{available: true, latencyMs: number} | {available: false, reason: string}>}
+ */
+async function checkHealth({
+  orchestratorUrl = DEFAULT_ORCHESTRATOR_URL,
+  fetch = globalThis.fetch,
+  timeout = 2000,
+} = {}) {
+  const startedAt = Date.now();
+
+  try {
+    const response = await fetch(`${normalizeBaseUrl(orchestratorUrl)}/health`, {
+      signal: AbortSignal.timeout(timeout),
+    });
+
+    if (!response.ok) {
+      return {
+        available: false,
+        reason: `health check failed with status ${response.status}`,
+      };
+    }
+
+    return {
+      available: true,
+      latencyMs: Date.now() - startedAt,
+    };
+  } catch (error) {
+    return {
+      available: false,
+      reason: error && error.message ? error.message : 'health check failed',
+    };
+  }
+}
+
+/**
+ * Dispatch a background skill run to the orchestrator and persist the session ID.
+ *
+ * @param {object} options
+ * @param {string} options.skill - Skill/task name
+ * @param {string} options.prompt - Prompt to send to the agent
+ * @param {string} options.project - Project identifier
+ * @param {string} [options.provider='codex'] - Provider command to invoke
+ * @param {string} [options.orchestratorUrl='http://localhost:3100'] - Orchestrator base URL
+ * @param {string} [options.activeSessionsPath='.tlc/.active-sessions.json'] - Active sessions file path
+ * @param {Function} [options.fetch=globalThis.fetch] - Injectable fetch implementation
+ * @returns {Promise<{sessionId: string, dispatched: true} | {dispatched: false, reason: string}>}
+ */
+async function dispatch({
+  skill,
+  prompt,
+  project,
+  provider = 'codex',
+  orchestratorUrl = DEFAULT_ORCHESTRATOR_URL,
+  activeSessionsPath = DEFAULT_ACTIVE_SESSIONS_PATH,
+  fetch = globalThis.fetch,
+}) {
+  try {
+    const response = await fetch(`${normalizeBaseUrl(orchestratorUrl)}/sessions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        project,
+        pool: 'local-tmux',
+        command: provider,
+        prompt,
+      }),
+    });
+
+    if (!response.ok) {
+      return {
+        dispatched: false,
+        reason: `dispatch failed with status ${response.status}`,
+      };
+    }
+
+    const payload = await readJson(response);
+    const sessionId = extractSessionId(payload);
+
+    if (!sessionId) {
+      return {
+        dispatched: false,
+        reason: 'invalid session response',
+      };
+    }
+
+    await appendActiveSession(activeSessionsPath, {
+      sessionId,
+      taskName: skill,
+      startedAt: new Date().toISOString(),
+    });
+
+    return {
+      sessionId,
+      dispatched: true,
+    };
+  } catch (error) {
+    return {
+      dispatched: false,
+      reason: error && error.message ? error.message : 'dispatch failed',
+    };
+  }
+}
+
+/**
+ * Poll the orchestrator until a session reaches a terminal state.
+ *
+ * @param {string} sessionId - Session identifier
+ * @param {object} options
+ * @param {string} [options.orchestratorUrl='http://localhost:3100'] - Orchestrator base URL
+ * @param {number} [options.interval=5000] - Poll interval in milliseconds, minimum 1000
+ * @param {number} [options.timeout=1800000] - Maximum total polling duration in milliseconds
+ * @param {Function} [options.fetch=globalThis.fetch] - Injectable fetch implementation
+ * @returns {Promise<{status: string|null, result: any}>}
+ */
+async function pollUntilDone(
+  sessionId,
+  {
+    orchestratorUrl = DEFAULT_ORCHESTRATOR_URL,
+    interval = 5000,
+    timeout = 1800000,
+    fetch = globalThis.fetch,
+  } = {}
+) {
+  const pollInterval = Math.max(1000, interval);
+  const deadline = Date.now() + timeout;
+
+  while (Date.now() <= deadline) {
+    const { payload } = await fetchSessionStatus(sessionId, { orchestratorUrl, fetch });
+    const { status, result } = extractStatusPayload(payload);
+
+    if (TERMINAL_STATES.has(status)) {
+      return { status, result };
+    }
+
+    if (Date.now() + pollInterval > deadline) {
+      break;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+
+  throw new Error('Poll timeout');
+}
+
+/**
+ * Capture the latest visible output and summary for a session.
+ *
+ * @param {string} sessionId - Session identifier
+ * @param {object} options
+ * @param {string} [options.orchestratorUrl='http://localhost:3100'] - Orchestrator base URL
+ * @param {Function} [options.fetch=globalThis.fetch] - Injectable fetch implementation
+ * @returns {Promise<{output: string|null, exitCode?: number|null, summary?: string|null, error?: string}>}
+ */
+async function captureResult(
+  sessionId,
+  {
+    orchestratorUrl = DEFAULT_ORCHESTRATOR_URL,
+    fetch = globalThis.fetch,
+  } = {}
+) {
+    try {
+      const { response, payload } = await fetchSessionStatus(sessionId, { orchestratorUrl, fetch });
+
+      if (response.status === 404) {
+        return { output: null };
+      }
+
+      const source = payload && typeof payload.result === 'object' && payload.result !== null
+        ? payload.result
+        : payload;
+
+      return {
+        output: source && Object.prototype.hasOwnProperty.call(source, 'paneSnapshot')
+          ? source.paneSnapshot
+          : null,
+        exitCode: source && Object.prototype.hasOwnProperty.call(source, 'exitCode')
+          ? source.exitCode
+          : null,
+        summary: source && Object.prototype.hasOwnProperty.call(source, 'summary')
+          ? source.summary
+          : null,
+      };
+    } catch (error) {
+      return {
+        output: null,
+        error: error && error.message ? error.message : 'capture failed',
+      };
+    }
+}
+
+module.exports = {
+  checkHealth,
+  dispatch,
+  pollUntilDone,
+  captureResult,
+};