zigrix 0.1.1 → 0.2.0

package/dist/state/tasks.js

@@ -189,15 +189,226 @@ export function recordTaskProgress(paths, params) {
     rebuildIndex(paths);
     return event;
 }
-// ─── Stale policy ───────────────────────────────────────────────────────────
-export function findStaleTasks(paths, hours = 24) {
+function toNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function parseAgentSubagentSessionKey(sessionKey) {
+    const matched = sessionKey.match(/^agent:([^:]+):subagent:([^:\s]+)$/);
+    if (!matched)
+        return null;
+    return { agentId: matched[1], sessionId: matched[2] };
+}
+function resolveSessionIdFromSessionsJson(agentsStateDir, agentId, sessionKey) {
+    try {
+        const sessionsJsonPath = path.join(agentsStateDir, agentId, 'sessions', 'sessions.json');
+        const raw = JSON.parse(fs.readFileSync(sessionsJsonPath, 'utf8'));
+        const entry = raw[sessionKey];
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return null;
+        return toNonEmptyString(entry.sessionId);
+    }
+    catch {
+        return null;
+    }
+}
+function listDeletedSessionPaths(agentsStateDir, agentId, sessionId) {
+    const sessionsDir = path.join(agentsStateDir, agentId, 'sessions');
+    if (!fs.existsSync(sessionsDir))
+        return [];
+    const prefix = `${sessionId}.jsonl.deleted.`;
+    try {
+        return fs.readdirSync(sessionsDir)
+            .filter((name) => name.startsWith(prefix))
+            .sort((a, b) => b.localeCompare(a))
+            .map((name) => path.join(sessionsDir, name));
+    }
+    catch {
+        return [];
+    }
+}
+function collectTaskSessionRefs(task) {
+    const refs = [];
+    if (task.orchestratorSessionKey && task.orchestratorId) {
+        refs.push({
+            scope: 'orchestrator',
+            agentId: task.orchestratorId,
+            sessionKey: task.orchestratorSessionKey,
+            sessionId: task.orchestratorSessionId ?? null,
+        });
+    }
+    for (const [agentId, raw] of Object.entries(task.workerSessions ?? {})) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const data = raw;
+        const sessionKey = toNonEmptyString(data.sessionKey);
+        if (!sessionKey)
+            continue;
+        refs.push({
+            scope: 'worker',
+            agentId,
+            sessionKey,
+            sessionId: toNonEmptyString(data.sessionId),
+        });
+    }
+    return refs;
+}
+function diagnoseTaskSessions(task, agentsStateDir) {
+    if (!agentsStateDir)
+        return [];
+    return collectTaskSessionRefs(task).map((ref) => {
+        const parsed = parseAgentSubagentSessionKey(ref.sessionKey);
+        const agentId = parsed?.agentId ?? ref.agentId;
+        let resolvedSessionId = ref.sessionId;
+        let mappingSource = ref.sessionId ? 'explicit' : 'none';
+        if (!resolvedSessionId && parsed) {
+            resolvedSessionId = parsed.sessionId;
+            mappingSource = 'parsed';
+        }
+        if (!resolvedSessionId) {
+            const mappedSessionId = resolveSessionIdFromSessionsJson(agentsStateDir, agentId, ref.sessionKey);
+            if (mappedSessionId) {
+                resolvedSessionId = mappedSessionId;
+                mappingSource = 'sessions_json';
+            }
+        }
+        if (!resolvedSessionId) {
+            return {
+                scope: ref.scope,
+                agentId,
+                sessionKey: ref.sessionKey,
+                sessionId: null,
+                mappingSource,
+                state: 'missing',
+                reason: 'missing_session_mapping',
+                activePath: null,
+                deletedPath: null,
+            };
+        }
+        const activePath = path.join(agentsStateDir, agentId, 'sessions', `${resolvedSessionId}.jsonl`);
+        if (fs.existsSync(activePath)) {
+            return {
+                scope: ref.scope,
+                agentId,
+                sessionKey: ref.sessionKey,
+                sessionId: resolvedSessionId,
+                mappingSource,
+                state: 'active',
+                reason: null,
+                activePath,
+                deletedPath: null,
+            };
+        }
+        const deletedPaths = listDeletedSessionPaths(agentsStateDir, agentId, resolvedSessionId);
+        if (deletedPaths.length > 0) {
+            return {
+                scope: ref.scope,
+                agentId,
+                sessionKey: ref.sessionKey,
+                sessionId: resolvedSessionId,
+                mappingSource,
+                state: 'deleted',
+                reason: 'session_dead',
+                activePath: null,
+                deletedPath: deletedPaths[0],
+            };
+        }
+        return {
+            scope: ref.scope,
+            agentId,
+            sessionKey: ref.sessionKey,
+            sessionId: resolvedSessionId,
+            mappingSource,
+            state: 'missing',
+            reason: null,
+            activePath: null,
+            deletedPath: null,
+        };
+    });
+}
+function joinUniqueAgentIds(diagnoses, reason) {
+    const agentIds = Array.from(new Set(diagnoses.filter((item) => item.reason === reason).map((item) => item.agentId)));
+    return agentIds.join(', ') || 'unknown-agent';
+}
+function buildStaleGuidance(task, reasonCode, hours, diagnoses) {
+    if (reasonCode === 'session_dead') {
+        const agents = joinUniqueAgentIds(diagnoses, 'session_dead');
+        return {
+            reason: 'session_dead',
+            nextAction: `respawn the deleted OpenClaw session for ${agents} and re-register it before resuming ${task.taskId}`,
+            resumeHint: `start a fresh session for ${agents}, then update zigrix with the new session key/sessionId before continuing the blocked task`,
+            reportLine: `${task.taskId}: BLOCKED session_dead (${agents})`,
+        };
+    }
+    if (reasonCode === 'missing_session_mapping') {
+        const agents = joinUniqueAgentIds(diagnoses, 'missing_session_mapping');
+        return {
+            reason: 'missing_session_mapping',
+            nextAction: `repair or re-register the missing session mapping for ${agents} before resuming ${task.taskId}`,
+            resumeHint: `re-run worker/orchestrator registration with --session-key and --session-id so zigrix can resolve the backing OpenClaw session`,
+            reportLine: `${task.taskId}: BLOCKED missing_session_mapping (${agents})`,
+        };
+    }
+    return {
+        reason: 'stale_timeout',
+        nextAction: `inspect the latest progress for ${task.taskId} and either report, refresh progress, or respawn the worker after ${hours}h of inactivity`,
+        resumeHint: 'check task status/events/evidence, then continue with a fresh worker registration if the original session is no longer active',
+        reportLine: `${task.taskId}: BLOCKED stale_timeout (> ${hours}h)`,
+    };
+}
+function buildStaleTaskSummary(task, hours, agentsStateDir, fallbackReason = 'stale_timeout') {
     const cutoff = Date.now() - hours * 3600 * 1000;
-    return listTasks(paths).filter((task) => task.status === 'IN_PROGRESS' && Date.parse(task.updatedAt) < cutoff);
+    const timedOut = Date.parse(task.updatedAt) < cutoff;
+    const diagnoses = diagnoseTaskSessions(task, agentsStateDir);
+    const hasDeletedSession = diagnoses.some((item) => item.reason === 'session_dead');
+    const hasMissingMapping = diagnoses.some((item) => item.reason === 'missing_session_mapping');
+    if (!hasDeletedSession && !timedOut)
+        return null;
+    const reasons = new Set();
+    if (timedOut)
+        reasons.add('stale_timeout');
+    if (hasDeletedSession)
+        reasons.add('session_dead');
+    if (hasMissingMapping)
+        reasons.add('missing_session_mapping');
+    const reasonCode = hasDeletedSession
+        ? 'session_dead'
+        : hasMissingMapping && timedOut
+            ? 'missing_session_mapping'
+            : 'stale_timeout';
+    const guidance = buildStaleGuidance(task, reasonCode, hours, diagnoses);
+    const reason = reasonCode === 'stale_timeout' ? fallbackReason : guidance.reason;
+    return {
+        taskId: task.taskId,
+        title: task.title,
+        updatedAt: task.updatedAt,
+        hoursThreshold: hours,
+        timedOut,
+        reason,
+        reasonCode,
+        reasons: Array.from(reasons),
+        nextAction: guidance.nextAction,
+        resumeHint: guidance.resumeHint,
+        reportLine: guidance.reportLine,
+        sessions: diagnoses,
+    };
+}
+export function findStaleTasks(paths, hours = 24, options = {}) {
+    return listTasks(paths)
+        .filter((task) => task.status === 'IN_PROGRESS')
+        .map((task) => buildStaleTaskSummary(task, hours, options.agentsStateDir, options.fallbackReason ?? 'stale_timeout'))
+        .filter((task) => task !== null);
 }
-export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout') {
-    const staleTasks = findStaleTasks(paths, hours);
-    const changed = staleTasks.map((task) => {
+export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout', options = {}) {
+    const staleTasks = findStaleTasks(paths, hours, { ...options, fallbackReason: reason });
+    const changed = staleTasks.map((summary) => {
+        const task = loadTask(paths, summary.taskId);
+        if (!task)
+            return null;
         task.status = 'BLOCKED';
+        task.nextAction = summary.nextAction;
+        task.resumeHint = summary.resumeHint;
+        task.staleReason = summary.reasonCode;
+        task.staleReasons = summary.reasons;
         saveTask(paths, task);
         const event = appendEvent(paths.eventsFile, {
             event: 'task_blocked',
@@ -205,12 +416,33 @@ export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout') {
             phase: 'recovery',
             actor: 'zigrix',
             status: 'BLOCKED',
-            payload: { reason, previousStatus: 'IN_PROGRESS', hoursThreshold: hours },
+            payload: {
+                reason: summary.reason,
+                reasonCode: summary.reasonCode,
+                reasons: summary.reasons,
+                previousStatus: 'IN_PROGRESS',
+                hoursThreshold: hours,
+                timedOut: summary.timedOut,
+                nextAction: summary.nextAction,
+                resumeHint: summary.resumeHint,
+                reportLine: summary.reportLine,
+                sessions: summary.sessions,
+            },
         });
-        return { taskId: task.taskId, event };
-    });
+        return {
+            taskId: task.taskId,
+            reason: summary.reason,
+            reasonCode: summary.reasonCode,
+            reasons: summary.reasons,
+            nextAction: summary.nextAction,
+            resumeHint: summary.resumeHint,
+            reportLine: summary.reportLine,
+            sessions: summary.sessions,
+            event,
+        };
+    }).filter((item) => item !== null);
     rebuildIndex(paths);
-    return { ok: true, hours, reason, count: changed.length, changed };
+    return { ok: true, hours, requestedReason: reason, count: changed.length, changed };
 }
 // ─── Index ──────────────────────────────────────────────────────────────────
 export function rebuildIndex(paths) {

package/dist/state/verify.js

@@ -9,6 +9,12 @@ function safeReadJson(filePath) {
         return null;
     }
 }
+function sortedStrings(value) {
+    return Array.isArray(value) ? value.map(String).sort() : [];
+}
+function sameStringArray(left, right) {
+    return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
+}
 function verifyTask(paths, task) {
     const issues = [];
     const evidenceDir = path.join(paths.evidenceDir, task.taskId);
@@ -17,34 +23,58 @@ function verifyTask(paths, task) {
     const presentEvidenceAgents = fs.existsSync(evidenceDir)
         ? fs.readdirSync(evidenceDir).filter((name) => name.endsWith('.json') && name !== '_merged.json').map((name) => path.basename(name, '.json')).sort()
         : [];
-    const requiredAgents = Array.isArray(task.requiredAgents) ? task.requiredAgents.map(String) : [];
+    const requiredAgents = Array.isArray(task.requiredAgents) ? task.requiredAgents.map(String).sort() : [];
     const workerAgents = Object.keys(task.workerSessions ?? {}).sort();
+    const requiredRoles = Array.isArray(task.requiredRoles) ? task.requiredRoles.map(String).sort() : [];
+    const roleAgentMap = task.roleAgentMap && typeof task.roleAgentMap === 'object'
+        ? task.roleAgentMap
+        : {};
     for (const agentId of requiredAgents) {
         if (!workerAgents.includes(agentId) && !presentEvidenceAgents.includes(agentId)) {
             issues.push(`required agent '${agentId}' has neither worker session nor evidence`);
         }
     }
+    for (const role of requiredRoles) {
+        const mappedAgents = Array.isArray(roleAgentMap[role]) ? roleAgentMap[role].map(String).filter(Boolean) : [];
+        if (mappedAgents.length === 0) {
+            issues.push(`required role '${role}' has no mapped agent in roleAgentMap`);
+            continue;
+        }
+        const hasActiveArtifact = mappedAgents.some((agentId) => requiredAgents.includes(agentId) || workerAgents.includes(agentId) || presentEvidenceAgents.includes(agentId));
+        if (!hasActiveArtifact) {
+            issues.push(`required role '${role}' has no required agent, worker session, or evidence`);
+        }
+    }
     if (merged) {
-        const mergedPresent = Array.isArray(merged.presentAgents) ? merged.presentAgents.map(String).sort() : [];
-        const mergedMissing = Array.isArray(merged.missingAgents) ? merged.missingAgents.map(String).sort() : [];
+        const mergedPresent = sortedStrings(merged.presentAgents);
+        const mergedMissing = sortedStrings(merged.missingAgents);
         const computedMissing = requiredAgents.filter((agentId) => !presentEvidenceAgents.includes(agentId)).sort();
-        if (JSON.stringify(mergedPresent) !== JSON.stringify(presentEvidenceAgents)) {
+        if (!sameStringArray(mergedPresent, presentEvidenceAgents)) {
             issues.push('merged presentAgents does not match evidence files');
         }
-        if (JSON.stringify(mergedMissing) !== JSON.stringify(computedMissing)) {
+        if (!sameStringArray(mergedMissing, computedMissing)) {
             issues.push('merged missingAgents does not match requiredAgents/evidence files');
         }
-        if (task.status === 'REPORTED' && merged.complete !== true) {
-            issues.push('task is REPORTED but merged evidence is incomplete');
+        const qaVerification = merged.qaVerification;
+        const qaVerificationComplete = Boolean(qaVerification &&
+            typeof qaVerification === 'object' &&
+            !Array.isArray(qaVerification) &&
+            qaVerification.complete === true);
+        if (['DONE_PENDING_REPORT', 'REPORTED'].includes(task.status) && merged.complete !== true) {
+            issues.push(`task is ${task.status} but merged evidence is incomplete`);
+        }
+        if (['DONE_PENDING_REPORT', 'REPORTED'].includes(task.status) && merged.qaPresent === true && !qaVerificationComplete) {
+            issues.push('task reached reporting state without DoD↔test verification mapping for QA evidence');
         }
     }
-    else if (task.status === 'REPORTED') {
-        issues.push('task is REPORTED but merged evidence is missing');
+    else if (['DONE_PENDING_REPORT', 'REPORTED'].includes(task.status)) {
+        issues.push(`task is ${task.status} but merged evidence is missing`);
     }
     return {
         taskId: task.taskId,
         status: task.status,
         requiredAgents,
+        requiredRoles,
         workerAgents,
         presentEvidenceAgents,
         mergedExists: Boolean(merged),
@@ -52,14 +82,62 @@ function verifyTask(paths, task) {
         issues,
     };
 }
+function verifyIndex(paths, tasks) {
+    const issues = [];
+    const index = safeReadJson(paths.indexFile);
+    if (!index) {
+        issues.push('index.json is missing or unreadable');
+        return { ok: false, issues };
+    }
+    const counts = index.counts && typeof index.counts === 'object' ? index.counts : {};
+    const statusBuckets = index.statusBuckets && typeof index.statusBuckets === 'object'
+        ? index.statusBuckets
+        : {};
+    const taskSummaries = index.taskSummaries && typeof index.taskSummaries === 'object'
+        ? index.taskSummaries
+        : {};
+    const activeTasks = index.activeTasks && typeof index.activeTasks === 'object'
+        ? index.activeTasks
+        : {};
+    if (Number(counts.tasks ?? -1) !== tasks.length) {
+        issues.push(`index counts.tasks mismatch: expected ${tasks.length}, got ${String(counts.tasks ?? 'missing')}`);
+    }
+    const expectedBuckets = new Map();
+    for (const task of tasks) {
+        expectedBuckets.set(task.status, [...(expectedBuckets.get(task.status) ?? []), task.taskId]);
+        const summary = taskSummaries[task.taskId];
+        if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+            issues.push(`taskSummaries missing entry for ${task.taskId}`);
+            continue;
+        }
+        if (summary.status !== task.status) {
+            issues.push(`taskSummaries status mismatch for ${task.taskId}`);
+        }
+    }
+    for (const [status, taskIds] of expectedBuckets.entries()) {
+        const indexed = sortedStrings(statusBuckets[status]);
+        if (!sameStringArray(indexed, taskIds)) {
+            issues.push(`statusBuckets mismatch for ${status}`);
+        }
+    }
+    const expectedActiveStatuses = new Set(['OPEN', 'IN_PROGRESS', 'BLOCKED', 'DONE_PENDING_REPORT']);
+    const expectedActiveTaskIds = tasks.filter((task) => expectedActiveStatuses.has(task.status)).map((task) => task.taskId).sort();
+    const indexedActiveTaskIds = Object.keys(activeTasks).sort();
+    if (!sameStringArray(indexedActiveTaskIds, expectedActiveTaskIds)) {
+        issues.push('activeTasks mismatch with task statuses');
+    }
+    return { ok: issues.length === 0, issues };
+}
 export function verifyState(paths) {
     const tasks = listTasks(paths);
     const checks = tasks.map((task) => verifyTask(paths, task));
     const failures = checks.filter((item) => item.ok === false);
+    const indexCheck = verifyIndex(paths, tasks);
     return {
-        ok: failures.length === 0,
+        ok: failures.length === 0 && indexCheck.ok === true,
         taskCount: tasks.length,
-        failedCount: failures.length,
+        failedCount: failures.length + (indexCheck.ok === true ? 0 : 1),
         checks,
+        index: indexCheck,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigrix",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Multi-project parallel task orchestration CLI for agent-assisted development",
   "license": "Apache-2.0",