zigrix 0.2.0 → 0.2.2

package/dist/orchestration/dispatch.js

@@ -2,8 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { ROLE_HINTS } from '../agents/roles.js';
 import { resolveAbsolutePath } from '../config/defaults.js';
+import { composeOrchestratorPrompt, buildSpawnLabel } from './prompt-compose.js';
 import { appendEvent } from '../state/events.js';
-import { createTask, rebuildIndex, saveTask } from '../state/tasks.js';
+import { createTask, rebuildIndex, resolveTaskPaths, saveTask } from '../state/tasks.js';
 import { ensureBaseState } from '../state/paths.js';
 const BASELINE_REQUIRED_ROLES = ['orchestrator', 'qa'];
 const CANDIDATE_ROLE_ORDER = ['frontend', 'backend', 'system', 'security'];
@@ -137,47 +138,6 @@ function defaultExecutionUnits(scale, owners) {
         { id: 'U3', title: 'qa / regression', kind: 'verification', owner: owners.qaAgentId, workPackage: 'verification', dependsOn: ['U2'], parallel: false, status: 'OPEN', dod: 'qa evidence attached' },
     ];
 }
-function buildBootPrompt(task, options) {
-    return `## Orchestration Task Boot: ${task.taskId}
-- **Title:** ${task.title}
-- **Scale:** ${task.scale}
-- **Orchestrator:** ${options.orchestratorId}
-
----
-
-## ⚠️ 절대 규칙: QA 역할 워커 호출 필수
-
-**이 태스크는 QA 역할(${options.qaAgentId}) 워커 완료가 필수다.**
-
----
-
-## ⚡ 필수 첫 단계 (건너뛰기 금지)
-
-아래 명령을 **가장 먼저** 실행하라:
-
-\`\`\`bash
-zigrix task start ${task.taskId} --json
-\`\`\`
-
-그 후 태스크 메타를 확인하라:
-
-\`\`\`bash
-zigrix task status ${task.taskId} --json
-\`\`\`
-
-워커 호출 시:
-\`\`\`bash
-zigrix worker prepare --task-id ${task.taskId} --agent-id <workerId> --description "..." --json
-zigrix worker register --task-id ${task.taskId} --agent-id <workerId> --session-key <key> --json
-zigrix worker complete --task-id ${task.taskId} --agent-id <workerId> --session-key <key> --run-id <rid> --json
-\`\`\`
-
-최종 완료:
-\`\`\`bash
-zigrix task finalize ${task.taskId} --json
-\`\`\`
-`;
-}
 export function dispatchTask(paths, config, params) {
     ensureBaseState(paths);
     const selection = resolveAgentSelection(config, params.scale);
@@ -204,37 +164,21 @@ export function dispatchTask(paths, config, params) {
     task.orchestratorId = selection.orchestratorId;
     task.qaAgentId = selection.qaAgentId;
     saveTask(paths, task);
+    const taskPaths = resolveTaskPaths(paths, task.taskId);
     const promptPath = path.join(paths.promptsDir, `${task.taskId}-dispatch.md`);
-    const dispatchPrompt = [
-        `## Orchestration Task: ${task.taskId}`,
-        '',
-        '### 기본 정보',
-        `- **Title:** ${task.title}`,
-        `- **Scale:** ${task.scale}`,
-        `- **Orchestrator:** ${selection.orchestratorId}`,
-        `- **Baseline Required Agents:** ${selection.requiredAgents.join(', ')}`,
-        `- **Candidate Agents:** ${selection.candidateAgents.length > 0 ? selection.candidateAgents.join(', ') : '(none)'}`,
-        `- **Required Roles:** ${selection.requiredRoles.join(', ')}`,
-        `- **Optional Roles:** ${selection.optionalRoles.length > 0 ? selection.optionalRoles.join(', ') : '(none)'}`,
-        projectDir ? `- **Project Dir:** ${projectDir}` : '',
-        '',
-        '### 요청 내용',
-        params.description,
-        params.constraints ? `\n### 제약사항\n${params.constraints}` : '',
-        '',
-        '### 역할 매핑',
-        ...Object.entries(selection.roleAgentMap)
-            .filter(([, agentIds]) => agentIds.length > 0)
-            .map(([role, agentIds]) => `- ${role}: ${agentIds.join(', ')}`),
-        '',
-        '### 선택 규칙',
-        ...Object.entries(selection.selectionHints).map(([agentId, hint]) => `- ${agentId}: ${hint}`),
-    ].filter(Boolean).join('\n');
-    fs.writeFileSync(promptPath, `${dispatchPrompt}\n`, 'utf8');
-    const orchestratorPrompt = buildBootPrompt(task, {
+    const orchestratorLabel = buildSpawnLabel(task.taskId, selection.orchestratorId);
+    const orchestratorPrompt = composeOrchestratorPrompt({
+        paths,
+        task,
         orchestratorId: selection.orchestratorId,
         qaAgentId: selection.qaAgentId,
+        promptPath,
+        specPath: taskPaths.specPath,
+        metaPath: taskPaths.metaPath,
+        projectDir: projectDir ?? null,
+        constraints: params.constraints,
     });
+    fs.writeFileSync(promptPath, `${orchestratorPrompt}\n`, 'utf8');
     appendEvent(paths.eventsFile, {
         event: 'task_dispatched',
         taskId: task.taskId,
@@ -265,10 +209,11 @@ export function dispatchTask(paths, config, params) {
         requiredRoles: selection.requiredRoles,
         optionalRoles: selection.optionalRoles,
         roleAgentMap: selection.roleAgentMap,
-        specPath: path.join(paths.tasksDir, `${task.taskId}.md`),
-        metaPath: path.join(paths.tasksDir, `${task.taskId}.meta.json`),
+        specPath: taskPaths.specPath,
+        metaPath: taskPaths.metaPath,
         promptPath,
         orchestratorPrompt,
+        orchestratorLabel,
         projectDir: projectDir ?? null,
     };
 }

package/dist/orchestration/prompt-compose.d.ts

@@ -0,0 +1,35 @@
+import { type StandardAgentRole } from '../agents/roles.js';
+import type { ZigrixConfig } from '../config/schema.js';
+import { type ZigrixPaths } from '../state/paths.js';
+import { type ZigrixTask } from '../state/tasks.js';
+export declare function resolveAgentRole(config: ZigrixConfig, task: ZigrixTask, agentId: string): StandardAgentRole;
+export declare function buildSpawnLabel(taskId: string, agentId: string): string;
+export declare function composeOrchestratorPrompt(params: {
+    paths: ZigrixPaths;
+    task: ZigrixTask;
+    orchestratorId: string;
+    qaAgentId: string;
+    promptPath: string;
+    specPath: string;
+    metaPath: string;
+    projectDir?: string | null;
+    constraints?: string;
+}): string;
+export declare function composeWorkerPrompt(params: {
+    paths: ZigrixPaths;
+    config: ZigrixConfig;
+    task: ZigrixTask;
+    agentId: string;
+    description: string;
+    constraints?: string;
+    unitId?: string;
+    workPackage?: string;
+    dod?: string;
+    projectDir?: string | null;
+    promptPath: string;
+    specPath: string;
+    metaPath: string;
+}): {
+    prompt: string;
+    role: StandardAgentRole;
+};

package/dist/orchestration/prompt-compose.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inferStandardAgentRole, normalizeAgentRole, } from '../agents/roles.js';
+const ROLE_RULE_FILE = {
+    orchestrator: 'orchestrator-agent.md',
+    qa: 'qa-agent.md',
+    security: 'security-agent.md',
+    frontend: 'frontend-agent.md',
+    backend: 'backend-agent.md',
+    system: 'system-agent.md',
+};
+const WORKER_COMMON_RULE_FILE = 'worker-common.md';
+function bundledRulesDir() {
+    return path.resolve(fileURLToPath(new URL('../../rules/defaults', import.meta.url)));
+}
+function firstReadableRulePath(paths, fileName) {
+    const candidates = [
+        path.join(paths.rulesDir, fileName),
+        path.join(bundledRulesDir(), fileName),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function loadRuleText(paths, fileName) {
+    const resolved = firstReadableRulePath(paths, fileName);
+    if (!resolved) {
+        throw new Error(`required Zigrix rule file not found: ${fileName}`);
+    }
+    return fs.readFileSync(resolved, 'utf8').trim();
+}
+function compactBlock(text) {
+    return text.replace(/\r\n/g, '\n').trim();
+}
+function joinPromptBlocks(...blocks) {
+    return blocks
+        .map((block) => (typeof block === 'string' ? compactBlock(block) : ''))
+        .filter((block) => block.length > 0)
+        .join('\n\n---\n\n');
+}
+function renderRoleMap(task) {
+    const entries = Object.entries(task.roleAgentMap ?? {}).filter(([, ids]) => Array.isArray(ids) && ids.length > 0);
+    if (entries.length === 0)
+        return '- (none)';
+    return entries.map(([role, ids]) => `- ${role}: ${ids.join(', ')}`).join('\n');
+}
+function resolveTaskRole(task, agentId) {
+    if (typeof task.orchestratorId === 'string' && task.orchestratorId === agentId)
+        return 'orchestrator';
+    if (typeof task.qaAgentId === 'string' && task.qaAgentId === agentId)
+        return 'qa';
+    const roleMap = task.roleAgentMap;
+    if (roleMap && typeof roleMap === 'object') {
+        for (const [role, agentIds] of Object.entries(roleMap)) {
+            if (!Array.isArray(agentIds))
+                continue;
+            if (agentIds.includes(agentId)) {
+                const normalized = normalizeAgentRole(role);
+                if (normalized)
+                    return normalized;
+            }
+        }
+    }
+    return null;
+}
+export function resolveAgentRole(config, task, agentId) {
+    const fromTask = resolveTaskRole(task, agentId);
+    if (fromTask)
+        return fromTask;
+    const fromRegistry = config.agents.registry[agentId]?.role;
+    if (typeof fromRegistry === 'string') {
+        const normalized = normalizeAgentRole(fromRegistry);
+        if (normalized)
+            return normalized;
+    }
+    return inferStandardAgentRole({ agentId, theme: null });
+}
+export function buildSpawnLabel(taskId, agentId) {
+    return `[${agentId}] ${taskId}`;
+}
+export function composeOrchestratorPrompt(params) {
+    const roleRule = loadRuleText(params.paths, ROLE_RULE_FILE.orchestrator);
+    const overlay = [
+        `## Runtime Task Overlay: ${params.task.taskId}`,
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| taskId | ${params.task.taskId} |`,
+        `| title | ${params.task.title} |`,
+        `| scale | ${params.task.scale} |`,
+        `| orchestratorId | ${params.orchestratorId} |`,
+        `| qaAgentId | ${params.qaAgentId} |`,
+        `| specPath | ${params.specPath} |`,
+        `| metaPath | ${params.metaPath} |`,
+        `| promptPath | ${params.promptPath} |`,
+        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
+        '',
+        '### Authority Boundary',
+        '- 이 prompt는 Zigrix orchestrator role rule + task overlay를 합성한 canonical instruction이다.',
+        '- 메인 전용 skill (`zigrix-main-agent-guide`)이나 일반 OpenClaw skill discovery를 근거 규칙으로 삼지 않는다.',
+        '- 실제 runtime agentId는 아래 role mapping과 task metadata를 따른다.',
+        '',
+        '### Original Request',
+        params.task.description,
+        params.constraints ? `\n### Constraints\n${params.constraints}` : '',
+        '',
+        '### Runtime Role Mapping',
+        renderRoleMap(params.task),
+        '',
+        '### Required CLI Chain',
+        '1. `zigrix task start <taskId> --json`',
+        '2. `zigrix task status <taskId> --json`',
+        '3. 필요 워커마다 `zigrix worker prepare → sessions_spawn → zigrix worker register → zigrix worker complete`',
+        '4. evidence 수집/머지 확인',
+        '5. `zigrix task finalize <taskId> --json`',
+        '',
+        '### Worker Dispatch Contract',
+        '- worker spawn 전에 반드시 `zigrix worker prepare --task-id <taskId> --agent-id <workerId> --description "..." --json` 를 호출해 worker prompt / projectDir / spawnLabel을 확보한다.',
+        '- worker spawn 시 `agentId`, `label`, `cwd`, `task` 를 모두 명시한다.',
+        '- spawn 후에는 prepare 응답의 `spawnLabel` / `projectDir` 와 실제 `sessionKey` / `sessionId` 를 함께 `zigrix worker register` 에 전달한다.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return joinPromptBlocks(roleRule, overlay);
+}
+export function composeWorkerPrompt(params) {
+    const role = resolveAgentRole(params.config, params.task, params.agentId);
+    const roleRule = loadRuleText(params.paths, ROLE_RULE_FILE[role]);
+    const baseRule = role === 'orchestrator' ? '' : loadRuleText(params.paths, WORKER_COMMON_RULE_FILE);
+    const overlay = [
+        `## Runtime Worker Overlay: ${params.task.taskId}`,
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| taskId | ${params.task.taskId} |`,
+        `| title | ${params.task.title} |`,
+        `| scale | ${params.task.scale} |`,
+        `| agentId | ${params.agentId} |`,
+        `| role | ${role} |`,
+        `| specPath | ${params.specPath} |`,
+        `| metaPath | ${params.metaPath} |`,
+        `| promptPath | ${params.promptPath} |`,
+        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
+        '',
+        '### Authority Boundary',
+        '- 이 prompt는 Zigrix role rule + task overlay를 합성한 canonical worker instruction이다.',
+        '- 메인 전용 skill (`zigrix-main-agent-guide`)이나 일반 OpenClaw skill discovery를 근거 규칙으로 삼지 않는다.',
+        '- role rule 안의 예시 agent 이름보다 현재 overlay의 `agentId` / `role` / `projectDir` 를 우선 적용한다.',
+        '',
+        '### Assignment',
+        params.description,
+        params.constraints ? `\n### Constraints\n${params.constraints}` : '',
+        params.dod ? `\n### Definition of Done\n${params.dod}` : '',
+        params.unitId || params.workPackage
+            ? `\n### Execution Context\n- unitId: ${params.unitId ?? 'N/A'}\n- workPackage: ${params.workPackage ?? 'N/A'}`
+            : '',
+        '',
+        '### Completion Chain',
+        `- evidence collect: \`zigrix evidence collect --task-id ${params.task.taskId} --agent-id ${params.agentId} --summary "<result summary>"\``,
+        '- 결과 보고에는 taskId / sessionKey / runId / evidence / risks 를 포함한다.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return {
+        role,
+        prompt: joinPromptBlocks(baseRule, roleRule, overlay),
+    };
+}

package/dist/orchestration/worker.d.ts

@@ -1,8 +1,9 @@
+import type { ZigrixConfig } from '../config/schema.js';
 import { type ZigrixPaths } from '../state/paths.js';
 import { type ZigrixTask } from '../state/tasks.js';
 export declare const DEFAULT_REQUIRED_ROLES: readonly ["orchestrator", "qa"];
 export declare function resolveRequiredAgents(task: Partial<ZigrixTask> & Record<string, unknown>): string[];
-export declare function prepareWorker(paths: ZigrixPaths, params: {
+export declare function prepareWorker(paths: ZigrixPaths, config: ZigrixConfig, params: {
     taskId: string;
     agentId: string;
     description: string;
@@ -21,6 +22,8 @@ export declare function registerWorker(paths: ZigrixPaths, params: {
     unitId?: string;
     workPackage?: string;
     reason?: string;
+    label?: string;
+    projectDir?: string;
 }): Record<string, unknown> | null;
 export declare function completeWorker(paths: ZigrixPaths, params: {
     taskId: string;

package/dist/orchestration/worker.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { appendEvent } from '../state/events.js';
 import { ensureBaseState } from '../state/paths.js';
 import { loadTask, resolveTaskPaths, saveTask } from '../state/tasks.js';
+import { buildSpawnLabel, composeWorkerPrompt } from './prompt-compose.js';
 export const DEFAULT_REQUIRED_ROLES = ['orchestrator', 'qa'];
 function firstNonEmpty(...values) {
     for (const value of values) {
@@ -47,45 +48,51 @@ export function resolveRequiredAgents(task) {
     }
     return resolveDefaultRequiredAgents(task);
 }
-function renderPrompt(params) {
-    const sections = [
-        `## Worker Assignment: ${params.task.taskId}`,
-        '',
-        '| Field | Value |',
-        '|---|---|',
-        `| taskId | ${params.task.taskId} |`,
-        `| title | ${params.task.title} |`,
-        `| scale | ${params.task.scale} |`,
-        `| role | ${params.agentId} |`,
-        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
-        '',
-        '### Assignment',
-        params.description,
-    ];
-    if (params.constraints)
-        sections.push('', '### Constraints', params.constraints);
-    if (params.dod)
-        sections.push('', '### Definition of Done', params.dod);
-    if (params.unitId || params.workPackage) {
-        sections.push('', '### Execution Context', `- unitId: ${params.unitId ?? 'N/A'}`, `- workPackage: ${params.workPackage ?? 'N/A'}`);
-    }
-    sections.push('', '### Completion', '작업 완료 후 다음 순서를 반드시 따르라:', '', '1. **증적(evidence) 수집** — 작업 결과 증적을 먼저 기록한다:', '   ```bash', `   zigrix evidence collect --task-id ${params.task.taskId} --agent-id ${params.agentId} --summary "<작업 결과 요약>"`, '   ```', '2. **결과 보고** — 증적 수집 완료 후 결과와 근거를 명확히 보고하라.', '', '⚠️ 증적 없이 완료하면 finalize에서 incomplete 판정된다.');
-    return sections.join('\n');
+function normalizePathValue(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return null;
+    return path.resolve(value.trim());
+}
+function parseSessionKey(sessionKey) {
+    const matched = sessionKey.match(/^agent:([^:]+):subagent:([^:\s]+)$/);
+    if (!matched)
+        return null;
+    return { agentId: matched[1], sessionId: matched[2] };
 }
-export function prepareWorker(paths, params) {
+export function prepareWorker(paths, config, params) {
     ensureBaseState(paths);
     const task = loadTask(paths, params.taskId);
     if (!task)
         return null;
-    const projectDir = params.projectDir ?? task.projectDir;
-    const prompt = renderPrompt({ task, ...params, projectDir });
+    const taskPaths = resolveTaskPaths(paths, params.taskId);
     const promptPath = path.join(paths.promptsDir, `${params.taskId}-${params.agentId}.md`);
-    fs.writeFileSync(promptPath, `${prompt}\n`, 'utf8');
+    const projectDir = normalizePathValue(params.projectDir ?? task.projectDir ?? null);
+    const spawnLabel = buildSpawnLabel(params.taskId, params.agentId);
+    const composed = composeWorkerPrompt({
+        paths,
+        config,
+        task,
+        agentId: params.agentId,
+        description: params.description,
+        constraints: params.constraints,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        dod: params.dod,
+        projectDir,
+        promptPath,
+        specPath: taskPaths.specPath,
+        metaPath: taskPaths.metaPath,
+    });
+    fs.writeFileSync(promptPath, `${composed.prompt}\n`, 'utf8');
     task.workerSessions[params.agentId] = {
+        ...(task.workerSessions[params.agentId] ?? {}),
         status: 'prepared',
+        role: composed.role,
         unitId: params.unitId,
         workPackage: params.workPackage,
         promptPath,
+        expectedLabel: spawnLabel,
+        projectDir,
     };
     const required = task.requiredAgents.length > 0 ? task.requiredAgents : resolveRequiredAgents(task);
     if (!required.includes(params.agentId))
@@ -101,36 +108,60 @@ export function prepareWorker(paths, params) {
         status: 'IN_PROGRESS',
         unitId: params.unitId,
         workPackage: params.workPackage,
-        payload: { agentId: params.agentId, description: params.description, constraints: params.constraints ?? '', dod: params.dod ?? '', promptPath },
+        payload: {
+            agentId: params.agentId,
+            role: composed.role,
+            description: params.description,
+            constraints: params.constraints ?? '',
+            dod: params.dod ?? '',
+            promptPath,
+            spawnLabel,
+            projectDir,
+        },
     });
     return {
         ok: true,
         taskId: params.taskId,
         agentId: params.agentId,
+        role: composed.role,
         promptPath,
-        prompt,
+        prompt: composed.prompt,
         unitId: params.unitId,
         workPackage: params.workPackage,
-        projectDir: projectDir ?? null,
-        ...resolveTaskPaths(paths, params.taskId),
+        projectDir,
+        spawnLabel,
+        ...taskPaths,
     };
 }
-/**
- * Extract sessionId from a sessionKey of the form `agent:<agentId>:subagent:<sessionId>`.
- * Returns null if the sessionKey does not match the expected pattern.
- */
-function parseSessionIdFromKey(sessionKey) {
-    const matched = sessionKey.match(/^agent:[^:]+:subagent:([^:\s]+)$/);
-    return matched?.[1] ?? null;
-}
 export function registerWorker(paths, params) {
     const task = loadTask(paths, params.taskId);
     if (!task)
         return null;
-    // Resolve sessionId: use provided value, or fall back to parsing it from sessionKey
-    const resolvedSessionId = params.sessionId || parseSessionIdFromKey(params.sessionKey) || null;
+    const parsedKey = parseSessionKey(params.sessionKey);
+    if (parsedKey && parsedKey.agentId !== params.agentId) {
+        throw new Error(`worker register validation failed: sessionKey belongs to '${parsedKey.agentId}', expected '${params.agentId}'`);
+    }
+    const previous = task.workerSessions[params.agentId] ?? {};
+    const expectedLabel = firstNonEmpty(previous.expectedLabel) ?? buildSpawnLabel(params.taskId, params.agentId);
+    const providedLabel = firstNonEmpty(params.label);
+    if (!providedLabel) {
+        throw new Error('worker register validation failed: label is required (use spawnLabel from worker prepare).');
+    }
+    if (providedLabel !== expectedLabel) {
+        throw new Error(`worker register validation failed: label mismatch (expected '${expectedLabel}', got '${providedLabel}')`);
+    }
+    const expectedProjectDir = normalizePathValue(firstNonEmpty(previous.projectDir, task.projectDir));
+    const providedProjectDir = normalizePathValue(params.projectDir);
+    if (expectedProjectDir && !providedProjectDir) {
+        throw new Error('worker register validation failed: projectDir is required for this task.');
+    }
+    if (expectedProjectDir && providedProjectDir && expectedProjectDir !== providedProjectDir) {
+        throw new Error(`worker register validation failed: projectDir mismatch (expected '${expectedProjectDir}', got '${providedProjectDir}')`);
+    }
+    const resolvedSessionId = params.sessionId || parsedKey?.sessionId || null;
+    const resolvedProjectDir = providedProjectDir ?? expectedProjectDir;
     task.workerSessions[params.agentId] = {
-        ...(task.workerSessions[params.agentId] ?? {}),
+        ...previous,
         status: 'dispatched',
         sessionKey: params.sessionKey,
         runId: params.runId ?? '',
@@ -138,6 +169,9 @@ export function registerWorker(paths, params) {
         unitId: params.unitId,
         workPackage: params.workPackage,
         reason: params.reason ?? '',
+        label: providedLabel,
+        expectedLabel,
+        projectDir: resolvedProjectDir,
     };
     const required = task.requiredAgents.length > 0 ? task.requiredAgents : resolveRequiredAgents(task);
     if (!required.includes(params.agentId))
@@ -145,11 +179,37 @@ export function registerWorker(paths, params) {
     task.requiredAgents = required;
     saveTask(paths, task);
     appendEvent(paths.eventsFile, {
-        event: 'worker_dispatched', taskId: params.taskId, phase: 'execution', actor: 'zigrix', targetAgent: params.agentId, status: 'IN_PROGRESS',
-        sessionKey: params.sessionKey, sessionId: resolvedSessionId, unitId: params.unitId, workPackage: params.workPackage,
-        payload: { agentId: params.agentId, runId: params.runId ?? '', reason: params.reason ?? '' },
+        event: 'worker_dispatched',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: 'zigrix',
+        targetAgent: params.agentId,
+        status: 'IN_PROGRESS',
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        payload: {
+            agentId: params.agentId,
+            runId: params.runId ?? '',
+            reason: params.reason ?? '',
+            label: providedLabel,
+            projectDir: resolvedProjectDir,
+        },
     });
-    return { ok: true, taskId: params.taskId, agentId: params.agentId, sessionKey: params.sessionKey, runId: params.runId ?? '', sessionId: resolvedSessionId, unitId: params.unitId, workPackage: params.workPackage, status: 'dispatched' };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+        runId: params.runId ?? '',
+        sessionId: resolvedSessionId,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        label: providedLabel,
+        projectDir: resolvedProjectDir,
+        status: 'dispatched',
+    };
 }
 export function completeWorker(paths, params) {
     const task = loadTask(paths, params.taskId);
@@ -167,16 +227,36 @@ export function completeWorker(paths, params) {
     };
     saveTask(paths, task);
     appendEvent(paths.eventsFile, {
-        event: 'worker_done', taskId: params.taskId, phase: 'execution', actor: params.agentId, targetAgent: params.agentId,
-        status: (params.result ?? 'done') === 'blocked' ? 'BLOCKED' : 'IN_PROGRESS', sessionKey: params.sessionKey, sessionId: params.sessionId ?? null,
-        unitId: params.unitId ?? prev.unitId, workPackage: params.workPackage ?? prev.workPackage,
+        event: 'worker_done',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: params.agentId,
+        targetAgent: params.agentId,
+        status: (params.result ?? 'done') === 'blocked' ? 'BLOCKED' : 'IN_PROGRESS',
+        sessionKey: params.sessionKey,
+        sessionId: params.sessionId ?? null,
+        unitId: params.unitId ?? prev.unitId,
+        workPackage: params.workPackage ?? prev.workPackage,
         payload: { result: params.result ?? 'done', runId: params.runId },
     });
     const evidenceDir = path.join(paths.evidenceDir, params.taskId);
     const presentAgents = fs.existsSync(evidenceDir)
-        ? fs.readdirSync(evidenceDir).filter((file) => file.endsWith('.json') && file !== '_merged.json').map((file) => path.basename(file, '.json')).sort()
+        ? fs
+            .readdirSync(evidenceDir)
+            .filter((file) => file.endsWith('.json') && file !== '_merged.json')
+            .map((file) => path.basename(file, '.json'))
+            .sort()
         : [];
     const required = resolveRequiredAgents(task);
     const missingAgents = required.filter((agentId) => !presentAgents.includes(agentId));
-    return { ok: true, taskId: params.taskId, agentId: params.agentId, result: params.result ?? 'done', requiredAgents: required, presentEvidenceAgents: presentAgents, missingEvidenceAgents: missingAgents, allEvidenceCollected: missingAgents.length === 0 };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        result: params.result ?? 'done',
+        requiredAgents: required,
+        presentEvidenceAgents: presentAgents,
+        missingEvidenceAgents: missingAgents,
+        allEvidenceCollected: missingAgents.length === 0,
+    };
 }

package/dist/state/tasks.d.ts

@@ -91,6 +91,12 @@ export declare function createTask(paths: ZigrixPaths, params: {
     prefix?: string;
 }): ZigrixTask;
 export declare function updateTaskStatus(paths: ZigrixPaths, taskId: string, status: string): ZigrixTask | null;
+export declare function bindOrchestratorSession(paths: ZigrixPaths, params: {
+    taskId: string;
+    agentId: string;
+    sessionKey: string;
+    sessionId?: string;
+}): Record<string, unknown> | null;
 export declare function recordTaskProgress(paths: ZigrixPaths, params: {
     taskId: string;
     actor: string;

package/dist/state/tasks.js

@@ -170,6 +170,45 @@ export function updateTaskStatus(paths, taskId, status) {
     rebuildIndex(paths);
     return task;
 }
+export function bindOrchestratorSession(paths, params) {
+    const task = loadTask(paths, params.taskId);
+    if (!task)
+        return null;
+    const parsed = parseAgentSubagentSessionKey(params.sessionKey);
+    if (parsed && parsed.agentId !== params.agentId) {
+        throw new Error(`orchestrator bind validation failed: sessionKey belongs to '${parsed.agentId}', expected '${params.agentId}'`);
+    }
+    const resolvedSessionId = params.sessionId ?? parsed?.sessionId ?? null;
+    task.orchestratorId = params.agentId;
+    task.orchestratorSessionKey = params.sessionKey;
+    if (resolvedSessionId) {
+        task.orchestratorSessionId = resolvedSessionId;
+    }
+    else {
+        delete task.orchestratorSessionId;
+    }
+    saveTask(paths, task);
+    appendEvent(paths.eventsFile, {
+        event: 'orchestrator_bound',
+        taskId: params.taskId,
+        phase: 'dispatch',
+        actor: 'zigrix',
+        targetAgent: params.agentId,
+        status: task.status,
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        payload: { agentId: params.agentId },
+    });
+    rebuildIndex(paths);
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        status: task.status,
+    };
+}
 export function recordTaskProgress(paths, params) {
     const task = loadTask(paths, params.taskId);
     if (!task)