zigrix 0.1.1 → 0.2.0

package/dist/onboard.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { addAgent } from './agents/registry.js';
-import { inferStandardAgentRole, STANDARD_AGENT_ROLES } from './agents/roles.js';
+import { inferStandardAgentRole, STANDARD_AGENT_ROLES, } from './agents/roles.js';
 import { LEGACY_DEFAULT_GATEWAY_URL, resolveAbsolutePath } from './config/defaults.js';
 import { loadConfig, writeConfigFile, writeDefaultConfig } from './config/load.js';
 import { ensureBaseState, resolvePaths } from './state/paths.js';
@@ -40,7 +40,11 @@ function normalizeGatewayUrl(input) {
     return parsed.toString().replace(/\/+$/, '');
 }
 function coerceGatewayPort(value) {
-    const n = typeof value === 'string' && value.trim().length > 0 ? Number(value) : typeof value === 'number' ? value : NaN;
+    const n = typeof value === 'string' && value.trim().length > 0
+        ? Number(value)
+        : typeof value === 'number'
+            ? value
+            : NaN;
     if (!Number.isFinite(n) || n <= 0 || n > 65535)
         return null;
     return Math.trunc(n);
@@ -62,6 +66,41 @@ export function resolveOpenClawGatewayToken(openclawConfig) {
     const token = openclawConfig?.gateway?.auth?.token;
     return typeof token === 'string' && token.trim().length > 0 ? token : null;
 }
+function resolveExistingExecutablePath(candidate) {
+    try {
+        const stat = fs.lstatSync(candidate);
+        if (stat.isSymbolicLink()) {
+            return path.resolve(fs.realpathSync(candidate));
+        }
+        return fs.existsSync(candidate) ? path.resolve(candidate) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveGlobalPackageBin(params) {
+    try {
+        const globalRoot = execSync('npm root -g', { encoding: 'utf8', timeout: 3000 }).trim();
+        if (!globalRoot)
+            return null;
+        const packageRoot = path.join(globalRoot, params.packageName);
+        const packageJsonPath = path.join(packageRoot, 'package.json');
+        if (!fs.existsSync(packageJsonPath))
+            return null;
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        const binEntry = typeof pkg.bin === 'string'
+            ? pkg.bin
+            : pkg.bin && typeof pkg.bin === 'object'
+                ? pkg.bin[params.binName]
+                : null;
+        if (typeof binEntry !== 'string' || binEntry.trim().length === 0)
+            return null;
+        return resolveExistingExecutablePath(path.resolve(packageRoot, binEntry));
+    }
+    catch {
+        return null;
+    }
+}
 function shouldReplaceStoredGatewayUrl(stored, detected) {
     const trimmed = stored.trim();
     if (!trimmed)
@@ -81,11 +120,17 @@ function shouldReplaceStoredGatewayUrl(stored, detected) {
  * Returns the resolved absolute path or null.
  */
 export function resolveOpenClawBin(openclawHome) {
+    const pickCandidate = (candidate) => {
+        if (!candidate)
+            return null;
+        return resolveExistingExecutablePath(candidate);
+    };
     // Strategy 1: which/where
     try {
         const result = execSync('which openclaw', { encoding: 'utf8', timeout: 3000 }).trim();
-        if (result && fs.existsSync(result))
-            return path.resolve(result);
+        const resolved = pickCandidate(result);
+        if (resolved)
+            return resolved;
     }
     catch {
         // not in PATH
@@ -95,44 +140,58 @@ export function resolveOpenClawBin(openclawHome) {
     const nodeVersion = process.versions.node;
     const majorMinorPatch = nodeVersion; // e.g., "25.5.0"
     const nvmCandidate = path.join(home, '.nvm', 'versions', 'node', `v${majorMinorPatch}`, 'bin', 'openclaw');
-    if (fs.existsSync(nvmCandidate))
-        return path.resolve(nvmCandidate);
+    const nvmResolved = pickCandidate(nvmCandidate);
+    if (nvmResolved)
+        return nvmResolved;
     // Also try nvm current symlink
     const nvmCurrent = path.join(home, '.nvm', 'current', 'bin', 'openclaw');
-    if (fs.existsSync(nvmCurrent))
-        return path.resolve(nvmCurrent);
+    const nvmCurrentResolved = pickCandidate(nvmCurrent);
+    if (nvmCurrentResolved)
+        return nvmCurrentResolved;
     // Volta
     const voltaCandidate = path.join(home, '.volta', 'bin', 'openclaw');
-    if (fs.existsSync(voltaCandidate))
-        return path.resolve(voltaCandidate);
+    const voltaResolved = pickCandidate(voltaCandidate);
+    if (voltaResolved)
+        return voltaResolved;
     // fnm
     const fnmCandidate = path.join(home, '.fnm', 'node-versions', `v${majorMinorPatch}`, 'installation', 'bin', 'openclaw');
-    if (fs.existsSync(fnmCandidate))
-        return path.resolve(fnmCandidate);
+    const fnmResolved = pickCandidate(fnmCandidate);
+    if (fnmResolved)
+        return fnmResolved;
     // Strategy 3: well-known system paths
     for (const dir of ['/usr/local/bin', path.join(home, '.local', 'bin')]) {
         const candidate = path.join(dir, 'openclaw');
-        if (fs.existsSync(candidate))
-            return path.resolve(candidate);
-    }
-    // Strategy 4: node global lib path (npm root -g)
+        const resolved = pickCandidate(candidate);
+        if (resolved)
+            return resolved;
+    }
+    // Strategy 4: resolve the actual global package bin target (not the wrapper path)
+    const globalPackageBin = resolveGlobalPackageBin({
+        packageName: 'openclaw',
+        binName: 'openclaw',
+    });
+    if (globalPackageBin)
+        return globalPackageBin;
+    // Strategy 5: node global bin wrapper path (npm root -g)
     try {
         const globalRoot = execSync('npm root -g', { encoding: 'utf8', timeout: 3000 }).trim();
         if (globalRoot) {
             const candidate = path.join(path.dirname(globalRoot), 'bin', 'openclaw');
-            if (fs.existsSync(candidate))
-                return path.resolve(candidate);
+            const resolved = pickCandidate(candidate);
+            if (resolved)
+                return resolved;
         }
     }
     catch {
         // npm not available or timed out
     }
-    // Strategy 5: from openclaw home
+    // Strategy 6: from openclaw home
     if (openclawHome) {
         // Some installations place a bin reference inside the home dir
         const homeBin = path.join(openclawHome, 'bin', 'openclaw');
-        if (fs.existsSync(homeBin))
-            return path.resolve(homeBin);
+        const resolved = pickCandidate(homeBin);
+        if (resolved)
+            return resolved;
     }
     return null;
 }
@@ -151,10 +210,11 @@ export function registerAgents(config, agents, roleAssignments) {
             skipped.push(agent.id);
             continue;
         }
-        const role = roleAssignments?.[agent.id] ?? inferStandardAgentRole({
-            agentId: agent.id,
-            theme: agent.identity?.theme ?? null,
-        });
+        const role = roleAssignments?.[agent.id] ??
+            inferStandardAgentRole({
+                agentId: agent.id,
+                theme: agent.identity?.theme ?? null,
+            });
         const result = addAgent(current, {
             id: agent.id,
             role,
@@ -326,9 +386,7 @@ export function findSystemBinDir() {
  */
 export function findUserBinDir() {
     const home = process.env.HOME ?? '~';
-    const candidates = [
-        path.join(home, '.local', 'bin'),
-    ];
+    const candidates = [path.join(home, '.local', 'bin')];
     // Also check PATH dirs that are user-writable
     const pathEnv = process.env.PATH ?? '';
     for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
@@ -346,6 +404,9 @@ export function findUserBinDir() {
     }
     return candidates[0];
 }
+function pathTargetsSameLocation(sourcePath, targetPath) {
+    return path.resolve(sourcePath) === path.resolve(targetPath);
+}
 /**
  * Ensure zigrix is reachable from PATH.
  * Priority:
@@ -374,6 +435,9 @@ export function ensureZigrixInPath(opts) {
         : findSystemBinDir();
     if (systemBinDir) {
         const symlinkPath = path.join(systemBinDir, 'zigrix');
+        if (pathTargetsSameLocation(binEntry, symlinkPath)) {
+            return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
+        }
         try {
             // Remove stale entry if present
             try {
@@ -414,6 +478,9 @@ export function ensureZigrixInPath(opts) {
         };
     }
     const symlinkPath = path.join(userBinDir, 'zigrix');
+    if (pathTargetsSameLocation(binEntry, symlinkPath)) {
+        return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
+    }
     try {
         // Remove existing if present (stale symlink or old wrapper)
         if (fs.existsSync(symlinkPath) || fs.lstatSync(symlinkPath).isSymbolicLink()) {
@@ -443,7 +510,9 @@ export function ensureZigrixInPath(opts) {
     }
     // Check if userBinDir is actually in PATH
     const pathEnv = process.env.PATH ?? '';
-    const inPath = pathEnv.split(path.delimiter).some((d) => path.resolve(d) === path.resolve(userBinDir));
+    const inPath = pathEnv
+        .split(path.delimiter)
+        .some((d) => path.resolve(d) === path.resolve(userBinDir));
     const warning = inPath
         ? null
         : `Created zigrix at ${symlinkPath}, but ${userBinDir} is not in your PATH. Add it:\n  export PATH="${userBinDir}:$PATH"`;
@@ -495,6 +564,9 @@ export function ensureOpenClawInPath(opts) {
         : findSystemBinDir();
     if (systemBinDir) {
         const symlinkPath = path.join(systemBinDir, 'openclaw');
+        if (pathTargetsSameLocation(binPath, symlinkPath)) {
+            return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
+        }
         try {
             // Remove stale entry if present
             try {
@@ -535,6 +607,9 @@ export function ensureOpenClawInPath(opts) {
         };
     }
     const symlinkPath = path.join(userBinDir, 'openclaw');
+    if (pathTargetsSameLocation(binPath, symlinkPath)) {
+        return { alreadyInPath: true, symlinkCreated: false, symlinkPath: null, warning: null };
+    }
     try {
         // Remove existing if present (stale symlink)
         if (fs.existsSync(symlinkPath) || fs.lstatSync(symlinkPath).isSymbolicLink()) {
@@ -558,7 +633,9 @@ export function ensureOpenClawInPath(opts) {
     }
     // Check if userBinDir is actually in PATH
     const pathEnv = process.env.PATH ?? '';
-    const inPath = pathEnv.split(path.delimiter).some((d) => path.resolve(d) === path.resolve(userBinDir));
+    const inPath = pathEnv
+        .split(path.delimiter)
+        .some((d) => path.resolve(d) === path.resolve(userBinDir));
     const warning = inPath
         ? null
         : `Created openclaw at ${symlinkPath}, but ${userBinDir} is not in your PATH. Add it:\n  export PATH="${userBinDir}:$PATH"`;
@@ -605,7 +682,13 @@ export function registerSkills(openclawHome) {
         fs.mkdirSync(openclawSkillsDir, { recursive: true });
     }
     catch (e) {
-        return { registered, skipped, failed: [`Could not create ${openclawSkillsDir}: ${e instanceof Error ? e.message : String(e)}`] };
+        return {
+            registered,
+            skipped,
+            failed: [
+                `Could not create ${openclawSkillsDir}: ${e instanceof Error ? e.message : String(e)}`,
+            ],
+        };
     }
     let skillDirs;
     try {
@@ -681,7 +764,10 @@ export async function promptAgentSelection(agents) {
     }
 }
 export async function promptAgentRoleAssignments(agents) {
-    const defaults = Object.fromEntries(agents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]));
+    const defaults = Object.fromEntries(agents.map((agent) => [
+        agent.id,
+        inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null }),
+    ]));
     if (agents.length === 0)
         return defaults;
     try {
@@ -825,7 +911,8 @@ export async function runOnboard(options) {
     const { configPath } = ensureConfig();
     const loaded = loadConfig({ configPath });
     let nextConfig = structuredClone(loaded.config);
-    const configuredWorkspace = nextConfig.workspace.projectsBaseDir?.trim() || path.join(nextConfig.paths.baseDir, 'workspace');
+    const configuredWorkspace = nextConfig.workspace.projectsBaseDir?.trim() ||
+        path.join(nextConfig.paths.baseDir, 'workspace');
     const desiredWorkspace = options.projectsBaseDir
         ? resolveAbsolutePath(options.projectsBaseDir)
         : options.yes
@@ -888,7 +975,10 @@ export async function runOnboard(options) {
         }
         if (selectedAgents.length > 0) {
             const roleAssignments = options.yes
-                ? Object.fromEntries(selectedAgents.map((agent) => [agent.id, inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null })]))
+                ? Object.fromEntries(selectedAgents.map((agent) => [
+                    agent.id,
+                    inferStandardAgentRole({ agentId: agent.id, theme: agent.identity?.theme ?? null }),
+                ]))
                 : await promptAgentRoleAssignments(selectedAgents);
             const result = registerAgents(nextConfig, selectedAgents, roleAssignments);
             nextConfig = result.config;
@@ -996,7 +1086,12 @@ export async function runOnboard(options) {
         }
     }
     // 7. Stabilize PATH — ensure openclaw is reachable from non-login shells
-    let openclawPathResult = { alreadyInPath: false, symlinkCreated: false, symlinkPath: null, warning: null };
+    let openclawPathResult = {
+        alreadyInPath: false,
+        symlinkCreated: false,
+        symlinkPath: null,
+        warning: null,
+    };
     if (openclawBinPath) {
         openclawPathResult = ensureOpenClawInPath();
         if (openclawPathResult.symlinkCreated) {

package/dist/orchestration/evidence.d.ts

@@ -1,4 +1,8 @@
 import { type ZigrixPaths } from '../state/paths.js';
+export type VerificationMapping = {
+    dod: string;
+    test: string;
+};
 export declare function collectEvidence(paths: ZigrixPaths, params: {
     taskId: string;
     agentId: string;
@@ -10,6 +14,9 @@ export declare function collectEvidence(paths: ZigrixPaths, params: {
     summary?: string;
     toolResults?: string[];
     notes?: string;
+    dodItems?: string[];
+    testCases?: string[];
+    verificationMappings?: VerificationMapping[];
     limit?: number;
 }): Record<string, unknown> | null;
 export declare function mergeEvidence(paths: ZigrixPaths, params: {

package/dist/orchestration/evidence.js

@@ -57,6 +57,29 @@ function resolveQaAgentId(task) {
     const fallback = required.find((agentId) => String(agentId).trim().length > 0 && String(agentId).trim() !== orchestratorId);
     return fallback ? String(fallback).trim() : null;
 }
+function sanitizeVerificationMapping(mapping) {
+    const dod = mapping.dod.trim();
+    const test = mapping.test.trim();
+    if (!dod || !test)
+        return null;
+    return { dod, test };
+}
+function collectVerificationMappings(evidence) {
+    const verification = evidence.verification;
+    if (!verification || typeof verification !== 'object' || Array.isArray(verification))
+        return [];
+    const rawMappings = verification.mappings;
+    if (!Array.isArray(rawMappings))
+        return [];
+    return rawMappings.flatMap((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return [];
+        const dod = typeof item.dod === 'string' ? String(item.dod) : '';
+        const test = typeof item.test === 'string' ? String(item.test) : '';
+        const sanitized = sanitizeVerificationMapping({ dod, test });
+        return sanitized ? [sanitized] : [];
+    });
+}
 export function collectEvidence(paths, params) {
     ensureBaseState(paths);
     const task = loadTask(paths, params.taskId);
@@ -72,6 +95,18 @@ export function collectEvidence(paths, params) {
         extracted.toolResults = [...params.toolResults];
     if (params.notes)
         extracted.notes = params.notes;
+    const dodItems = (params.dodItems ?? []).map((item) => item.trim()).filter(Boolean);
+    const testCases = (params.testCases ?? []).map((item) => item.trim()).filter(Boolean);
+    const verificationMappings = (params.verificationMappings ?? [])
+        .map((mapping) => sanitizeVerificationMapping(mapping))
+        .filter((mapping) => Boolean(mapping));
+    if (dodItems.length || testCases.length || verificationMappings.length) {
+        extracted.verification = {
+            dodItems,
+            testCases,
+            mappings: verificationMappings,
+        };
+    }
     const outDir = path.join(paths.evidenceDir, params.taskId);
     fs.mkdirSync(outDir, { recursive: true });
     const outPath = path.join(outDir, `${params.agentId}.json`);
@@ -111,14 +146,54 @@ export function mergeEvidence(paths, params) {
     const qaAgentId = resolveQaAgentId(task);
     const qaPresent = qaAgentId ? presentAgents.includes(qaAgentId) : false;
     const qaRequiredSatisfied = !(params.requireQa ?? false) || (qaAgentId !== null && qaPresent);
-    const complete = missingAgents.length === 0 && qaRequiredSatisfied;
-    const merged = { ts: nowIso(), taskId: params.taskId, requiredAgents, presentAgents, missingAgents, qaAgentId, qaPresent, complete, items };
+    const qaVerificationMappings = qaAgentId
+        ? items
+            .filter((item) => String(item.agentId) === qaAgentId)
+            .flatMap((item) => collectVerificationMappings(item.evidence))
+        : [];
+    const qaVerification = {
+        required: Boolean(params.requireQa),
+        mappingCount: qaVerificationMappings.length,
+        mappings: qaVerificationMappings,
+        complete: !(params.requireQa ?? false) || !qaPresent || qaVerificationMappings.length > 0,
+    };
+    const complete = missingAgents.length === 0 && qaRequiredSatisfied && qaVerification.complete;
+    const merged = {
+        ts: nowIso(),
+        taskId: params.taskId,
+        requiredAgents,
+        presentAgents,
+        missingAgents,
+        qaAgentId,
+        qaPresent,
+        qaVerification,
+        complete,
+        items,
+    };
     const outPath = path.join(taskDir, '_merged.json');
     fs.writeFileSync(outPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
     appendEvent(paths.eventsFile, {
         event: 'evidence_merged', taskId: params.taskId, phase: 'verification', actor: 'zigrix', status: complete ? 'DONE_PENDING_REPORT' : 'IN_PROGRESS',
-        payload: { requiredAgents, missingAgents, complete, mergedPath: outPath, qaPresent },
+        payload: {
+            requiredAgents,
+            missingAgents,
+            complete,
+            mergedPath: outPath,
+            qaPresent,
+            qaVerificationComplete: qaVerification.complete,
+            qaVerificationMappingCount: qaVerification.mappingCount,
+        },
     });
     rebuildIndex(paths);
-    return { ok: true, taskId: params.taskId, complete, missingAgents, qaAgentId, qaPresent, mergedPath: outPath };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        complete,
+        missingAgents,
+        qaAgentId,
+        qaPresent,
+        qaVerificationComplete: qaVerification.complete,
+        qaVerificationMappingCount: qaVerification.mappingCount,
+        mergedPath: outPath,
+    };
 }

package/dist/orchestration/pipeline.d.ts

@@ -5,6 +5,7 @@ export declare function runPipeline(paths: ZigrixPaths, params: {
     scale?: string;
     requiredAgents?: string[];
     evidenceSummaries?: string[];
+    verificationMappings?: string[];
     requireQa?: boolean;
     autoReport?: boolean;
     recordFeedback?: boolean;

package/dist/orchestration/pipeline.js

@@ -7,11 +7,36 @@ export function runPipeline(paths, params) {
     const taskId = task.taskId;
     steps.push({ step: 'task_create', result: task });
     steps.push({ step: 'task_start', result: updateTaskStatus(paths, taskId, 'IN_PROGRESS') });
+    const verificationMappings = new Map();
+    for (const raw of params.verificationMappings ?? []) {
+        if (!raw.includes('='))
+            throw new Error(`invalid verification mapping format: ${raw} (expected agentId=dod=test)`);
+        const [agentId, rest] = raw.split(/=(.*)/s, 2);
+        const trimmedAgentId = agentId.trim();
+        const [dod, test] = (rest ?? '').split(/=(.*)/s, 2);
+        if (!trimmedAgentId || !dod?.trim() || !test?.trim()) {
+            throw new Error(`invalid verification mapping format: ${raw} (expected agentId=dod=test)`);
+        }
+        verificationMappings.set(trimmedAgentId, [
+            ...(verificationMappings.get(trimmedAgentId) ?? []),
+            { dod: dod.trim(), test: test.trim() },
+        ]);
+    }
     for (const raw of params.evidenceSummaries ?? []) {
         if (!raw.includes('='))
             throw new Error(`invalid evidence summary format: ${raw} (expected agentId=summary)`);
         const [agentId, summary] = raw.split(/=(.*)/s, 2);
-        steps.push({ step: 'evidence_collect', agentId: agentId.trim(), result: collectEvidence(paths, { taskId, agentId: agentId.trim(), summary: summary.trim() }) });
+        const trimmedAgentId = agentId.trim();
+        steps.push({
+            step: 'evidence_collect',
+            agentId: trimmedAgentId,
+            result: collectEvidence(paths, {
+                taskId,
+                agentId: trimmedAgentId,
+                summary: summary.trim(),
+                verificationMappings: verificationMappings.get(trimmedAgentId) ?? [],
+            }),
+        });
     }
     const merged = mergeEvidence(paths, { taskId, requiredAgents: params.requiredAgents, requireQa: params.requireQa });
     steps.push({ step: 'evidence_merge', result: merged });

package/dist/state/tasks.d.ts

@@ -40,6 +40,36 @@ export type ZigrixTask = {
     qaAgentId?: string;
     orchestratorSessionKey?: string;
     orchestratorSessionId?: string;
+    nextAction?: string;
+    resumeHint?: string;
+    staleReason?: string;
+    staleReasons?: string[];
+};
+export type StaleReasonCode = 'stale_timeout' | 'session_dead' | 'missing_session_mapping';
+export type SessionDiagnosis = {
+    scope: 'orchestrator' | 'worker';
+    agentId: string;
+    sessionKey: string;
+    sessionId: string | null;
+    mappingSource: 'explicit' | 'parsed' | 'sessions_json' | 'none';
+    state: 'active' | 'deleted' | 'missing';
+    reason: 'session_dead' | 'missing_session_mapping' | null;
+    activePath: string | null;
+    deletedPath: string | null;
+};
+export type StaleTaskSummary = {
+    taskId: string;
+    title: string;
+    updatedAt: string;
+    hoursThreshold: number;
+    timedOut: boolean;
+    reason: string;
+    reasonCode: StaleReasonCode;
+    reasons: StaleReasonCode[];
+    nextAction: string;
+    resumeHint: string;
+    reportLine: string;
+    sessions: SessionDiagnosis[];
 };
 export declare function resolveTaskPaths(paths: ZigrixPaths, taskId: string): {
     specPath: string;
@@ -68,6 +98,11 @@ export declare function recordTaskProgress(paths: ZigrixPaths, params: {
     unitId?: string;
     workPackage?: string;
 }): Record<string, unknown> | null;
-export declare function findStaleTasks(paths: ZigrixPaths, hours?: number): ZigrixTask[];
-export declare function applyStalePolicy(paths: ZigrixPaths, hours?: number, reason?: string): Record<string, unknown>;
+type StalePolicyOptions = {
+    agentsStateDir?: string | null;
+    fallbackReason?: string;
+};
+export declare function findStaleTasks(paths: ZigrixPaths, hours?: number, options?: StalePolicyOptions): StaleTaskSummary[];
+export declare function applyStalePolicy(paths: ZigrixPaths, hours?: number, reason?: string, options?: StalePolicyOptions): Record<string, unknown>;
 export declare function rebuildIndex(paths: ZigrixPaths): Record<string, unknown>;
+export {};