triflux 3.3.0-dev.7 → 3.3.0-dev.8

package/hub/bridge.mjs

@@ -295,6 +295,17 @@ async function requestHub(operation, body, timeoutMs = 3000, fallback = null) {
   return { transport: 'fallback', result: viaFallback };
 }
 
+function unavailableResult() {
+  return { ok: false, reason: 'hub_unavailable' };
+}
+
+function emitJson(payload) {
+  if (payload !== undefined) {
+    console.log(JSON.stringify(payload));
+  }
+  return payload?.ok !== false;
+}
+
 async function cmdRegister(args) {
   const agentId = args.agent;
   const timeoutSec = parseInt(args.timeout || '600', 10);
@@ -313,15 +324,15 @@ async function cmdRegister(args) {
   const result = outcome?.result;
 
   if (result?.ok) {
-    console.log(JSON.stringify({
+    return emitJson({
       ok: true,
       agent_id: agentId,
       lease_expires_ms: result.data?.lease_expires_ms,
       pipe_path: result.data?.pipe_path || getHubPipePath(),
-    }));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+    });
   }
+
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdResult(args) {
@@ -349,10 +360,10 @@ async function cmdResult(args) {
   const result = outcome?.result;
 
   if (result?.ok) {
-    console.log(JSON.stringify({ ok: true, message_id: result.data?.message_id }));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+    return emitJson({ ok: true, message_id: result.data?.message_id });
   }
+
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdControl(args) {
@@ -367,11 +378,7 @@ async function cmdControl(args) {
     ttl_ms: args['ttl-ms'] != null ? Number(args['ttl-ms']) : undefined,
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdContext(args) {
@@ -394,14 +401,21 @@ async function cmdContext(args) {
 
     if (args.out) {
       writeFileSync(args.out, combined, 'utf8');
-      console.log(JSON.stringify({ ok: true, count: result.data.messages.length, file: args.out }));
+      return emitJson({ ok: true, count: result.data.messages.length, file: args.out });
     } else {
       console.log(combined);
+      return true;
     }
-    return;
   }
 
-  if (args.out) console.log(JSON.stringify({ ok: true, count: 0 }));
+  if (result?.ok) {
+    if (args.out) {
+      return emitJson({ ok: true, count: 0 });
+    }
+    return true;
+  }
+
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdDeregister(args) {
@@ -411,10 +425,10 @@ async function cmdDeregister(args) {
   const result = outcome?.result;
 
   if (result?.ok) {
-    console.log(JSON.stringify({ ok: true, agent_id: args.agent, status: 'offline' }));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+    return emitJson({ ok: true, agent_id: args.agent, status: 'offline' });
   }
+
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdAssignAsync(args) {
@@ -432,11 +446,7 @@ async function cmdAssignAsync(args) {
     correlation_id: args.correlation || undefined,
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdAssignResult(args) {
@@ -451,11 +461,7 @@ async function cmdAssignResult(args) {
     metadata: args.metadata ? parseJsonSafe(args.metadata, {}) : {},
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdAssignStatus(args) {
@@ -463,11 +469,7 @@ async function cmdAssignStatus(args) {
     job_id: args['job-id'],
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdAssignRetry(args) {
@@ -477,11 +479,7 @@ async function cmdAssignRetry(args) {
     requested_by: args['requested-by'],
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdTeamInfo(args) {
@@ -495,9 +493,7 @@ async function cmdTeamInfo(args) {
     return await teamInfo(body);
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdTeamTaskList(args) {
@@ -513,9 +509,7 @@ async function cmdTeamTaskList(args) {
     return await teamTaskList(body);
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdTeamTaskUpdate(args) {
@@ -539,9 +533,7 @@ async function cmdTeamTaskUpdate(args) {
     return await teamTaskUpdate(body);
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdTeamSendMessage(args) {
@@ -558,9 +550,7 @@ async function cmdTeamSendMessage(args) {
     return await teamSendMessage(body);
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 function getHubDbPath() {
@@ -588,9 +578,7 @@ async function cmdPipelineState(args) {
     }
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdPipelineAdvance(args) {
@@ -616,9 +604,7 @@ async function cmdPipelineAdvance(args) {
     }
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdPipelineInit(args) {
@@ -628,49 +614,39 @@ async function cmdPipelineInit(args) {
     ralph_max: args['ralph-max'] != null ? Number(args['ralph-max']) : undefined,
   });
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdPipelineList() {
   const outcome = await requestHub(HUB_OPERATIONS.pipelineList, {});
   const result = outcome?.result;
-  if (result) {
-    console.log(JSON.stringify(result));
-  } else {
-    console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
-  }
+  return emitJson(result || unavailableResult());
 }
 
 async function cmdPing() {
   const outcome = await requestHub(HUB_OPERATIONS.hubStatus, { scope: 'hub' }, 2000);
 
   if (outcome?.transport === 'pipe' && outcome.result?.ok) {
-    console.log(JSON.stringify({
+    return emitJson({
       ok: true,
       hub: outcome.result.data?.hub?.state || 'healthy',
       pipe_path: getHubPipePath(),
       transport: 'pipe',
-    }));
-    return;
+    });
   }
 
   if (outcome?.transport === 'http' && outcome.result) {
     const data = outcome.result;
-    console.log(JSON.stringify({
+    return emitJson({
       ok: true,
       hub: data.hub?.state,
       sessions: data.sessions,
       pipe_path: data.pipe?.path || data.pipe_path || null,
       transport: 'http',
-    }));
-    return;
+    });
   }
 
-  console.log(JSON.stringify({ ok: false, reason: 'hub_unavailable' }));
+  return emitJson(unavailableResult());
 }
 
 export async function main(argv = process.argv.slice(2)) {
@@ -678,24 +654,24 @@ export async function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv.slice(1));
 
   switch (cmd) {
-    case 'register': await cmdRegister(args); break;
-    case 'result': await cmdResult(args); break;
-    case 'control': await cmdControl(args); break;
-    case 'context': await cmdContext(args); break;
-    case 'deregister': await cmdDeregister(args); break;
-    case 'assign-async': await cmdAssignAsync(args); break;
-    case 'assign-result': await cmdAssignResult(args); break;
-    case 'assign-status': await cmdAssignStatus(args); break;
-    case 'assign-retry': await cmdAssignRetry(args); break;
-    case 'team-info': await cmdTeamInfo(args); break;
-    case 'team-task-list': await cmdTeamTaskList(args); break;
-    case 'team-task-update': await cmdTeamTaskUpdate(args); break;
-    case 'team-send-message': await cmdTeamSendMessage(args); break;
-    case 'pipeline-state': await cmdPipelineState(args); break;
-    case 'pipeline-advance': await cmdPipelineAdvance(args); break;
-    case 'pipeline-init': await cmdPipelineInit(args); break;
-    case 'pipeline-list': await cmdPipelineList(args); break;
-    case 'ping': await cmdPing(args); break;
+    case 'register': return await cmdRegister(args);
+    case 'result': return await cmdResult(args);
+    case 'control': return await cmdControl(args);
+    case 'context': return await cmdContext(args);
+    case 'deregister': return await cmdDeregister(args);
+    case 'assign-async': return await cmdAssignAsync(args);
+    case 'assign-result': return await cmdAssignResult(args);
+    case 'assign-status': return await cmdAssignStatus(args);
+    case 'assign-retry': return await cmdAssignRetry(args);
+    case 'team-info': return await cmdTeamInfo(args);
+    case 'team-task-list': return await cmdTeamTaskList(args);
+    case 'team-task-update': return await cmdTeamTaskUpdate(args);
+    case 'team-send-message': return await cmdTeamSendMessage(args);
+    case 'pipeline-state': return await cmdPipelineState(args);
+    case 'pipeline-advance': return await cmdPipelineAdvance(args);
+    case 'pipeline-init': return await cmdPipelineInit(args);
+    case 'pipeline-list': return await cmdPipelineList(args);
+    case 'ping': return await cmdPing(args);
     default:
       console.error('사용법: bridge.mjs <register|result|control|context|deregister|assign-async|assign-result|assign-status|assign-retry|team-info|team-task-list|team-task-update|team-send-message|pipeline-state|pipeline-advance|pipeline-init|pipeline-list|ping> [--옵션]');
       process.exit(1);
@@ -704,5 +680,5 @@ export async function main(argv = process.argv.slice(2)) {
 
 const selfRun = process.argv[1]?.replace(/\\/g, '/').endsWith('hub/bridge.mjs');
 if (selfRun) {
-  await main();
+  process.exitCode = await main() ? 0 : 1;
 }

package/hub/delegator/contracts.mjs

@@ -0,0 +1,38 @@
+export const DELEGATOR_MCP_SERVER_INFO = Object.freeze({
+  name: 'triflux-delegator',
+  version: '0.1.0',
+});
+
+export const DELEGATOR_TOOL_NAMES = Object.freeze({
+  delegate: 'delegate',
+  delegateReply: 'delegate-reply',
+  status: 'status',
+});
+
+export const DELEGATOR_PIPE_ACTIONS = Object.freeze({
+  delegate: 'delegator_delegate',
+  delegateReply: 'delegator_reply',
+  status: 'delegator_status',
+});
+
+export const DELEGATOR_JOB_STATUSES = Object.freeze([
+  'queued',
+  'running',
+  'waiting_reply',
+  'completed',
+  'failed',
+]);
+
+export const DELEGATOR_MODES = Object.freeze([
+  'sync',
+  'async',
+]);
+
+export const DELEGATOR_PROVIDERS = Object.freeze([
+  'auto',
+  'codex',
+  'gemini',
+  'claude',
+]);
+
+export const DELEGATOR_SCHEMA_URL = new URL('./schema/delegator-tools.schema.json', import.meta.url);

package/hub/delegator/index.mjs

@@ -0,0 +1,14 @@
+export {
+  DELEGATOR_JOB_STATUSES,
+  DELEGATOR_MCP_SERVER_INFO,
+  DELEGATOR_MODES,
+  DELEGATOR_PIPE_ACTIONS,
+  DELEGATOR_PROVIDERS,
+  DELEGATOR_SCHEMA_URL,
+  DELEGATOR_TOOL_NAMES,
+} from './contracts.mjs';
+export { DelegatorService } from './service.mjs';
+export {
+  getDelegatorMcpToolDefinitions,
+  loadDelegatorSchemaBundle,
+} from './tool-definitions.mjs';

package/hub/delegator/schema/delegator-tools.schema.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://triflux.dev/schema/hub/delegator-tools.schema.json",
+  "title": "Triflux Delegator MCP Tool Schemas",
+  "$defs": {
+    "Provider": {
+      "type": "string",
+      "enum": ["auto", "codex", "gemini", "claude"]
+    },
+    "Mode": {
+      "type": "string",
+      "enum": ["sync", "async"]
+    },
+    "JobStatus": {
+      "type": "string",
+      "enum": ["queued", "running", "waiting_reply", "completed", "failed"]
+    },
+    "McpProfile": {
+      "type": "string",
+      "enum": [
+        "auto",
+        "default",
+        "executor",
+        "designer",
+        "explore",
+        "reviewer",
+        "writer",
+        "none",
+        "implement",
+        "analyze",
+        "review",
+        "docs",
+        "minimal"
+      ]
+    },
+    "SearchTool": {
+      "type": "string",
+      "enum": ["exa", "brave-search", "tavily"]
+    },
+    "NullableDateTime": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "NullableString": {
+      "type": ["string", "null"]
+    },
+    "DelegateInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prompt"],
+      "properties": {
+        "prompt": {
+          "type": "string",
+          "minLength": 1
+        },
+        "provider": {
+          "$ref": "#/$defs/Provider",
+          "default": "auto"
+        },
+        "mode": {
+          "$ref": "#/$defs/Mode",
+          "default": "sync"
+        },
+        "agent_type": {
+          "type": "string",
+          "default": "executor",
+          "minLength": 1
+        },
+        "cwd": {
+          "type": "string",
+          "minLength": 1
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "session_key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "thread_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reset_session": {
+          "type": "boolean",
+          "default": false
+        },
+        "mcp_profile": {
+          "$ref": "#/$defs/McpProfile",
+          "default": "auto"
+        },
+        "search_tool": {
+          "$ref": "#/$defs/SearchTool"
+        },
+        "context_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1
+        },
+        "developer_instructions": {
+          "type": "string",
+          "minLength": 1
+        },
+        "compact_prompt": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "DelegateReplyInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["job_id", "reply"],
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reply": {
+          "type": "string",
+          "minLength": 1
+        },
+        "done": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
+    "StatusInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["job_id"],
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "DelegateOutput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ok",
+        "job_id",
+        "status",
+        "mode",
+        "provider_requested",
+        "provider_resolved",
+        "agent_type",
+        "transport",
+        "created_at",
+        "started_at",
+        "updated_at",
+        "completed_at",
+        "thread_id",
+        "session_key",
+        "conversation_open"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "job_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "$ref": "#/$defs/JobStatus"
+        },
+        "mode": {
+          "$ref": "#/$defs/Mode"
+        },
+        "provider_requested": {
+          "$ref": "#/$defs/Provider"
+        },
+        "provider_resolved": {
+          "type": ["string", "null"]
+        },
+        "agent_type": {
+          "type": "string",
+          "minLength": 1
+        },
+        "transport": {
+          "type": "string",
+          "minLength": 1
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "started_at": {
+          "$ref": "#/$defs/NullableDateTime"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "completed_at": {
+          "$ref": "#/$defs/NullableDateTime"
+        },
+        "output": {
+          "type": "string"
+        },
+        "stderr": {
+          "type": "string"
+        },
+        "error": {
+          "type": "string"
+        },
+        "thread_id": {
+          "$ref": "#/$defs/NullableString"
+        },
+        "session_key": {
+          "$ref": "#/$defs/NullableString"
+        },
+        "conversation_open": {
+          "type": "boolean"
+        }
+      }
+    }
+  },
+  "x-triflux-mcp-tools": [
+    {
+      "name": "delegate",
+      "description": "Create a new delegator job and optionally wait for the first result.",
+      "inputSchemaDef": "DelegateInput",
+      "outputSchemaDef": "DelegateOutput",
+      "pipeAction": "delegator_delegate"
+    },
+    {
+      "name": "delegate-reply",
+      "description": "Send a follow-up reply into an existing delegator conversation job.",
+      "inputSchemaDef": "DelegateReplyInput",
+      "outputSchemaDef": "DelegateOutput",
+      "pipeAction": "delegator_reply"
+    },
+    {
+      "name": "status",
+      "description": "Read the latest snapshot for an existing delegator job.",
+      "inputSchemaDef": "StatusInput",
+      "outputSchemaDef": "DelegateOutput",
+      "pipeAction": "delegator_status"
+    }
+  ]
+}

package/hub/delegator/service.mjs

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+
+import {
+  DELEGATOR_JOB_STATUSES,
+  DELEGATOR_MODES,
+  DELEGATOR_PROVIDERS,
+} from './contracts.mjs';
+import { getDelegatorMcpToolDefinitions } from './tool-definitions.mjs';
+
+function deepClone(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function assertKnown(enumValues, value, fieldName) {
+  if (value == null) return;
+  if (!enumValues.includes(value)) {
+    throw new Error(`Unsupported ${fieldName}: ${value}`);
+  }
+}
+
+export class DelegatorService {
+  constructor({
+    idFactory = randomUUID,
+    now = () => new Date(),
+  } = {}) {
+    this.idFactory = idFactory;
+    this.now = now;
+    this.jobs = new Map();
+  }
+
+  listToolDefinitions() {
+    return getDelegatorMcpToolDefinitions();
+  }
+
+  createJobSnapshot(input = {}) {
+    const timestamp = this.now().toISOString();
+    const jobId = input.job_id || this.idFactory();
+    const mode = input.mode || 'sync';
+    const providerRequested = input.provider || 'auto';
+
+    assertKnown(DELEGATOR_MODES, mode, 'mode');
+    assertKnown(DELEGATOR_PROVIDERS, providerRequested, 'provider');
+
+    return {
+      ok: true,
+      job_id: jobId,
+      status: 'queued',
+      mode,
+      provider_requested: providerRequested,
+      provider_resolved: null,
+      agent_type: input.agent_type || 'executor',
+      transport: 'resident-pending',
+      created_at: timestamp,
+      started_at: null,
+      updated_at: timestamp,
+      completed_at: null,
+      output: '',
+      stderr: '',
+      error: '',
+      thread_id: input.thread_id || null,
+      session_key: input.session_key || null,
+      conversation_open: false,
+    };
+  }
+
+  recordJob(snapshot) {
+    if (!snapshot?.job_id) {
+      throw new Error('job_id is required');
+    }
+    assertKnown(DELEGATOR_JOB_STATUSES, snapshot.status, 'status');
+    this.jobs.set(snapshot.job_id, deepClone(snapshot));
+    return this.getStatusSnapshot(snapshot.job_id);
+  }
+
+  getStatusSnapshot(jobId) {
+    const snapshot = this.jobs.get(jobId);
+    return snapshot ? deepClone(snapshot) : null;
+  }
+
+  async delegate(_input) {
+    throw new Error('Not implemented: wire delegate to the resident worker pool and Hub pipe action.');
+  }
+
+  async reply(_input) {
+    throw new Error('Not implemented: wire delegate-reply to the resident conversation handler.');
+  }
+
+  async status({ job_id: jobId } = {}) {
+    const snapshot = this.getStatusSnapshot(jobId);
+    if (snapshot) {
+      return snapshot;
+    }
+
+    const timestamp = this.now().toISOString();
+
+    return {
+      ok: false,
+      job_id: jobId || 'unknown-job',
+      status: 'failed',
+      mode: 'async',
+      provider_requested: 'auto',
+      provider_resolved: null,
+      agent_type: 'executor',
+      transport: 'resident-pending',
+      created_at: timestamp,
+      started_at: null,
+      updated_at: timestamp,
+      completed_at: null,
+      output: '',
+      stderr: '',
+      error: 'job not found',
+      thread_id: null,
+      session_key: null,
+      conversation_open: false,
+    };
+  }
+}

package/hub/delegator/tool-definitions.mjs

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+
+import { DELEGATOR_SCHEMA_URL } from './contracts.mjs';
+
+let schemaBundleCache = null;
+
+function deepClone(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function loadDelegatorSchemaBundle() {
+  if (schemaBundleCache) {
+    return schemaBundleCache;
+  }
+
+  schemaBundleCache = JSON.parse(readFileSync(DELEGATOR_SCHEMA_URL, 'utf8'));
+  return schemaBundleCache;
+}
+
+export function getDelegatorMcpToolDefinitions() {
+  const bundle = loadDelegatorSchemaBundle();
+  const defs = bundle.$defs || {};
+  const tools = Array.isArray(bundle['x-triflux-mcp-tools'])
+    ? bundle['x-triflux-mcp-tools']
+    : [];
+
+  return tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: deepClone(defs[tool.inputSchemaDef]),
+    outputSchema: deepClone(defs[tool.outputSchemaDef]),
+    pipeAction: tool.pipeAction,
+  }));
+}

package/hub/team/native.mjs

@@ -6,6 +6,10 @@
 // SKILL.md가 인라인 프롬프트를 사용하므로, 이 모듈은 CLI(tfx multi --native)에서
 // 팀 설정을 프로그래밍적으로 생성할 때 사용한다.
 
+import * as fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
 const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
 export const SLIM_WRAPPER_SUBAGENT_TYPE = "slim-wrapper";
 const ROUTE_LOG_RE = /\[tfx-route\]/i;
@@ -255,6 +259,103 @@ gemini/codex를 직접 호출하지 마라. psmux spawn이 tfx-route.sh를 통
 실패 여부는 metadata.result로 구분. pane 실패 시에도 반드시 TaskUpdate + SendMessage 후 종료.`;
 }
 
+/**
+ * tfx-route.sh가 남긴 로컬 결과 파일을 폴링해서 완료/대기 태스크를 분리한다.
+ * SendMessage 전달 지연이 있더라도 Phase 4에서 파일 기반으로 완료를 빠르게 감지하기 위한 보조 경로다.
+ *
+ * @param {string} teamName
+ * @param {string[]} expectedTaskIds
+ * @returns {Promise<{completed:Array<{taskId:string,result:string,summary:string}>, pending:string[]}>}
+ */
+export async function pollTeamResults(teamName, expectedTaskIds = []) {
+  const normalizedTaskIds = Array.from(
+    new Set(
+      (Array.isArray(expectedTaskIds) ? expectedTaskIds : [])
+        .map((taskId) => String(taskId || "").trim())
+        .filter(Boolean),
+    ),
+  );
+
+  if (!normalizedTaskIds.length) {
+    return { completed: [], pending: [] };
+  }
+
+  const normalizedTeamName = String(teamName || "").trim();
+  if (!normalizedTeamName) {
+    return { completed: [], pending: normalizedTaskIds };
+  }
+
+  const resultDir = path.join(os.homedir(), ".claude", "tfx-results", normalizedTeamName);
+
+  let entries;
+  try {
+    entries = await fs.readdir(resultDir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return { completed: [], pending: normalizedTaskIds };
+    }
+    throw error;
+  }
+
+  const availableFiles = new Set(
+    entries
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name),
+  );
+
+  const completedCandidates = await Promise.all(
+    normalizedTaskIds.map(async (taskId) => {
+      const fileName = `${taskId}.json`;
+      if (!availableFiles.has(fileName)) return null;
+
+      try {
+        const raw = await fs.readFile(path.join(resultDir, fileName), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+          taskId,
+          result: typeof parsed?.result === "string" ? parsed.result : "failed",
+          summary: typeof parsed?.summary === "string" ? parsed.summary : "",
+        };
+      } catch (error) {
+        if (error && error.code === "ENOENT") return null;
+        return {
+          taskId,
+          result: "failed",
+          summary: "결과 파일 파싱 실패",
+        };
+      }
+    }),
+  );
+
+  const completed = completedCandidates.filter(Boolean);
+  const completedTaskIds = new Set(completed.map((item) => item.taskId));
+  const pending = normalizedTaskIds.filter((taskId) => !completedTaskIds.has(taskId));
+
+  return { completed, pending };
+}
+
+/**
+ * 폴링 결과를 진행률 한 줄 요약으로 바꾼다.
+ *
+ * @param {{completed?:Array<{taskId:string,result:string}>, pending?:string[]}} pollResult
+ * @returns {string}
+ */
+export function formatPollReport(pollResult = {}) {
+  const completed = Array.isArray(pollResult.completed) ? pollResult.completed : [];
+  const pending = Array.isArray(pollResult.pending) ? pollResult.pending : [];
+  const total = completed.length + pending.length;
+
+  if (total === 0) return "0/0 완료";
+
+  const detail = completed
+    .map(({ taskId, result }) => `${taskId} ${result || "unknown"}`)
+    .join(", ");
+
+  return detail
+    ? `${completed.length}/${total} 완료 (${detail})`
+    : `${completed.length}/${total} 완료`;
+}
+
 /**
  * 팀 이름 생성 (타임스탬프 기반)
  * @returns {string}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "3.3.0-dev.7",
+  "version": "3.3.0-dev.8",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {